blob: 0b57e9376d7ea882dd6f6ba8848ad694a5b87a9c [file] [log] [blame]
Chris Ye1a5a8882020-01-15 10:51:47 -08001/*
2 * Copyright (C) 2020 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/**
18 * @addtogroup Thermal
19 * @{
20 */
21
22/**
23 * @file thermal.h
24 */
25
26#ifndef _ANDROID_THERMAL_H
27#define _ANDROID_THERMAL_H
28
29#include <sys/cdefs.h>
30
31/******************************************************************
32 *
33 * IMPORTANT NOTICE:
34 *
35 * This file is part of Android's set of stable system headers
36 * exposed by the Android NDK (Native Development Kit).
37 *
38 * Third-party source AND binary code relies on the definitions
39 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
40 *
41 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
42 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
43 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
44 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
45 */
46
47/*
48 * Structures and functions to access thermal status and register/unregister
49 * thermal status listener in native code.
50 */
51
52#include <stdint.h>
53#include <sys/types.h>
54
55#if !defined(__INTRODUCED_IN)
Chris Forbes56e925a2020-09-15 09:34:59 -070056#define __INTRODUCED_IN(__api_level) /* nothing */
Chris Ye1a5a8882020-01-15 10:51:47 -080057#endif
58
59#ifdef __cplusplus
60extern "C" {
61#endif
62
gfan5d5faa42021-04-12 15:14:29 -070063/**
64 * Thermal status used in function {@link AThermal_getCurrentThermalStatus} and
65 * {@link AThermal_StatusCallback}.
66 */
Chris Ye1a5a8882020-01-15 10:51:47 -080067enum AThermalStatus {
68 /** Error in thermal status. */
69 ATHERMAL_STATUS_ERROR = -1,
70 /** Not under throttling. */
71 ATHERMAL_STATUS_NONE = 0,
72 /** Light throttling where UX is not impacted. */
73 ATHERMAL_STATUS_LIGHT = 1,
74 /** Moderate throttling where UX is not largely impacted. */
75 ATHERMAL_STATUS_MODERATE = 2,
76 /** Severe throttling where UX is largely impacted. */
77 ATHERMAL_STATUS_SEVERE = 3,
78 /** Platform has done everything to reduce power. */
79 ATHERMAL_STATUS_CRITICAL = 4,
80 /**
81 * Key components in platform are shutting down due to thermal condition.
82 * Device functionalities will be limited.
83 */
84 ATHERMAL_STATUS_EMERGENCY = 5,
85 /** Need shutdown immediately. */
86 ATHERMAL_STATUS_SHUTDOWN = 6,
87};
88
89/**
90 * An opaque type representing a handle to a thermal manager.
91 * An instance of thermal manager must be acquired prior to
92 * using thermal status APIs and must be released after use.
93 *
94 * <p>To use:<ul>
95 * <li>Create a new thermal manager instance by calling the
96 * {@link AThermal_acquireManager} function.</li>
97 * <li>Get current thermal status with
98 * {@link AThermal_getCurrentThermalStatus}.</li>
99 * <li>Register a thermal status listener with
100 * {@link AThermal_registerThermalStatusListener}.</li>
101 * <li>Unregister a thermal status listener with
102 * {@link AThermal_unregisterThermalStatusListener}.</li>
103 * <li>Release the thermal manager instance with
104 * {@link AThermal_releaseManager}.</li></ul></p>
105 *
106 */
107typedef struct AThermalManager AThermalManager;
108
109/**
110 * Prototype of the function that is called when thermal status changes.
111 * It's passed the updated thermal status as parameter, as well as the
112 * pointer provided by the client that registered a callback.
113 */
Xiang Wange6c65b32023-10-09 13:39:37 -0700114typedef void (*AThermal_StatusCallback)(void* data, AThermalStatus status);
Chris Ye1a5a8882020-01-15 10:51:47 -0800115
116/**
117 * Acquire an instance of the thermal manager. This must be freed using
118 * {@link AThermal_releaseManager}.
119 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700120 * Available since API level 30.
121 *
Chris Ye1a5a8882020-01-15 10:51:47 -0800122 * @return manager instance on success, nullptr on failure.
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700123 */
124AThermalManager* AThermal_acquireManager() __INTRODUCED_IN(30);
Chris Ye1a5a8882020-01-15 10:51:47 -0800125
126/**
127 * Release the thermal manager pointer acquired via
128 * {@link AThermal_acquireManager}.
129 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700130 * Available since API level 30.
Chris Ye1a5a8882020-01-15 10:51:47 -0800131 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700132 * @param manager The manager to be released.
Chris Ye1a5a8882020-01-15 10:51:47 -0800133 */
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700134void AThermal_releaseManager(AThermalManager *manager) __INTRODUCED_IN(30);
Chris Ye1a5a8882020-01-15 10:51:47 -0800135
136/**
137 * Gets the current thermal status.
138 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700139 * Available since API level 30.
140 *
Chris Ye1a5a8882020-01-15 10:51:47 -0800141 * @param manager The manager instance to use to query the thermal status.
142 * Acquired via {@link AThermal_acquireManager}.
143 *
144 * @return current thermal status, ATHERMAL_STATUS_ERROR on failure.
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700145 */
146AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager) __INTRODUCED_IN(30);
Chris Ye1a5a8882020-01-15 10:51:47 -0800147
148/**
149 * Register the thermal status listener for thermal status change.
150 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700151 * Available since API level 30.
152 *
Chris Ye1a5a8882020-01-15 10:51:47 -0800153 * @param manager The manager instance to use to register.
154 * Acquired via {@link AThermal_acquireManager}.
155 * @param callback The callback function to be called when thermal status updated.
156 * @param data The data pointer to be passed when callback is called.
157 *
158 * @return 0 on success
159 * EINVAL if the listener and data pointer were previously added and not removed.
160 * EPERM if the required permission is not held.
161 * EPIPE if communication with the system service has failed.
162 */
163int AThermal_registerThermalStatusListener(AThermalManager *manager,
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700164 AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30);
Chris Ye1a5a8882020-01-15 10:51:47 -0800165
166/**
167 * Unregister the thermal status listener previously resgistered.
168 *
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700169 * Available since API level 30.
170 *
Chris Ye1a5a8882020-01-15 10:51:47 -0800171 * @param manager The manager instance to use to unregister.
172 * Acquired via {@link AThermal_acquireManager}.
173 * @param callback The callback function to be called when thermal status updated.
174 * @param data The data pointer to be passed when callback is called.
175 *
176 * @return 0 on success
177 * EINVAL if the listener and data pointer were not previously added.
178 * EPERM if the required permission is not held.
179 * EPIPE if communication with the system service has failed.
180 */
181int AThermal_unregisterThermalStatusListener(AThermalManager *manager,
Elliott Hughes7be0e2d2020-06-02 13:05:04 -0700182 AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30);
Chris Ye1a5a8882020-01-15 10:51:47 -0800183
Chris Forbes56e925a2020-09-15 09:34:59 -0700184/**
185 * Provides an estimate of how much thermal headroom the device currently has before
186 * hitting severe throttling.
187 *
188 * Note that this only attempts to track the headroom of slow-moving sensors, such as
189 * the skin temperature sensor. This means that there is no benefit to calling this function
190 * more frequently than about once per second, and attempted to call significantly
Elliott Hughesd4b452c2023-09-15 22:52:03 +0000191 * more frequently may result in the function returning `NaN`.
Chris Forbes56e925a2020-09-15 09:34:59 -0700192 *
193 * In addition, in order to be able to provide an accurate forecast, the system does
194 * not attempt to forecast until it has multiple temperature samples from which to
195 * extrapolate. This should only take a few seconds from the time of the first call,
196 * but during this time, no forecasting will occur, and the current headroom will be
Elliott Hughesd4b452c2023-09-15 22:52:03 +0000197 * returned regardless of the value of `forecastSeconds`.
Chris Forbes56e925a2020-09-15 09:34:59 -0700198 *
199 * The value returned is a non-negative float that represents how much of the thermal envelope
200 * is in use (or is forecasted to be in use). A value of 1.0 indicates that the device is
gfan5d5faa42021-04-12 15:14:29 -0700201 * (or will be) throttled at {@link #ATHERMAL_STATUS_SEVERE}. Such throttling can affect the
Chris Forbes56e925a2020-09-15 09:34:59 -0700202 * CPU, GPU, and other subsystems. Values may exceed 1.0, but there is no implied mapping
203 * to specific thermal levels beyond that point. This means that values greater than 1.0
gfan5d5faa42021-04-12 15:14:29 -0700204 * may correspond to {@link #ATHERMAL_STATUS_SEVERE}, but may also represent heavier throttling.
Chris Forbes56e925a2020-09-15 09:34:59 -0700205 *
206 * A value of 0.0 corresponds to a fixed distance from 1.0, but does not correspond to any
207 * particular thermal status or temperature. Values on (0.0, 1.0] may be expected to scale
208 * linearly with temperature, though temperature changes over time are typically not linear.
209 * Negative values will be clamped to 0.0 before returning.
210 *
211 * Available since API level 31.
212 *
213 * @param manager The manager instance to use.
214 * Acquired via {@link AThermal_acquireManager}.
215 * @param forecastSeconds how many seconds into the future to forecast. Given that device
216 * conditions may change at any time, forecasts from further in the
217 * future will likely be less accurate than forecasts in the near future.
218 * @return a value greater than equal to 0.0, where 1.0 indicates the SEVERE throttling threshold,
219 * as described above. Returns NaN if the device does not support this functionality or
220 * if this function is called significantly faster than once per second.
221 */
222float AThermal_getThermalHeadroom(AThermalManager *manager,
223 int forecastSeconds) __INTRODUCED_IN(31);
224
Xiang Wange6c65b32023-10-09 13:39:37 -0700225/**
226 * This struct defines an instance of headroom threshold value and its status.
227 * <p>
228 * The value should be monotonically non-decreasing as the thermal status increases.
229 * For {@link ATHERMAL_STATUS_SEVERE}, its headroom threshold is guaranteed to
230 * be 1.0f. For status below severe status, the value should be lower or equal
231 * to 1.0f, and for status above severe, the value should be larger or equal to 1.0f.
232 * <p>
233 * Also see {@link AThermal_getThermalHeadroom} for explanation on headroom, and
234 * {@link AThermal_getThermalHeadroomThresholds} for how to use this.
235 */
236struct AThermalHeadroomThreshold {
237 float headroom;
238 AThermalStatus thermalStatus;
239};
240
241/**
242 * Gets the thermal headroom thresholds for all available thermal status.
243 *
244 * A thermal status will only exist in output if the device manufacturer has the
245 * corresponding threshold defined for at least one of its slow-moving skin temperature
246 * sensors. If it's set, one should also expect to get it from
247 * {@link #AThermal_getCurrentThermalStatus} or {@link AThermal_StatusCallback}.
248 * <p>
249 * The headroom threshold is used to interpret the possible thermal throttling status based on
250 * the headroom prediction. For example, if the headroom threshold for
251 * {@link ATHERMAL_STATUS_LIGHT} is 0.7, and a headroom prediction in 10s returns 0.75
252 * (or {@code AThermal_getThermalHeadroom(10)=0.75}), one can expect that in 10 seconds the system
253 * could be in lightly throttled state if the workload remains the same. The app can consider
254 * taking actions according to the nearest throttling status the difference between the headroom and
255 * the threshold.
256 * <p>
257 * For new devices it's guaranteed to have a single sensor, but for older devices with multiple
258 * sensors reporting different threshold values, the minimum threshold is taken to be conservative
259 * on predictions. Thus, when reading real-time headroom, it's not guaranteed that a real-time value
260 * of 0.75 (or {@code AThermal_getThermalHeadroom(0)}=0.75) exceeding the threshold of 0.7 above
261 * will always come with lightly throttled state
262 * (or {@code AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_LIGHT}) but it can be lower
263 * (or {@code AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_NONE}).
264 * While it's always guaranteed that the device won't be throttled heavier than the unmet
265 * threshold's state, so a real-time headroom of 0.75 will never come with
266 * {@link #ATHERMAL_STATUS_MODERATE} but always lower, and 0.65 will never come with
267 * {@link ATHERMAL_STATUS_LIGHT} but {@link #ATHERMAL_STATUS_NONE}.
268 * <p>
269 * The returned list of thresholds is cached on first successful query and owned by the thermal
270 * manager, which will not change between calls to this function. The caller should only need to
271 * free the manager with {@link AThermal_releaseManager}.
272 *
273 * @param manager The manager instance to use.
274 * Acquired via {@link AThermal_acquireManager}.
275 * @param outThresholds non-null output pointer to null AThermalHeadroomThreshold pointer, which
276 * will be set to the cached array of thresholds if thermal thresholds are supported
277 * by the system or device, otherwise nullptr or unmodified.
278 * @param size non-null output pointer whose value will be set to the size of the threshold array
279 * or 0 if it's not supported.
280 * @return 0 on success
281 * EINVAL if outThresholds or size_t is nullptr, or *outThresholds is not nullptr.
282 * EPIPE if communication with the system service has failed.
283 * ENOSYS if the feature is disabled by the current system.
284 */
285int AThermal_getThermalHeadroomThresholds(AThermalManager* manager,
286 const AThermalHeadroomThreshold ** outThresholds,
287 size_t* size) __INTRODUCED_IN(35);
288
Chris Ye1a5a8882020-01-15 10:51:47 -0800289#ifdef __cplusplus
290}
291#endif
292
293#endif // _ANDROID_THERMAL_H
294
295/** @} */