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

/// A value to indicate which type of subsystem an Actor connection represents. The Controller may
/// leverage this extra information to thermally limit only specific subsystems as needed.
enum ActorType {
    UNSPECIFIED = 1;
    AUDIO = 2;
};

/// Error codes for the thermal protocol.
enum Error {
    /// The component encountered an unspecified error while performing the operation.
    INTERNAL = 1;

    /// At least one argument was invalid.
    INVALID_ARGUMENTS = 2;
};

/// The maximum number of trip points that may be specified in the `trip_points` vector argument to
/// `Subscribe`.
const uint32 MAX_TRIP_POINT_COUNT = 100;

/// The maximum value of the normalized thermal load. This value bounds the width (and therefore
/// also the precision) of the normalized thermal limiting range starting from 0. Trip points must
/// be specified within this range.
const uint32 MAX_THERMAL_LOAD = 100;

/// Configuration for a single trip point. The trip point will be activated when the thermal load
/// is greater than or equal to `activate_at`, and deactivated when it is less than
/// `deactivate_below`.
///
/// See [fuchsia.thermal/Controller.Subscribe] for the relationship between trip points and thermal
/// states.
struct TripPoint {
    /// The trip point will be deactivated when thermal load drops below this value.
    uint32 deactivate_below;

    /// The trip point will be activated when thermal load is greater than or equal to this value.
    uint32 activate_at;
};

/// A protocol providing the API for a client service to subscribe to receive thermal state updates.
[Discoverable]
protocol Controller {
    /// Subscribes with the Controller to receive thermal state changes on the specified
    /// [fuchsia.thermal/Actor] proxy handle.
    ///
    /// The current thermal state will be sent immediately, with all subsequent state changes
    /// occuring based on the changing system thermal load and specified `trip_points`.
    ///
    /// A TripPoint is activated when the thermal load is greater than or equal to its `activate_at`
    /// value and deactivated when the thermal load drops below its `deactivate_below` value. The
    /// Actor's thermal state is set to 1 greater than the index of the highest active trip point,
    /// or 0 if none are active.
    ///
    /// + request `actor` a [fuchsia.thermal/Actor] proxy to handle the SetThermalState callbacks
    /// + request `actor_type` a [fuchsia.thermal/ActorType] value to indicate the type of
    ///     subsystem this actor is representing. The Controller may leverage this extra
    ///     information to thermally limit only specific subsystems as needed.
    /// + request `trip_points` a vector of `TripPoint`s specifying when the Actor should be
    ///     transitioned between thermal states. The vector must:
    ///     - have length in the range [1 - MAX_TRIP_POINT_COUNT]
    ///     - elementwise satisfy `low` <= `high`
    ///     - be monotonically increasing: `high[i]` < `low[i+1]`
    ///     - elementwise have `low` and `high` values in the range [1 - MAX_THERMAL_LOAD]
    ///   Failure to meet these conditions will cause [fuchsia.thermal/Error].INVALID_ARGUMENTS to
    ///   be returned.
    /// * error a [fuchsia.thermal/Error] value indicating the reason (if any) that Subscribe failed
    Subscribe(Actor actor,
              ActorType actor_type,
              vector<TripPoint>:MAX_TRIP_POINT_COUNT trip_points) -> () error Error;
};

/// The protocol to receive thermal state updates from the fuchsia.thermal/Controller.
protocol Actor {
    /// Sets the Actor's thermal state.
    ///
    /// The Actor is expected to ACK each call before subsequent calls will be made. `state` is
    /// defined as an index into the Actor's reported thermal ranges. The Actor's thermal ranges
    /// are defined by dividing the normalized thermal limiting range [0 - `MAX_THERMAL_LOAD`] at
    /// the locations specified by the `trip_points` argument to Subscribe. `state` is therefore in
    /// the range [0 - len(trip_points)]. For each value of `state`, the subsystem should remain
    /// operational. The value of `state` should be interpreted as:
    ///     0: "normal operation"
    ///     1..[len(trip_points) - 1]: The subsystem is operating in such a way that each state
    ///                                produces less heat than the previous state
    ///     len(trip_points): max thermal limiting while still operational
    ///
    /// As a simple example, consider that Subscribe was called with a vector of two trip points:
    /// [50, 90]. We can think of these trip points as boundaries within the normalized range
    /// [0 - `MAX_THERMAL_LOAD`] such that three thermal ranges are created: [0 - 49], [50 - 89],
    /// and [90 - `MAX_THERMAL_LOAD`]. Now, as the Controller observes the system thermal load
    /// increase through the normalized range, it calls SetThermalState at the specified trip
    /// points and indicates the index of which thermal range is now active. In this example, the
    /// Controller would initially call `SetThermalState(0)` when there is no thermal limiting
    /// required. As the device heats up, the Controller would call `SetThermalState(1)` and finally
    /// `SetThermalState(2)` as the Controller observes the system thermal load cross 50 and 90,
    /// respectively.
    ///
    /// + request `state` the new thermal state as an index into the Actor's reported thermal
    ///     ranges, which are defined based on the Actor's specified `trip_points`.
    SetThermalState(uint32 state) -> ();
};