// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.hardware.thermal;

using zx;
using fuchsia.hardware.fan;
using fuchsia.hardware.temperature;

/// The maximum number of trip points that can be used.
const MAX_TRIP_POINTS uint32 = 16;

/// The maximum number of DVFS domains a device can support (one for each cluster in a big-little
/// architecture).
const MAX_DVFS_DOMAINS uint32 = 2;

/// The maximum number of operating points that can be used.
const MAX_DVFS_OPPS uint32 = 16;

/// Bitmask values for ThermalInfo.state.
const THERMAL_STATE_NORMAL uint32 = 0;
const THERMAL_STATE_TRIP_VIOLATION uint32 = 1;

/// Devices with big-little architecture may have different operating points for each cluster.
/// Other devices use `BIG_CLUSTER_POWER_DOMAIN` for getting/setting the operating point.
type PowerDomain = strict enum : uint32 {
    BIG_CLUSTER_POWER_DOMAIN = 0;
    LITTLE_CLUSTER_POWER_DOMAIN = 1;
};

/// scpi_opp_t is typedef'd to this.
type OperatingPoint = struct {
    /// The device's operating points.
    opp array<OperatingPointEntry, MAX_DVFS_OPPS>;
    /// In microseconds.
    latency uint32;
    /// The number of operating points in opp.
    count uint32;
};

/// scpi_opp_entry_t is typedef'd to this.
type OperatingPointEntry = struct {
    /// The operating point frequency in Hz.
    freq_hz uint32;
    /// The operating point voltage in microvolts.
    volt_uv uint32;
};

/// Temperature units are degrees Celsius.
type ThermalInfo = struct {
    /// State is a bitmask of `THERMAL_STATE_`* values.
    state uint32;
    /// The sensor temperature at which the system should activate passive cooling policy.
    passive_temp_celsius float32;
    /// The sensor temperature at which the system should perform critical shutdown.
    critical_temp_celsius float32;
    /// The number of trip points supported.
    max_trip_count uint32;
    /// The currently active trip point.
    active_trip array<float32, MAX_TRIP_POINTS>;
};

/// Temperature units are degrees Celsius.
type ThermalTemperatureInfo = struct {
    /// The temperature must rise to up_temp to get to this trip point.
    up_temp_celsius float32;
    /// The temperature must fall to down_temp to get to this trip point.
    down_temp_celsius float32;
    /// The fan level for this trip point.
    fan_level uint32;
    /// The operating point index of the big cluster.
    big_cluster_dvfs_opp uint16;
    /// The operating point index of the little cluster.
    little_cluster_dvfs_opp uint16;
    /// The GPU clock source index.
    gpu_clk_freq_source uint32;
};

type ThermalDeviceInfo = struct {
    /// Active cooling support.
    active_cooling bool;
    /// Passive cooling support.
    passive_cooling bool;
    /// GPU throttling support.
    gpu_throttling bool;
    /// Number of trip points.
    num_trip_points uint32;
    /// Big-little architecture.
    big_little bool;
    /// Critical temperature in degrees Celsius.
    critical_temp_celsius float32;
    /// Trip point information.
    trip_point_info array<ThermalTemperatureInfo, MAX_TRIP_POINTS>;
    /// Operating point information.
    opps array<OperatingPoint, MAX_DVFS_DOMAINS>;
};

@deprecated
closed protocol Device {
    compose fuchsia.hardware.fan.Fan;
    compose fuchsia.hardware.temperature.Device;

    /// Get information about the device's current state.
    strict GetInfo() -> (struct {
        status zx.Status;
        info box<ThermalInfo>;
    });

    /// Get information about the device's thermal capabilities and trip points.
    strict GetDeviceInfo() -> (struct {
        status zx.Status;
        info box<ThermalDeviceInfo>;
    });

    /// Get the device's operating points.
    /// TODO(bradenkell): Can this be removed? GetDeviceInfo() provides the same information.
    strict GetDvfsInfo(struct {
        power_domain PowerDomain;
    }) -> (struct {
        status zx.Status;
        info box<OperatingPoint>;
    });

    /// Get an event to get trip point notifications on. `ZX_USER_SIGNAL_`0 is changed when either
    /// trip point is reached. It is deasserted when the state is read via GetInfo.
    strict GetStateChangeEvent() -> (resource struct {
        status zx.Status;
        handle zx.Handle:<EVENT, optional>;
    });

    /// Get a port to get trip point notification packets.
    strict GetStateChangePort() -> (resource struct {
        status zx.Status;
        handle zx.Handle:<PORT, optional>;
    });

    /// Sets a trip point in degrees Celsius. When the sensor reaches the trip point temperature the
    /// device will notify on an event.
    strict SetTripCelsius(struct {
        id uint32;
        temp float32;
    }) -> (struct {
        status zx.Status;
    });

    /// Get the current operating point index.
    strict GetDvfsOperatingPoint(struct {
        power_domain PowerDomain;
    }) -> (struct {
        status zx.Status;
        op_idx uint16;
    });

    /// Set the operating point index.
    strict SetDvfsOperatingPoint(struct {
        op_idx uint16;
        power_domain PowerDomain;
    }) -> (struct {
        status zx.Status;
    });
};