Thermal mitigation

With the Android framework, device manufacturers and app developers can use thermal data to ensure a consistent user experience (UX) if a device begins to overheat. For example, when a system undergoes thermal stress, jobscheduler jobs get throttled and, if necessary, a framework thermal shutdown is initiated. Apps that receive thermal-stress notifications through a registered callback in the PowerManager class can gracefully adjust their UX.

Thermal HAL

Android 9 and lower use a polling interface defined in Thermal HAL 1.0 to get temperature readings. This HAL allowed the Android framework and other trusted clients, such as a device manufacturer's HAL, to read the current temperature and product-policy specific throttling and shutdown thresholds for each sensor through the same API.

Android 10 introduced a thermal system in the Android framework and a new version of the HAL, Thermal HAL 2.0, that abstracts the interface to the thermal subsystem hardware devices. The hardware interface includes temperature sensors and thermistors for the skin, battery, GPU, CPU, and USB port. The device skin temperature is the most important system to track to keep the device surface temperature within specified thermal limits.

Additionally, Thermal HAL 2.0 provides multiple clients with thermal sensor readings and associated severity levels to indicate thermal stress. The following figure shows two warning messages from the Android System UI. These messages are displayed when the IThermalEventListener callback interface for theUSB_PORT and SKIN sensors, respectively, reach the THERMAL_STATUS_EMERGENCY severity level.

Overheat warnings.

Figure 1. Overheat warnings.

The current temperatures are retrieved for the different types of thermal sensors through IThermal HAL. Each function call returns a status value of either SUCCESS or FAILURE. If SUCCESS is returned, the process continues. If FAILURE is returned, an error message, which must be human-readable, is sent to status.debugMessage.

In addition to being a polling interface that returns the current temperatures, you can use the callback IThermalChangedCallback (HIDL, Android 10 through 13) or IThermalChangedCallback (AIDL, Android 14 and higher) with the callback interface from thermal HAL clients, such as the framework’s thermal service. For example, RegisterIThermalChangedCallback and UnregisterIThermalChangedCallback to register or unregister severity-changed events. If the thermal severity of a given sensor has changed, notifyThrottling sends a thermal throttling event callback to thermal-event listeners.

In addition to thermal sensor information, a list of mitigated cooling devices is exposed in getCurrentCoolingDevices. This list's order is persistent, even if a cooling device has gone offline. Device manufacturers can use the list to collect statsd metrics.

For more information, see the Reference implementation.

While you can add your own extensions, you shouldn't disable the thermal mitigation function.

Thermal service

In Android 10 and higher, the thermal service in the framework provides constant monitoring using the various mitigation signals from Thermal HAL 2.0, and gives throttling severity feedback to its clients. These clients include internal components and Android apps. The service uses two binder callback interfaces, IThermalEventListener and IThermalStatusListener, exposed as callbacks. The former is for internal platform and device manufacturer use, and the latter is for Android apps.

Through the callback interfaces, a device’s current thermal status is retrievable as an integer value ranging from 0x00000000 (no throttling) to 0x00000006 (device shutdown). Only a trusted system service, such as an Android API or device manufacturer API, can access the detailed thermal sensor and thermal event information. The following figure provides a model of the thermal mitigation process flow in Android 10 and higher:

Thermal mitigation process flow in Android 10 and higher.

Figure 2. Thermal mitigation process flow in Android 10 and higher.

Device manufacturer guidelines

To report device temperature sensor and throttling status for Android 10 through 13, device manufacturers must implement the HIDL aspect of the Thermal HAL 2.0 (IThermal.hal).

To report device temperature sensor and throttling status for Android 14, device manufacturers must implement the AIDL aspect of the Thermal HAL 2.0 (IThermal.aidl).

Anything that throttles device performance, including battery power constraints, must be reported through the thermal HAL. To ensure this happens, put all sensors that might indicate a need for mitigation (based on status changes) into the thermal HAL, and report the severity of any mitigation actions taken. The temperature value returned from a sensor reading doesn’t have to be the actual temperature, as long as it accurately reflects the corresponding severity threshold. For example, you can pass different numerical values instead of your actual temperature threshold values, or you can build guardbanding into threshold specifications to provide hysteresis. However, the severity corresponding to that value must match what’s needed at that threshold. For example, you might decide to return 72°C as your critical temperature threshold, when the actual temperature is 65°C, and it corresponds to the critical severity you specified. The severity level must be accurate for best thermal framework functionality.

To read more about the threshold levels in the framework and how they correspond to mitigation actions, see Use thermal status codes.

Use thermal APIs

Apps can add and remove listeners, and access thermal status information through the PowerManager class. The IThermal interface provides all the functionality needed, including returning the thermal status values. The IThermal binder interface is wrapped as the OnThermalStatusChangedListener interface, which apps can use when registering or removing thermal status listeners.

The Android thermal APIs have both callback and polling methods for apps to be notified of the thermal severity levels through status codes, which are defined in the PowerManager class. The methods are:

getCurrentThermalStatus() returns the current thermal status of the device as an integer, unless the device is undergoing throttling.
addThermalStatusListener() adds a listener.
removeThermalStatusListener() removes a previously added listener.

Use thermal status codes

The thermal status codes translate to specific throttling levels, which you can use for gathering data and for designing an optimal UX. For example, apps might receive a status of 0x00000000 (THERMAL_STATUS_NONE), which might later change to 0x00000001 (THERMAL_STATUS_LIGHT). Marking the 0x00000000 state as t0, then measuring the time lapsed from status THERMAL_STATUS_NONE to status THERMAL_STATUS_LIGHT as t1 enables device manufacturers to design and test mitigation strategies for specific use cases. The following table outlines suggested ways to use the thermal status codes:

Thermal status code	Description and suggested use
`THERMAL_STATUS_NONE` (`0x00000000`)	No throttling. Use this status to implement protective actions, such as detecting the start of the time period (t0 to t1) from `THERMAL_STATUS_NONE` (`0`) to `THERMAL_STATUS_LIGHT` (`1`).
`THERMAL_STATUS_LIGHT` (`0x00000001`)	Light throttling, UX isn't impacted. Use gentle device mitigation for this stage. For example, skip boosting or using inefficient frequencies, but only on big cores.
`THERMAL_STATUS_MODERATE` (`0x00000002`)	Moderate throttling, UX isn't greatly impacted. Thermal mitigation impacts foreground activities, so apps should reduce power immediately.
`THERMAL_STATUS_SEVERE` (`0x00000003`)	Severe throttling; UX is largely impacted. In this stage, device thermal mitigation should limit the system capacity. This state might cause side effects, such as display jank and audio jitter.
`THERMAL_STATUS_CRITICAL` (`0x00000004`)	Platform has done everything to reduce power. The device thermal mitigation software has placed all components to run at their lowest capacity.
`THERMAL_STATUS_EMERGENCY` (`0x00000005`)	Key components in the platform are shutting down due to thermal conditions and device functionality is limited. This status code represents the last warning before device shutdown. In this state, some functions, such as the modem and cellular data, are turned off completely.
`THERMAL_STATUS_SHUTDOWN` (`0x00000006`)	Shut down immediately. Due to the severity of this stage, apps might not be able to receive this notification.

Device manufacturers must pass the VTS test for thermal HAL, and can use emul_temp from the kernel sysfs interface to simulate temperature changes.