Thermal

Summary

Enumerations
AThermalStatus{
  ATHERMAL_STATUS_ERROR = -1,
  ATHERMAL_STATUS_NONE = 0,
  ATHERMAL_STATUS_LIGHT = 1,
  ATHERMAL_STATUS_MODERATE = 2,
  ATHERMAL_STATUS_SEVERE = 3,
  ATHERMAL_STATUS_CRITICAL = 4,
  ATHERMAL_STATUS_EMERGENCY = 5,
  ATHERMAL_STATUS_SHUTDOWN = 6
} 		enum
Thermal status used in function AThermal_getCurrentThermalStatus and AThermal_StatusCallback.

Typedefs
AThermalHeadroomThreshold typedef
AThermalManager typedef
An opaque type representing a handle to a thermal manager.
AThermalStatus typedef
AThermal_StatusCallback)(void *_Nullable data, AThermalStatus status) typedef
void(*
Prototype of the function that is called when thermal status changes.

Functions
AThermal_acquireManager()
AThermalManager *_Nonnull
Acquire an instance of the thermal manager.
AThermal_getCurrentThermalStatus(AThermalManager *_Nonnull manager)
Gets the current thermal status.
AThermal_getThermalHeadroom(AThermalManager *_Nonnull manager, int forecastSeconds)
float
Provides an estimate of how much thermal headroom the device currently has before hitting severe throttling.
AThermal_getThermalHeadroomThresholds(AThermalManager *_Nonnull manager, const AThermalHeadroomThreshold *_Nonnull *_Nullable outThresholds, size_t *_Nonnull size)
int
Gets the thermal headroom thresholds for all available thermal status.
AThermal_registerThermalStatusListener(AThermalManager *_Nonnull manager, AThermal_StatusCallback _Nullable callback, void *_Nullable data)
int
Register the thermal status listener for thermal status change.
AThermal_releaseManager(AThermalManager *_Nonnull manager)
void
Release the thermal manager pointer acquired via AThermal_acquireManager.
AThermal_unregisterThermalStatusListener(AThermalManager *_Nonnull manager, AThermal_StatusCallback _Nullable callback, void *_Nullable data)
int
Unregister the thermal status listener previously resgistered.

Structs
AThermalHeadroomThreshold

This struct defines an instance of headroom threshold value and its status.

Enumerations

AThermalStatus

Declared in android/thermal.h 
 AThermalStatus

Thermal status used in function AThermal_getCurrentThermalStatus and AThermal_StatusCallback.

Properties
ATHERMAL_STATUS_CRITICAL

Platform has done everything to reduce power.

ATHERMAL_STATUS_EMERGENCY

Key components in platform are shutting down due to thermal condition.

Device functionalities will be limited.

ATHERMAL_STATUS_ERROR

Error in thermal status.

ATHERMAL_STATUS_LIGHT

Light throttling where UX is not impacted.

ATHERMAL_STATUS_MODERATE

Moderate throttling where UX is not largely impacted.

ATHERMAL_STATUS_NONE

Not under throttling.

ATHERMAL_STATUS_SEVERE

Severe throttling where UX is largely impacted.

ATHERMAL_STATUS_SHUTDOWN

Need shutdown immediately.

Typedefs

AThermalHeadroomThreshold

Declared in android/thermal.h 
struct AThermalHeadroomThreshold AThermalHeadroomThreshold

AThermalManager

Declared in android/thermal.h 
struct AThermalManager AThermalManager

An opaque type representing a handle to a thermal manager.

An instance of thermal manager must be acquired prior to using thermal status APIs and must be released after use.

To use:

AThermalStatus

Declared in android/thermal.h 
enum AThermalStatus AThermalStatus

AThermal_StatusCallback

Declared in android/thermal.h 
void(* AThermal_StatusCallback)(void *_Nullable data, AThermalStatus status)

Prototype of the function that is called when thermal status changes.

It's passed the updated thermal status as parameter, as well as the pointer provided by the client that registered a callback.

Functions

AThermal_acquireManager

Declared in android/thermal.h 
AThermalManager *_Nonnull AThermal_acquireManager()

Acquire an instance of the thermal manager.

This must be freed using AThermal_releaseManager.

Available since API level 30.

Details
Returns
manager instance on success, nullptr on failure.

AThermal_getCurrentThermalStatus

Declared in android/thermal.h 
AThermalStatus AThermal_getCurrentThermalStatus(
  AThermalManager *_Nonnull manager
)

Gets the current thermal status.

Available since API level 30.

Details
Parameters
manager
The manager instance to use to query the thermal status. Acquired via AThermal_acquireManager.
Returns
current thermal status, ATHERMAL_STATUS_ERROR on failure.

AThermal_getThermalHeadroom

Declared in android/thermal.h 
float AThermal_getThermalHeadroom(
  AThermalManager *_Nonnull manager,
  int forecastSeconds
)

Provides an estimate of how much thermal headroom the device currently has before hitting severe throttling.

Note that this only attempts to track the headroom of slow-moving sensors, such as the skin temperature sensor. This means that there is no benefit to calling this function more frequently than about once per second, and attempted to call significantly more frequently may result in the function returning NaN.

In addition, in order to be able to provide an accurate forecast, the system does not attempt to forecast until it has multiple temperature samples from which to extrapolate. This should only take a few seconds from the time of the first call, but during this time, no forecasting will occur, and the current headroom will be returned regardless of the value of forecastSeconds.

The value returned is a non-negative float that represents how much of the thermal envelope is in use (or is forecasted to be in use). A value of 1.0 indicates that the device is (or will be) throttled at ATHERMAL_STATUS_SEVERE. Such throttling can affect the CPU, GPU, and other subsystems. Values may exceed 1.0, but there is no implied mapping to specific thermal levels beyond that point. This means that values greater than 1.0 may correspond to ATHERMAL_STATUS_SEVERE, but may also represent heavier throttling.

A value of 0.0 corresponds to a fixed distance from 1.0, but does not correspond to any particular thermal status or temperature. Values on (0.0, 1.0] may be expected to scale linearly with temperature, though temperature changes over time are typically not linear. Negative values will be clamped to 0.0 before returning.

Available since API level 31.

Details
Parameters
manager
The manager instance to use. Acquired via AThermal_acquireManager.
forecastSeconds
how many seconds into the future to forecast. Given that device conditions may change at any time, forecasts from further in the future will likely be less accurate than forecasts in the near future.
Returns
a value greater than equal to 0.0, where 1.0 indicates the SEVERE throttling threshold, as described above. Returns NaN if the device does not support this functionality or if this function is called significantly faster than once per second.

AThermal_getThermalHeadroomThresholds

Declared in android/thermal.h 
int AThermal_getThermalHeadroomThresholds(
  AThermalManager *_Nonnull manager,
  const AThermalHeadroomThreshold *_Nonnull *_Nullable outThresholds,
  size_t *_Nonnull size
)

Gets the thermal headroom thresholds for all available thermal status.

A thermal status will only exist in output if the device manufacturer has the corresponding threshold defined for at least one of its slow-moving skin temperature sensors. If it's set, one should also expect to get it from AThermal_getCurrentThermalStatus or AThermal_StatusCallback.

The headroom threshold is used to interpret the possible thermal throttling status based on the headroom prediction. For example, if the headroom threshold for ATHERMAL_STATUS_LIGHT is 0.7, and a headroom prediction in 10s returns 0.75 (or AThermal_getThermalHeadroom(10)=0.75), one can expect that in 10 seconds the system could be in lightly throttled state if the workload remains the same. The app can consider taking actions according to the nearest throttling status the difference between the headroom and the threshold.

For new devices it's guaranteed to have a single sensor, but for older devices with multiple sensors reporting different threshold values, the minimum threshold is taken to be conservative on predictions. Thus, when reading real-time headroom, it's not guaranteed that a real-time value of 0.75 (or AThermal_getThermalHeadroom(0)=0.75) exceeding the threshold of 0.7 above will always come with lightly throttled state (or AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_LIGHT) but it can be lower (or AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_NONE). While it's always guaranteed that the device won't be throttled heavier than the unmet threshold's state, so a real-time headroom of 0.75 will never come with ATHERMAL_STATUS_MODERATE but always lower, and 0.65 will never come with ATHERMAL_STATUS_LIGHT but ATHERMAL_STATUS_NONE.

The returned list of thresholds is cached on first successful query and owned by the thermal manager, which will not change between calls to this function. The caller should only need to free the manager with AThermal_releaseManager.

Details
Parameters
manager
The manager instance to use. Acquired via AThermal_acquireManager.
outThresholds
non-null output pointer to null AThermalHeadroomThreshold pointer, which will be set to the cached array of thresholds if thermal thresholds are supported by the system or device, otherwise nullptr or unmodified.
size
non-null output pointer whose value will be set to the size of the threshold array or 0 if it's not supported.
Returns
0 on success EINVAL if outThresholds or size_t is nullptr, or *outThresholds is not nullptr. EPIPE if communication with the system service has failed. ENOSYS if the feature is disabled by the current system.

AThermal_registerThermalStatusListener

Declared in android/thermal.h 
int AThermal_registerThermalStatusListener(
  AThermalManager *_Nonnull manager,
  AThermal_StatusCallback _Nullable callback,
  void *_Nullable data
)

Register the thermal status listener for thermal status change.

Available since API level 30.

Details
Parameters
manager
The manager instance to use to register. Acquired via AThermal_acquireManager.
callback
The callback function to be called when thermal status updated.
data
The data pointer to be passed when callback is called.
Returns
0 on success EINVAL if the listener and data pointer were previously added and not removed. EPERM if the required permission is not held. EPIPE if communication with the system service has failed.

AThermal_releaseManager

Declared in android/thermal.h 
void AThermal_releaseManager(
  AThermalManager *_Nonnull manager
)

Release the thermal manager pointer acquired via AThermal_acquireManager.

Available since API level 30.

Details
Parameters
manager
The manager to be released.

AThermal_unregisterThermalStatusListener

Declared in android/thermal.h 
int AThermal_unregisterThermalStatusListener(
  AThermalManager *_Nonnull manager,
  AThermal_StatusCallback _Nullable callback,
  void *_Nullable data
)

Unregister the thermal status listener previously resgistered.

Available since API level 30.

Details
Parameters
manager
The manager instance to use to unregister. Acquired via AThermal_acquireManager.
callback
The callback function to be called when thermal status updated.
data
The data pointer to be passed when callback is called.
Returns
0 on success EINVAL if the listener and data pointer were not previously added. EPERM if the required permission is not held. EPIPE if communication with the system service has failed.