Loading include/android/system_health.h +152 −52 Original line number Diff line number Diff line Loading @@ -16,6 +16,31 @@ /** * @defgroup SystemHealth * * SystemHealth provides access to data about how various system resources are used by applications. * * CPU/GPU headroom APIs are designed to be best used by applications with consistent and intense * workload such as games to query the remaining capacity headroom over a short period and perform * optimization accordingly. Due to the nature of the fast job scheduling and frequency scaling of * CPU and GPU, the headroom by nature will have "TOCTOU" problem which makes it less suitable for * apps with inconsistent or low workload to take any useful action but simply monitoring. And to * avoid oscillation it's not recommended to adjust workload too frequent (on each polling request) * or too aggressively. As the headroom calculation is more based on reflecting past history usage * than predicting future capacity. Take game as an example, if the API returns CPU headroom of 0 in * one scenario (especially if it's constant across multiple calls), or some value significantly * smaller than other scenarios, then it can reason that the recent performance result is more CPU * bottlenecked. Then reducing the CPU workload intensity can help reserve some headroom to handle * the load variance better, which can result in less frame drops or smooth FPS value. On the other * hand, if the API returns large CPU headroom constantly, the app can be more confident to increase * the workload and expect higher possibility of device meeting its performance expectation. * App can also use thermal APIs to read the current thermal status and headroom first, then poll * the CPU and GPU headroom if the device is (about to) getting thermal throttled. If the CPU/GPU * headrooms provide enough significance such as one valued at 0 while the other at 100, then it can * be used to infer that reducing CPU workload could be more efficient to cool down the device. * There is a caveat that the power controller may scale down the frequency of the CPU and GPU due * to thermal and other reasons, which can result in a higher than usual percentage usage of the * capacity. * * @{ */ Loading Loading @@ -70,28 +95,14 @@ typedef struct ACpuHeadroomParams ACpuHeadroomParams; */ typedef struct AGpuHeadroomParams AGpuHeadroomParams; /** * Creates a new instance of ACpuHeadroomParams. * * When the client finishes using {@link ACpuHeadroomParams}, * {@link ACpuHeadroomParams_destroy()} must be called to destroy * and free up the resources associated with {@link ACpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of ACpuHeadroomParams. */ ACpuHeadroomParams* _Nonnull ACpuHeadroomParams_create(void) __INTRODUCED_IN(36); typedef enum ACpuHeadroomCalculationType : int32_t { /** * Use the minimum headroom value within the calculation window. * The headroom calculation type bases on minimum value over a specified window. * Introduced in API level 36. */ ACPU_HEADROOM_CALCULATION_TYPE_MIN = 0, /** * Use the average headroom value within the calculation window. * The headroom calculation type bases on average value over a specified window. * Introduced in API level 36. */ ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, Loading @@ -99,24 +110,25 @@ typedef enum ACpuHeadroomCalculationType : int32_t { typedef enum AGpuHeadroomCalculationType : int32_t { /** * Use the minimum headroom value within the calculation window. * The headroom calculation type bases on minimum value over a specified window. * Introduced in API level 36. */ AGPU_HEADROOM_CALCULATION_TYPE_MIN = 0, /** * Use the average headroom value within the calculation window. * The headroom calculation type bases on average value over a specified window. * Introduced in API level 36. */ AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, } AGpuHeadroomCalculationType; /** * Sets the headroom calculation window size in ACpuHeadroomParams. * Sets the CPU headroom calculation window size in milliseconds. * * Available since API level 36. * * @param params The params to be set. * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the * @param windowMillis The window size in milliseconds ranges from * {@link ASystemHealth_getCpuHeadroomCalculationWindowRange}. The smaller the * window size, the larger fluctuation in the headroom value should be expected. * The default value can be retrieved from the * {@link #ACpuHeadroomParams_getCalculationWindowMillis} if not set. The device Loading @@ -127,23 +139,26 @@ void ACpuHeadroomParams_setCalculationWindowMillis(ACpuHeadroomParams* _Nonnull __INTRODUCED_IN(36); /** * Gets the headroom calculation window size in ACpuHeadroomParams. * Gets the CPU headroom calculation window size in milliseconds. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return This will return the default value chosen by the device if the params is not set. */ int ACpuHeadroomParams_getCalculationWindowMillis(ACpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation window size in AGpuHeadroomParams. * Sets the GPU headroom calculation window size in milliseconds. * * Available since API level 36. * * @param params The params to be set. * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the * @param windowMillis The window size in milliseconds ranges from * {@link ASystemHealth_getGpuHeadroomCalculationWindowRange}. The smaller the * window size, the larger fluctuation in the headroom value should be expected. * The default value can be retrieved from the * {@link #AGpuHeadroomParams_getCalculationWindowMillis} if not set. The device Loading @@ -154,18 +169,20 @@ void AGpuHeadroomParams_setCalculationWindowMillis(AGpuHeadroomParams* _Nonnull __INTRODUCED_IN(36); /** * Gets the headroom calculation window size in AGpuHeadroomParams. * Gets the GPU headroom calculation window size in milliseconds. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return This will return the default value chosen by the device if the params is not set. */ int AGpuHeadroomParams_getCalculationWindowMillis(AGpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation type in ACpuHeadroomParams. * Sets the CPU headroom calculation type in {@link ACpuHeadroomParams}. * * Available since API level 36. * Loading @@ -177,11 +194,13 @@ void ACpuHeadroomParams_setCalculationType(ACpuHeadroomParams* _Nonnull params, __INTRODUCED_IN(36); /** * Gets the headroom calculation type in ACpuHeadroomParams. * Gets the CPU headroom calculation type in {@link ACpuHeadroomParams}. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return The headroom calculation type. */ ACpuHeadroomCalculationType Loading @@ -189,7 +208,7 @@ ACpuHeadroomParams_getCalculationType(ACpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation type in AGpuHeadroomParams. * Sets the GPU headroom calculation type in {@link AGpuHeadroomParams}. * * Available since API level 36. * Loading @@ -201,11 +220,13 @@ void AGpuHeadroomParams_setCalculationType(AGpuHeadroomParams* _Nonnull params, __INTRODUCED_IN(36); /** * Gets the headroom calculation type in AGpuHeadroomParams. * Gets the GPU headroom calculation type in {@link AGpuHeadroomParams}. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return The headroom calculation type. */ AGpuHeadroomCalculationType Loading @@ -213,50 +234,115 @@ AGpuHeadroomParams_getCalculationType(AGpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the thread TIDs to track in ACpuHeadroomParams. * Sets the thread TIDs to track in {@link ACpuHeadroomParams}. * * The TIDs should belong to the same of the process that will make the headroom call. And they * should not have different core affinity. * * If not set or set to empty, the headroom will be based on the PID of the process making the call. * * Available since API level 36. * * @param params The params to be set. * @param tids Non-null array of TIDs, maximum 5. * @param tids Non-null array of TIDs, where maximum size can be read from * {@link ASystemHealth_getMaxCpuHeadroomTidsSize}. * @param tidsSize The size of the tids array. */ void ACpuHeadroomParams_setTids(ACpuHeadroomParams* _Nonnull params, const int* _Nonnull tids, int tidsSize) size_t tidsSize) __INTRODUCED_IN(36); /** * Creates a new instance of {@link ACpuHeadroomParams}. * * When the client finishes using {@link ACpuHeadroomParams}, * {@link ACpuHeadroomParams_destroy} must be called to destroy * and free up the resources associated with {@link ACpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of {@link ACpuHeadroomParams}. */ ACpuHeadroomParams* _Nonnull ACpuHeadroomParams_create(void) __INTRODUCED_IN(36); /** * Creates a new instance of AGpuHeadroomParams. * Creates a new instance of {@link AGpuHeadroomParams}. * * When the client finishes using {@link AGpuHeadroomParams}, * {@link AGpuHeadroomParams_destroy()} must be called to destroy * {@link AGpuHeadroomParams_destroy} must be called to destroy * and free up the resources associated with {@link AGpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of AGpuHeadroomParams. * @return A new instance of {@link AGpuHeadroomParams}. */ AGpuHeadroomParams* _Nonnull AGpuHeadroomParams_create(void) __INTRODUCED_IN(36); /** * Deletes the ACpuHeadroomParams instance. * Deletes the {@link ACpuHeadroomParams} instance. * * Available since API level 36. * * @param params The params to be deleted. */ void ACpuHeadroomParams_destroy(ACpuHeadroomParams* _Nonnull params) void ACpuHeadroomParams_destroy(ACpuHeadroomParams* _Nullable params) __INTRODUCED_IN(36); /** * Deletes the AGpuHeadroomParams instance. * Deletes the {@link AGpuHeadroomParams} instance. * * Available since API level 36. * * @param params The params to be deleted. */ void AGpuHeadroomParams_destroy(AGpuHeadroomParams* _Nonnull params) void AGpuHeadroomParams_destroy(AGpuHeadroomParams* _Nullable params) __INTRODUCED_IN(36); /** * Gets the maximum number of TIDs this device supports for getting CPU headroom. * * See {@link ACpuHeadroomParams_setTids}. * * Available since API level 36. * * @param outSize Non-null output pointer to the max size. * @return 0 on success. * ENOTSUP if the CPU headroom API is unsupported. */ int ASystemHealth_getMaxCpuHeadroomTidsSize(size_t* _Nonnull outSize); /** * Gets the range of the calculation window size for CPU headroom. * * In API version 36, the range will be a superset of [50, 10000]. * * Available since API level 36. * * @param outMinMillis Non-null output pointer to be set to the minimum window size in milliseconds. * @param outMaxMillis Non-null output pointer to be set to the maximum window size in milliseconds. * @return 0 on success. * ENOTSUP if API is unsupported. */ int ASystemHealth_getCpuHeadroomCalculationWindowRange(int32_t* _Nonnull outMinMillis, int32_t* _Nonnull outMaxMillis) __INTRODUCED_IN(36); /** * Gets the range of the calculation window size for GPU headroom. * * In API version 36, the range will be a superset of [50, 10000]. * * Available since API level 36. * * @param outMinMillis Non-null output pointer to be set to the minimum window size in milliseconds. * @param outMaxMillis Non-null output pointer to be set to the maximum window size in milliseconds. * @return 0 on success. * ENOTSUP if API is unsupported. */ int ASystemHealth_getGpuHeadroomCalculationWindowRange(int32_t* _Nonnull outMinMillis, int32_t* _Nonnull outMaxMillis) __INTRODUCED_IN(36); /** Loading @@ -267,15 +353,21 @@ __INTRODUCED_IN(36); * be used with the thermal status and headroom to determine if reducing the CPU bound workload can * help reduce the device temperature to avoid thermal throttling. * * If the params are valid, each call will perform at least one synchronous binder transaction that * can take more than 1ms. So it's not recommended to call or wait for this on critical threads. * Some devices may implement this as an on-demand API with lazy initialization, so the caller * should expect higher latency when making the first call (especially with non-default params) * since app starts or after changing params, as the device may need to change its data collection. * * Available since API level 36. * * @param params The params to customize the CPU headroom calculation, or nullptr to use the default * @param params The params to customize the CPU headroom calculation, or nullptr to use default. * @param outHeadroom Non-null output pointer to a single float, which will be set to the CPU * headroom value. The value will be a single value or `Float.NaN` if it's * temporarily unavailable. * temporarily unavailable due to server error or not enough user CPU workload. * Each valid value ranges from [0, 100], where 0 indicates no more cpu resources * can be granted. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the CPU headroom. * EPERM if the TIDs do not belong to the same process. * ENOTSUP if API or requested params is unsupported. Loading @@ -292,15 +384,21 @@ __INTRODUCED_IN(36); * be used with the thermal status and headroom to determine if reducing the GPU bound workload can * help reduce the device temperature to avoid thermal throttling. * * If the params are valid, each call will perform at least one synchronous binder transaction that * can take more than 1ms. So it's not recommended to call or wait for this on critical threads. * Some devices may implement this as an on-demand API with lazy initialization, so the caller * should expect higher latency when making the first call (especially with non-default params) * since app starts or after changing params, as the device may need to change its data collection. * * Available since API level 36 * * @param params The params to customize the GPU headroom calculation, or nullptr to use the default * @param params The params to customize the GPU headroom calculation, or nullptr to use default * @param outHeadroom Non-null output pointer to a single float, which will be set to the GPU * headroom value. The value will be a single value or `Float.NaN` if it's * temporarily unavailable. * Each valid value ranges from [0, 100], where 0 indicates no more gpu resources * can be granted. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the GPU headroom. * ENOTSUP if API or requested params is unsupported. */ Loading @@ -311,13 +409,14 @@ __INTRODUCED_IN(36); /** * Gets minimum polling interval for calling {@link ASystemHealth_getCpuHeadroom} in milliseconds. * * The getCpuHeadroom API may return cached result if called more frequently than the interval. * The {@link ASystemHealth_getCpuHeadroom} API may return cached result if called more frequently * than the interval. * * Available since API level 36. * * @param outMinIntervalMillis Non-null output pointer to a int64_t, which * will be set to the minimum polling interval in milliseconds. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the minimum polling interval. * ENOTSUP if API is unsupported. */ Loading @@ -327,13 +426,14 @@ __INTRODUCED_IN(36); /** * Gets minimum polling interval for calling {@link ASystemHealth_getGpuHeadroom} in milliseconds. * * The getGpuHeadroom API may return cached result if called more frequent than the interval. * The {@link ASystemHealth_getGpuHeadroom} API may return cached result if called more frequently * than the interval. * * Available since API level 36. * * @param outMinIntervalMillis Non-null output pointer to a int64_t, which * will be set to the minimum polling interval in milliseconds. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the minimum polling interval. * ENOTSUP if API is unsupported. */ Loading Loading
include/android/system_health.h +152 −52 Original line number Diff line number Diff line Loading @@ -16,6 +16,31 @@ /** * @defgroup SystemHealth * * SystemHealth provides access to data about how various system resources are used by applications. * * CPU/GPU headroom APIs are designed to be best used by applications with consistent and intense * workload such as games to query the remaining capacity headroom over a short period and perform * optimization accordingly. Due to the nature of the fast job scheduling and frequency scaling of * CPU and GPU, the headroom by nature will have "TOCTOU" problem which makes it less suitable for * apps with inconsistent or low workload to take any useful action but simply monitoring. And to * avoid oscillation it's not recommended to adjust workload too frequent (on each polling request) * or too aggressively. As the headroom calculation is more based on reflecting past history usage * than predicting future capacity. Take game as an example, if the API returns CPU headroom of 0 in * one scenario (especially if it's constant across multiple calls), or some value significantly * smaller than other scenarios, then it can reason that the recent performance result is more CPU * bottlenecked. Then reducing the CPU workload intensity can help reserve some headroom to handle * the load variance better, which can result in less frame drops or smooth FPS value. On the other * hand, if the API returns large CPU headroom constantly, the app can be more confident to increase * the workload and expect higher possibility of device meeting its performance expectation. * App can also use thermal APIs to read the current thermal status and headroom first, then poll * the CPU and GPU headroom if the device is (about to) getting thermal throttled. If the CPU/GPU * headrooms provide enough significance such as one valued at 0 while the other at 100, then it can * be used to infer that reducing CPU workload could be more efficient to cool down the device. * There is a caveat that the power controller may scale down the frequency of the CPU and GPU due * to thermal and other reasons, which can result in a higher than usual percentage usage of the * capacity. * * @{ */ Loading Loading @@ -70,28 +95,14 @@ typedef struct ACpuHeadroomParams ACpuHeadroomParams; */ typedef struct AGpuHeadroomParams AGpuHeadroomParams; /** * Creates a new instance of ACpuHeadroomParams. * * When the client finishes using {@link ACpuHeadroomParams}, * {@link ACpuHeadroomParams_destroy()} must be called to destroy * and free up the resources associated with {@link ACpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of ACpuHeadroomParams. */ ACpuHeadroomParams* _Nonnull ACpuHeadroomParams_create(void) __INTRODUCED_IN(36); typedef enum ACpuHeadroomCalculationType : int32_t { /** * Use the minimum headroom value within the calculation window. * The headroom calculation type bases on minimum value over a specified window. * Introduced in API level 36. */ ACPU_HEADROOM_CALCULATION_TYPE_MIN = 0, /** * Use the average headroom value within the calculation window. * The headroom calculation type bases on average value over a specified window. * Introduced in API level 36. */ ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, Loading @@ -99,24 +110,25 @@ typedef enum ACpuHeadroomCalculationType : int32_t { typedef enum AGpuHeadroomCalculationType : int32_t { /** * Use the minimum headroom value within the calculation window. * The headroom calculation type bases on minimum value over a specified window. * Introduced in API level 36. */ AGPU_HEADROOM_CALCULATION_TYPE_MIN = 0, /** * Use the average headroom value within the calculation window. * The headroom calculation type bases on average value over a specified window. * Introduced in API level 36. */ AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1, } AGpuHeadroomCalculationType; /** * Sets the headroom calculation window size in ACpuHeadroomParams. * Sets the CPU headroom calculation window size in milliseconds. * * Available since API level 36. * * @param params The params to be set. * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the * @param windowMillis The window size in milliseconds ranges from * {@link ASystemHealth_getCpuHeadroomCalculationWindowRange}. The smaller the * window size, the larger fluctuation in the headroom value should be expected. * The default value can be retrieved from the * {@link #ACpuHeadroomParams_getCalculationWindowMillis} if not set. The device Loading @@ -127,23 +139,26 @@ void ACpuHeadroomParams_setCalculationWindowMillis(ACpuHeadroomParams* _Nonnull __INTRODUCED_IN(36); /** * Gets the headroom calculation window size in ACpuHeadroomParams. * Gets the CPU headroom calculation window size in milliseconds. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return This will return the default value chosen by the device if the params is not set. */ int ACpuHeadroomParams_getCalculationWindowMillis(ACpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation window size in AGpuHeadroomParams. * Sets the GPU headroom calculation window size in milliseconds. * * Available since API level 36. * * @param params The params to be set. * @param windowMillis The window size in milliseconds ranged from [50, 10000]. The smaller the * @param windowMillis The window size in milliseconds ranges from * {@link ASystemHealth_getGpuHeadroomCalculationWindowRange}. The smaller the * window size, the larger fluctuation in the headroom value should be expected. * The default value can be retrieved from the * {@link #AGpuHeadroomParams_getCalculationWindowMillis} if not set. The device Loading @@ -154,18 +169,20 @@ void AGpuHeadroomParams_setCalculationWindowMillis(AGpuHeadroomParams* _Nonnull __INTRODUCED_IN(36); /** * Gets the headroom calculation window size in AGpuHeadroomParams. * Gets the GPU headroom calculation window size in milliseconds. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return This will return the default value chosen by the device if the params is not set. */ int AGpuHeadroomParams_getCalculationWindowMillis(AGpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation type in ACpuHeadroomParams. * Sets the CPU headroom calculation type in {@link ACpuHeadroomParams}. * * Available since API level 36. * Loading @@ -177,11 +194,13 @@ void ACpuHeadroomParams_setCalculationType(ACpuHeadroomParams* _Nonnull params, __INTRODUCED_IN(36); /** * Gets the headroom calculation type in ACpuHeadroomParams. * Gets the CPU headroom calculation type in {@link ACpuHeadroomParams}. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return The headroom calculation type. */ ACpuHeadroomCalculationType Loading @@ -189,7 +208,7 @@ ACpuHeadroomParams_getCalculationType(ACpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the headroom calculation type in AGpuHeadroomParams. * Sets the GPU headroom calculation type in {@link AGpuHeadroomParams}. * * Available since API level 36. * Loading @@ -201,11 +220,13 @@ void AGpuHeadroomParams_setCalculationType(AGpuHeadroomParams* _Nonnull params, __INTRODUCED_IN(36); /** * Gets the headroom calculation type in AGpuHeadroomParams. * Gets the GPU headroom calculation type in {@link AGpuHeadroomParams}. * * This will return the default value chosen by the device if not set. * * Available since API level 36. * * @param params The params to be set. * @param params The params to read from. * @return The headroom calculation type. */ AGpuHeadroomCalculationType Loading @@ -213,50 +234,115 @@ AGpuHeadroomParams_getCalculationType(AGpuHeadroomParams* _Nonnull params) __INTRODUCED_IN(36); /** * Sets the thread TIDs to track in ACpuHeadroomParams. * Sets the thread TIDs to track in {@link ACpuHeadroomParams}. * * The TIDs should belong to the same of the process that will make the headroom call. And they * should not have different core affinity. * * If not set or set to empty, the headroom will be based on the PID of the process making the call. * * Available since API level 36. * * @param params The params to be set. * @param tids Non-null array of TIDs, maximum 5. * @param tids Non-null array of TIDs, where maximum size can be read from * {@link ASystemHealth_getMaxCpuHeadroomTidsSize}. * @param tidsSize The size of the tids array. */ void ACpuHeadroomParams_setTids(ACpuHeadroomParams* _Nonnull params, const int* _Nonnull tids, int tidsSize) size_t tidsSize) __INTRODUCED_IN(36); /** * Creates a new instance of {@link ACpuHeadroomParams}. * * When the client finishes using {@link ACpuHeadroomParams}, * {@link ACpuHeadroomParams_destroy} must be called to destroy * and free up the resources associated with {@link ACpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of {@link ACpuHeadroomParams}. */ ACpuHeadroomParams* _Nonnull ACpuHeadroomParams_create(void) __INTRODUCED_IN(36); /** * Creates a new instance of AGpuHeadroomParams. * Creates a new instance of {@link AGpuHeadroomParams}. * * When the client finishes using {@link AGpuHeadroomParams}, * {@link AGpuHeadroomParams_destroy()} must be called to destroy * {@link AGpuHeadroomParams_destroy} must be called to destroy * and free up the resources associated with {@link AGpuHeadroomParams}. * * Available since API level 36. * * @return A new instance of AGpuHeadroomParams. * @return A new instance of {@link AGpuHeadroomParams}. */ AGpuHeadroomParams* _Nonnull AGpuHeadroomParams_create(void) __INTRODUCED_IN(36); /** * Deletes the ACpuHeadroomParams instance. * Deletes the {@link ACpuHeadroomParams} instance. * * Available since API level 36. * * @param params The params to be deleted. */ void ACpuHeadroomParams_destroy(ACpuHeadroomParams* _Nonnull params) void ACpuHeadroomParams_destroy(ACpuHeadroomParams* _Nullable params) __INTRODUCED_IN(36); /** * Deletes the AGpuHeadroomParams instance. * Deletes the {@link AGpuHeadroomParams} instance. * * Available since API level 36. * * @param params The params to be deleted. */ void AGpuHeadroomParams_destroy(AGpuHeadroomParams* _Nonnull params) void AGpuHeadroomParams_destroy(AGpuHeadroomParams* _Nullable params) __INTRODUCED_IN(36); /** * Gets the maximum number of TIDs this device supports for getting CPU headroom. * * See {@link ACpuHeadroomParams_setTids}. * * Available since API level 36. * * @param outSize Non-null output pointer to the max size. * @return 0 on success. * ENOTSUP if the CPU headroom API is unsupported. */ int ASystemHealth_getMaxCpuHeadroomTidsSize(size_t* _Nonnull outSize); /** * Gets the range of the calculation window size for CPU headroom. * * In API version 36, the range will be a superset of [50, 10000]. * * Available since API level 36. * * @param outMinMillis Non-null output pointer to be set to the minimum window size in milliseconds. * @param outMaxMillis Non-null output pointer to be set to the maximum window size in milliseconds. * @return 0 on success. * ENOTSUP if API is unsupported. */ int ASystemHealth_getCpuHeadroomCalculationWindowRange(int32_t* _Nonnull outMinMillis, int32_t* _Nonnull outMaxMillis) __INTRODUCED_IN(36); /** * Gets the range of the calculation window size for GPU headroom. * * In API version 36, the range will be a superset of [50, 10000]. * * Available since API level 36. * * @param outMinMillis Non-null output pointer to be set to the minimum window size in milliseconds. * @param outMaxMillis Non-null output pointer to be set to the maximum window size in milliseconds. * @return 0 on success. * ENOTSUP if API is unsupported. */ int ASystemHealth_getGpuHeadroomCalculationWindowRange(int32_t* _Nonnull outMinMillis, int32_t* _Nonnull outMaxMillis) __INTRODUCED_IN(36); /** Loading @@ -267,15 +353,21 @@ __INTRODUCED_IN(36); * be used with the thermal status and headroom to determine if reducing the CPU bound workload can * help reduce the device temperature to avoid thermal throttling. * * If the params are valid, each call will perform at least one synchronous binder transaction that * can take more than 1ms. So it's not recommended to call or wait for this on critical threads. * Some devices may implement this as an on-demand API with lazy initialization, so the caller * should expect higher latency when making the first call (especially with non-default params) * since app starts or after changing params, as the device may need to change its data collection. * * Available since API level 36. * * @param params The params to customize the CPU headroom calculation, or nullptr to use the default * @param params The params to customize the CPU headroom calculation, or nullptr to use default. * @param outHeadroom Non-null output pointer to a single float, which will be set to the CPU * headroom value. The value will be a single value or `Float.NaN` if it's * temporarily unavailable. * temporarily unavailable due to server error or not enough user CPU workload. * Each valid value ranges from [0, 100], where 0 indicates no more cpu resources * can be granted. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the CPU headroom. * EPERM if the TIDs do not belong to the same process. * ENOTSUP if API or requested params is unsupported. Loading @@ -292,15 +384,21 @@ __INTRODUCED_IN(36); * be used with the thermal status and headroom to determine if reducing the GPU bound workload can * help reduce the device temperature to avoid thermal throttling. * * If the params are valid, each call will perform at least one synchronous binder transaction that * can take more than 1ms. So it's not recommended to call or wait for this on critical threads. * Some devices may implement this as an on-demand API with lazy initialization, so the caller * should expect higher latency when making the first call (especially with non-default params) * since app starts or after changing params, as the device may need to change its data collection. * * Available since API level 36 * * @param params The params to customize the GPU headroom calculation, or nullptr to use the default * @param params The params to customize the GPU headroom calculation, or nullptr to use default * @param outHeadroom Non-null output pointer to a single float, which will be set to the GPU * headroom value. The value will be a single value or `Float.NaN` if it's * temporarily unavailable. * Each valid value ranges from [0, 100], where 0 indicates no more gpu resources * can be granted. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the GPU headroom. * ENOTSUP if API or requested params is unsupported. */ Loading @@ -311,13 +409,14 @@ __INTRODUCED_IN(36); /** * Gets minimum polling interval for calling {@link ASystemHealth_getCpuHeadroom} in milliseconds. * * The getCpuHeadroom API may return cached result if called more frequently than the interval. * The {@link ASystemHealth_getCpuHeadroom} API may return cached result if called more frequently * than the interval. * * Available since API level 36. * * @param outMinIntervalMillis Non-null output pointer to a int64_t, which * will be set to the minimum polling interval in milliseconds. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the minimum polling interval. * ENOTSUP if API is unsupported. */ Loading @@ -327,13 +426,14 @@ __INTRODUCED_IN(36); /** * Gets minimum polling interval for calling {@link ASystemHealth_getGpuHeadroom} in milliseconds. * * The getGpuHeadroom API may return cached result if called more frequent than the interval. * The {@link ASystemHealth_getGpuHeadroom} API may return cached result if called more frequently * than the interval. * * Available since API level 36. * * @param outMinIntervalMillis Non-null output pointer to a int64_t, which * will be set to the minimum polling interval in milliseconds. * @return 0 on success * @return 0 on success. * EPIPE if failed to get the minimum polling interval. * ENOTSUP if API is unsupported. */ Loading
