1 /* 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) 56 #define __INTRODUCED_IN(__api_level) /* nothing */ 57 #endif 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /** 64 * Thermal status used in function {@link AThermal_getCurrentThermalStatus} and 65 * {@link AThermal_StatusCallback}. 66 */ 67 enum 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 */ 107 typedef 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 */ 114 typedef void (*AThermal_StatusCallback)(void *data, AThermalStatus status); 115 116 /** 117 * Acquire an instance of the thermal manager. This must be freed using 118 * {@link AThermal_releaseManager}. 119 * 120 * Available since API level 30. 121 * 122 * @return manager instance on success, nullptr on failure. 123 */ 124 AThermalManager* AThermal_acquireManager() __INTRODUCED_IN(30); 125 126 /** 127 * Release the thermal manager pointer acquired via 128 * {@link AThermal_acquireManager}. 129 * 130 * Available since API level 30. 131 * 132 * @param manager The manager to be released. 133 */ 134 void AThermal_releaseManager(AThermalManager *manager) __INTRODUCED_IN(30); 135 136 /** 137 * Gets the current thermal status. 138 * 139 * Available since API level 30. 140 * 141 * @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. 145 */ 146 AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager) __INTRODUCED_IN(30); 147 148 /** 149 * Register the thermal status listener for thermal status change. 150 * 151 * Available since API level 30. 152 * 153 * @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 */ 163 int AThermal_registerThermalStatusListener(AThermalManager *manager, 164 AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30); 165 166 /** 167 * Unregister the thermal status listener previously resgistered. 168 * 169 * Available since API level 30. 170 * 171 * @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 */ 181 int AThermal_unregisterThermalStatusListener(AThermalManager *manager, 182 AThermal_StatusCallback callback, void *data) __INTRODUCED_IN(30); 183 184 /** 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 191 * more frequently may result in the function returning {@code NaN}. 192 * 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 197 * returned regardless of the value of {@code forecastSeconds}. 198 * 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 201 * (or will be) throttled at {@link #ATHERMAL_STATUS_SEVERE}. Such throttling can affect the 202 * 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 204 * may correspond to {@link #ATHERMAL_STATUS_SEVERE}, but may also represent heavier throttling. 205 * 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 */ 222 float AThermal_getThermalHeadroom(AThermalManager *manager, 223 int forecastSeconds) __INTRODUCED_IN(31); 224 225 #ifdef __cplusplus 226 } 227 #endif 228 229 #endif // _ANDROID_THERMAL_H 230 231 /** @} */ 232