// 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.temperature;

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

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

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

/// Bitmask values for ThermalInfo.state.
const uint32 THERMAL_STATE_NORMAL = 0;
const uint32 THERMAL_STATE_TRIP_VIOLATION = 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.
enum PowerDomain : uint32 {
    BIG_CLUSTER_POWER_DOMAIN = 0;
    LITTLE_CLUSTER_POWER_DOMAIN = 1;
};

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

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

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

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

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

[ForDeprecatedCBindings]
protocol Device {
    compose fuchsia.hardware.temperature.Device;

    /// Get information about the device's current state.
    GetInfo() -> (zx.status status, ThermalInfo? info);

    /// Get information about the device's thermal capabilities and trip points.
    GetDeviceInfo() -> (zx.status status, ThermalDeviceInfo? info);

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

    /// 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.
    GetStateChangeEvent() -> (zx.status status, zx.handle:EVENT? handle);

    /// Get a port to get trip point notification packets.
    GetStateChangePort() -> (zx.status status, zx.handle:PORT? handle);

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

    /// Get the current operating point index.
    GetDvfsOperatingPoint(PowerDomain power_domain) -> (zx.status status, uint16 op_idx);

    /// Set the operating point index.
    SetDvfsOperatingPoint(uint16 op_idx, PowerDomain power_domain) -> (zx.status status);

    /// Get the current fan level.
    GetFanLevel() -> (zx.status status, uint32 fan_level);

    /// Set the fan level.
    SetFanLevel(uint32 fan_level) -> (zx.status status);
};