blob: 76ee19203e26aa4c63bac288abeb40f3204d625c [file] [log] [blame]
// 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.
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
type ActorType = strict enum {
UNSPECIFIED = 1;
AUDIO = 2;
};
/// Error codes for the thermal protocol.
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
type Error = strict enum {
/// 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`.
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
const MAX_TRIP_POINT_COUNT uint32 = 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 MAX_THERMAL_LOAD uint32 = 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.
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
type TripPoint = struct {
/// The trip point will be deactivated when thermal load drops below this value.
deactivate_below uint32;
/// The trip point will be activated when thermal load is greater than or equal to this value.
activate_at uint32;
};
/// A protocol providing the API for a client service to subscribe to receive thermal state updates.
@discoverable
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
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(resource struct {
actor client_end:Actor;
actor_type ActorType;
trip_points vector<TripPoint>:MAX_TRIP_POINT_COUNT;
}) -> (struct {}) error Error;
};
/// The protocol to receive thermal state updates from the fuchsia.thermal/Controller.
@available(
deprecated=7,
removed=8,
note="fuchsia.thermal.Controller and supporting protocols/types replaced by fuchsia.thermal.ClientStateWatcher")
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(struct {
state uint32;
}) -> ();
};