1 /* 2 * Copyright (C) 2024 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 * @defgroup SystemHealth 19 * @{ 20 */ 21 22 /** 23 * @file system_health.h 24 */ 25 26 #ifndef _ANDROID_SYSTEM_HEALTH_H 27 #define _ANDROID_SYSTEM_HEALTH_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 #include <stdint.h> 49 #include <sys/types.h> 50 51 #if !defined(__INTRODUCED_IN) 52 #define __INTRODUCED_IN(__api_level) /* nothing */ 53 #endif 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 /** 60 * Params used to customize the calculation of CPU headroom. 61 * 62 * Also see {@link ASystemHealth_getCpuHeadroom}. 63 */ 64 typedef struct ACpuHeadroomParams ACpuHeadroomParams; 65 66 /** 67 * Params used to customize the calculation of GPU headroom. 68 * 69 * Also see {@link ASystemHealth_getGpuHeadroom}. 70 */ 71 typedef struct AGpuHeadroomParams AGpuHeadroomParams; 72 73 /** 74 * Creates a new instance of ACpuHeadroomParams. 75 * 76 * When the client finishes using {@link ACpuHeadroomParams}, 77 * {@link ACpuHeadroomParams_destroy()} must be called to destroy 78 * and free up the resources associated with {@link ACpuHeadroomParams}. 79 * 80 * Available since API level 36. 81 * 82 * @return A new instance of ACpuHeadroomParams. 83 */ 84 ACpuHeadroomParams *_Nonnull ACpuHeadroomParams_create() 85 __INTRODUCED_IN(36); 86 87 enum ACpuHeadroomCalculationType { 88 /** 89 * Use the minimum headroom value within the calculation window. 90 * Introduced in API level 36. 91 */ 92 ACPU_HEADROOM_CALCULATION_TYPE_MIN = 0, 93 /** 94 * Use the average headroom value within the calculation window. 95 * Introduced in API level 36. 96 */ 97 ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, 98 }; 99 typedef enum ACpuHeadroomCalculationType ACpuHeadroomCalculationType; 100 101 enum AGpuHeadroomCalculationType { 102 /** 103 * Use the minimum headroom value within the calculation window. 104 * Introduced in API level 36. 105 */ 106 AGPU_HEADROOM_CALCULATION_TYPE_MIN = 0, 107 /** 108 * Use the average headroom value within the calculation window. 109 * Introduced in API level 36. 110 */ 111 AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, 112 }; 113 typedef enum AGpuHeadroomCalculationType AGpuHeadroomCalculationType; 114 115 /** 116 * Sets the headroom calculation window size in ACpuHeadroomParams. 117 * 118 * Available since API level 36. 119 * 120 * @param params The params to be set. 121 * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the 122 * window size, the larger fluctuation in the headroom value should be expected. 123 * The default value can be retrieved from the 124 * {@link #ACpuHeadroomParams_getCalculationWindowMillis} if not set. The device 125 * will try to use the closest feasible window size to this param. 126 */ 127 void ACpuHeadroomParams_setCalculationWindowMillis(ACpuHeadroomParams *_Nonnull params, 128 int windowMillis) 129 __INTRODUCED_IN(36); 130 131 /** 132 * Gets the headroom calculation window size in ACpuHeadroomParams. 133 * 134 * Available since API level 36. 135 * 136 * @param params The params to be set. 137 * @return This will return the default value chosen by the device if the params is not set. 138 */ 139 int ACpuHeadroomParams_getCalculationWindowMillis(ACpuHeadroomParams *_Nonnull params) 140 __INTRODUCED_IN(36); 141 142 /** 143 * Sets the headroom calculation window size in AGpuHeadroomParams. 144 * 145 * Available since API level 36. 146 * 147 * @param params The params to be set. 148 * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the 149 * window size, the larger fluctuation in the headroom value should be expected. 150 * The default value can be retrieved from the 151 * {@link #AGpuHeadroomParams_getCalculationWindowMillis} if not set. The device 152 * will try to use the closest feasible window size to this param. 153 */ 154 void AGpuHeadroomParams_setCalculationWindowMillis(AGpuHeadroomParams *_Nonnull params, 155 int windowMillis) 156 __INTRODUCED_IN(36); 157 158 /** 159 * Gets the headroom calculation window size in AGpuHeadroomParams. 160 * 161 * Available since API level 36. 162 * 163 * @param params The params to be set. 164 * @return This will return the default value chosen by the device if the params is not set. 165 */ 166 int AGpuHeadroomParams_getCalculationWindowMillis(AGpuHeadroomParams *_Nonnull params) 167 __INTRODUCED_IN(36); 168 169 /** 170 * Sets the headroom calculation type in ACpuHeadroomParams. 171 * 172 * Available since API level 36. 173 * 174 * @param params The params to be set. 175 * @param calculationType The headroom calculation type. 176 */ 177 void ACpuHeadroomParams_setCalculationType(ACpuHeadroomParams *_Nonnull params, 178 ACpuHeadroomCalculationType calculationType) 179 __INTRODUCED_IN(36); 180 181 /** 182 * Gets the headroom calculation type in ACpuHeadroomParams. 183 * 184 * Available since API level 36. 185 * 186 * @param params The params to be set. 187 * @return The headroom calculation type. 188 */ 189 ACpuHeadroomCalculationType 190 ACpuHeadroomParams_getCalculationType(ACpuHeadroomParams *_Nonnull params) 191 __INTRODUCED_IN(36); 192 193 /** 194 * Sets the headroom calculation type in AGpuHeadroomParams. 195 * 196 * Available since API level 36. 197 * 198 * @param params The params to be set. 199 * @param calculationType The headroom calculation type. 200 */ 201 void AGpuHeadroomParams_setCalculationType(AGpuHeadroomParams *_Nonnull params, 202 AGpuHeadroomCalculationType calculationType) 203 __INTRODUCED_IN(36); 204 205 /** 206 * Gets the headroom calculation type in AGpuHeadroomParams. 207 * 208 * Available since API level 36. 209 * 210 * @param params The params to be set. 211 * @return The headroom calculation type. 212 */ 213 AGpuHeadroomCalculationType 214 AGpuHeadroomParams_getCalculationType(AGpuHeadroomParams *_Nonnull params) 215 __INTRODUCED_IN(36); 216 217 /** 218 * Sets the thread TIDs to track in ACpuHeadroomParams. 219 * 220 * Available since API level 36. 221 * 222 * @param params The params to be set. 223 * @param tids Non-null array of TIDs, maximum 5. 224 * @param tidsSize The size of the tids array. 225 */ 226 void ACpuHeadroomParams_setTids(ACpuHeadroomParams *_Nonnull params, const int *_Nonnull tids, 227 int tidsSize) 228 __INTRODUCED_IN(36); 229 230 /** 231 * Creates a new instance of AGpuHeadroomParams. 232 * 233 * When the client finishes using {@link AGpuHeadroomParams}, 234 * {@link AGpuHeadroomParams_destroy()} must be called to destroy 235 * and free up the resources associated with {@link AGpuHeadroomParams}. 236 * 237 * Available since API level 36. 238 * 239 * @return A new instance of AGpuHeadroomParams. 240 */ 241 AGpuHeadroomParams *_Nonnull AGpuHeadroomParams_create() 242 __INTRODUCED_IN(36); 243 244 /** 245 * Deletes the ACpuHeadroomParams instance. 246 * 247 * Available since API level 36. 248 * 249 * @param params The params to be deleted. 250 */ 251 void ACpuHeadroomParams_destroy(ACpuHeadroomParams *_Nonnull params) 252 __INTRODUCED_IN(36); 253 254 /** 255 * Deletes the AGpuHeadroomParams instance. 256 * 257 * Available since API level 36. 258 * 259 * @param params The params to be deleted. 260 */ 261 void AGpuHeadroomParams_destroy(AGpuHeadroomParams *_Nonnull params) 262 __INTRODUCED_IN(36); 263 264 /** 265 * Provides an estimate of available CPU capacity headroom of the device. 266 * 267 * The value can be used by the calling application to determine if the workload was CPU bound and 268 * then take action accordingly to ensure that the workload can be completed smoothly. It can also 269 * be used with the thermal status and headroom to determine if reducing the CPU bound workload can 270 * help reduce the device temperature to avoid thermal throttling. 271 * 272 * Available since API level 36. 273 * 274 * @param params The params to customize the CPU headroom calculation, or nullptr to use the default 275 * @param outHeadroom Non-null output pointer to a single float, which will be set to the CPU 276 * headroom value. The value will be a single value or `Float.NaN` if it's 277 * temporarily unavailable. 278 * Each valid value ranges from [0, 100], where 0 indicates no more cpu resources 279 * can be granted. 280 * @return 0 on success 281 * EPIPE if failed to get the CPU headroom. 282 * EPERM if the TIDs do not belong to the same process. 283 * ENOTSUP if API or requested params is unsupported. 284 */ 285 int ASystemHealth_getCpuHeadroom(const ACpuHeadroomParams *_Nullable params, 286 float *_Nonnull outHeadroom) 287 __INTRODUCED_IN(36); 288 289 /** 290 * Provides an estimate of available GPU capacity headroom of the device. 291 * 292 * The value can be used by the calling application to determine if the workload was GPU bound and 293 * then take action accordingly to ensure that the workload can be completed smoothly. It can also 294 * be used with the thermal status and headroom to determine if reducing the GPU bound workload can 295 * help reduce the device temperature to avoid thermal throttling. 296 * 297 * Available since API level 36 298 * 299 * @param params The params to customize the GPU headroom calculation, or nullptr to use the default 300 * @param outHeadroom Non-null output pointer to a single float, which will be set to the GPU 301 * headroom value. The value will be a single value or `Float.NaN` if it's 302 * temporarily unavailable. 303 * Each valid value ranges from [0, 100], where 0 indicates no more gpu resources 304 * can be granted. 305 * @return 0 on success 306 * EPIPE if failed to get the GPU headroom. 307 * ENOTSUP if API or requested params is unsupported. 308 */ 309 int ASystemHealth_getGpuHeadroom(const AGpuHeadroomParams *_Nullable params, 310 float *_Nonnull outHeadroom) 311 __INTRODUCED_IN(36); 312 313 /** 314 * Gets minimum polling interval for calling {@link ASystemHealth_getCpuHeadroom} in milliseconds. 315 * 316 * The getCpuHeadroom API may return cached result if called more frequently than the interval. 317 * 318 * Available since API level 36. 319 * 320 * @param outMinIntervalMillis Non-null output pointer to a int64_t, which 321 * will be set to the minimum polling interval in milliseconds. 322 * @return 0 on success 323 * EPIPE if failed to get the minimum polling interval. 324 * ENOTSUP if API is unsupported. 325 */ 326 int ASystemHealth_getCpuHeadroomMinIntervalMillis(int64_t *_Nonnull outMinIntervalMillis) 327 __INTRODUCED_IN(36); 328 329 /** 330 * Gets minimum polling interval for calling {@link ASystemHealth_getGpuHeadroom} in milliseconds. 331 * 332 * The getGpuHeadroom API may return cached result if called more frequent than the interval. 333 * 334 * Available since API level 36. 335 * 336 * @param outMinIntervalMillis Non-null output pointer to a int64_t, which 337 * will be set to the minimum polling interval in milliseconds. 338 * @return 0 on success 339 * EPIPE if failed to get the minimum polling interval. 340 * ENOTSUP if API is unsupported. 341 */ 342 int ASystemHealth_getGpuHeadroomMinIntervalMillis(int64_t *_Nonnull outMinIntervalMillis) 343 __INTRODUCED_IN(36); 344 345 #ifdef __cplusplus 346 } 347 #endif 348 349 #endif // _ANDROID_SYSTEM_HEALTH_H 350 351 /** @} */ 352