SystemHealth

SystemHealth provides access to data about how various system resources are used by applications.

Summary

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.

Enumerations
`ACpuHeadroomCalculationType{ ACPU_HEADROOM_CALCULATION_TYPE_MIN = 0, ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1 }`	enum
`AGpuHeadroomCalculationType{ AGPU_HEADROOM_CALCULATION_TYPE_MIN = 0, AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE = 1 }`	enum

Typedefs
`ACpuHeadroomCalculationType`	typedef `enum ACpuHeadroomCalculationType`
`ACpuHeadroomParams`	typedef `struct ACpuHeadroomParams` Params used to customize the calculation of CPU headroom.
`AGpuHeadroomCalculationType`	typedef `enum AGpuHeadroomCalculationType`
`AGpuHeadroomParams`	typedef `struct AGpuHeadroomParams` Params used to customize the calculation of GPU headroom.

Functions
`ACpuHeadroomParams_create(void)`	`ACpuHeadroomParams *_Nonnull` Creates a new instance of ACpuHeadroomParams.
`ACpuHeadroomParams_destroy(ACpuHeadroomParams *_Nullable params)`	`void` Deletes the ACpuHeadroomParams instance.
`ACpuHeadroomParams_getCalculationType(ACpuHeadroomParams *_Nonnull params)`	`ACpuHeadroomCalculationType` Gets the CPU headroom calculation type in ACpuHeadroomParams.
`ACpuHeadroomParams_getCalculationWindowMillis(ACpuHeadroomParams *_Nonnull params)`	`int` Gets the CPU headroom calculation window size in milliseconds.
`ACpuHeadroomParams_setCalculationType(ACpuHeadroomParams *_Nonnull params, ACpuHeadroomCalculationType calculationType)`	`void` Sets the CPU headroom calculation type in ACpuHeadroomParams.
`ACpuHeadroomParams_setCalculationWindowMillis(ACpuHeadroomParams *_Nonnull params, int windowMillis)`	`void` Sets the CPU headroom calculation window size in milliseconds.
`ACpuHeadroomParams_setTids(ACpuHeadroomParams _Nonnull params, const int _Nonnull tids, size_t tidsSize)`	`void` Sets the thread TIDs to track in ACpuHeadroomParams.
`AGpuHeadroomParams_create(void)`	`AGpuHeadroomParams *_Nonnull` Creates a new instance of AGpuHeadroomParams.
`AGpuHeadroomParams_destroy(AGpuHeadroomParams *_Nullable params)`	`void` Deletes the AGpuHeadroomParams instance.
`AGpuHeadroomParams_getCalculationType(AGpuHeadroomParams *_Nonnull params)`	`AGpuHeadroomCalculationType` Gets the GPU headroom calculation type in AGpuHeadroomParams.
`AGpuHeadroomParams_getCalculationWindowMillis(AGpuHeadroomParams *_Nonnull params)`	`int` Gets the GPU headroom calculation window size in milliseconds.
`AGpuHeadroomParams_setCalculationType(AGpuHeadroomParams *_Nonnull params, AGpuHeadroomCalculationType calculationType)`	`void` Sets the GPU headroom calculation type in AGpuHeadroomParams.
`AGpuHeadroomParams_setCalculationWindowMillis(AGpuHeadroomParams *_Nonnull params, int windowMillis)`	`void` Sets the GPU headroom calculation window size in milliseconds.
`ASystemHealth_getCpuHeadroom(const ACpuHeadroomParams _Nullable params, float _Nonnull outHeadroom)`	`int` Provides an estimate of available CPU capacity headroom of the device.
`ASystemHealth_getCpuHeadroomCalculationWindowRange(int32_t _Nonnull outMinMillis, int32_t _Nonnull outMaxMillis)`	`int` Gets the range of the calculation window size for CPU headroom.
`ASystemHealth_getCpuHeadroomMinIntervalMillis(int64_t *_Nonnull outMinIntervalMillis)`	`int` Gets minimum polling interval for calling ASystemHealth_getCpuHeadroom in milliseconds.
`ASystemHealth_getGpuHeadroom(const AGpuHeadroomParams _Nullable params, float _Nonnull outHeadroom)`	`int` Provides an estimate of available GPU capacity headroom of the device.
`ASystemHealth_getGpuHeadroomCalculationWindowRange(int32_t _Nonnull outMinMillis, int32_t _Nonnull outMaxMillis)`	`int` Gets the range of the calculation window size for GPU headroom.
`ASystemHealth_getGpuHeadroomMinIntervalMillis(int64_t *_Nonnull outMinIntervalMillis)`	`int` Gets minimum polling interval for calling ASystemHealth_getGpuHeadroom in milliseconds.
`ASystemHealth_getMaxCpuHeadroomTidsSize(size_t *_Nonnull outSize)`	`int` Gets the maximum number of TIDs this device supports for getting CPU headroom.

Enumerations

ACpuHeadroomCalculationType

Declared in android/system_health.h

 ACpuHeadroomCalculationType

Properties

Properties
`ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE`	The headroom calculation type bases on average value over a specified window. Introduced in API level 36.
`ACPU_HEADROOM_CALCULATION_TYPE_MIN`	The headroom calculation type bases on minimum value over a specified window. Introduced in API level 36.

ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE

The headroom calculation type bases on average value over a specified window.

Introduced in API level 36.

ACPU_HEADROOM_CALCULATION_TYPE_MIN

The headroom calculation type bases on minimum value over a specified window.

Introduced in API level 36.

AGpuHeadroomCalculationType

Declared in android/system_health.h

 AGpuHeadroomCalculationType

Properties

Properties
`AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE`	The headroom calculation type bases on average value over a specified window. Introduced in API level 36.
`AGPU_HEADROOM_CALCULATION_TYPE_MIN`	The headroom calculation type bases on minimum value over a specified window. Introduced in API level 36.

AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE

The headroom calculation type bases on average value over a specified window.

Introduced in API level 36.

AGPU_HEADROOM_CALCULATION_TYPE_MIN

The headroom calculation type bases on minimum value over a specified window.

Introduced in API level 36.

Typedefs

ACpuHeadroomCalculationType

Declared in android/system_health.h

enum ACpuHeadroomCalculationType ACpuHeadroomCalculationType

ACpuHeadroomParams

Declared in android/system_health.h

struct ACpuHeadroomParams ACpuHeadroomParams

Params used to customize the calculation of CPU headroom.

Also see ASystemHealth_getCpuHeadroom.

AGpuHeadroomCalculationType

Declared in android/system_health.h

enum AGpuHeadroomCalculationType AGpuHeadroomCalculationType

AGpuHeadroomParams

Declared in android/system_health.h

struct AGpuHeadroomParams AGpuHeadroomParams

Params used to customize the calculation of GPU headroom.

Also see ASystemHealth_getGpuHeadroom.

Functions

ACpuHeadroomParams_create

Declared in android/system_health.h

ACpuHeadroomParams *_Nonnull ACpuHeadroomParams_create(
  void
)

Creates a new instance of ACpuHeadroomParams.

When the client finishes using ACpuHeadroomParams, ACpuHeadroomParams_destroy must be called to destroy and free up the resources associated with ACpuHeadroomParams.

Available since API level 36.

Details
Returns	A new instance of ACpuHeadroomParams.

ACpuHeadroomParams_destroy

Declared in android/system_health.h

void ACpuHeadroomParams_destroy(
  ACpuHeadroomParams *_Nullable params
)

Deletes the ACpuHeadroomParams instance.

Available since API level 36.

Details

Parameters

params

The params to be deleted.

ACpuHeadroomParams_getCalculationType

Declared in android/system_health.h

ACpuHeadroomCalculationType ACpuHeadroomParams_getCalculationType(
  ACpuHeadroomParams *_Nonnull params
)

Gets the CPU headroom calculation type in ACpuHeadroomParams.

This will return the default value chosen by the device if not set.

Available since API level 36.

Details

Parameters

params

The params to read from.

Returns

The headroom calculation type.

ACpuHeadroomParams_getCalculationWindowMillis

Declared in android/system_health.h

int ACpuHeadroomParams_getCalculationWindowMillis(
  ACpuHeadroomParams *_Nonnull params
)

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.

Details

Parameters

params

The params to read from.

Returns

This will return the default value chosen by the device if the params is not set.

ACpuHeadroomParams_setCalculationType

Declared in android/system_health.h

void ACpuHeadroomParams_setCalculationType(
  ACpuHeadroomParams *_Nonnull params,
  ACpuHeadroomCalculationType calculationType
)

Sets the CPU headroom calculation type in ACpuHeadroomParams.

Available since API level 36.

Details

Parameters

`params`	The params to be set.
`calculationType`	The headroom calculation type.

ACpuHeadroomParams_setCalculationWindowMillis

Declared in android/system_health.h

void ACpuHeadroomParams_setCalculationWindowMillis(
  ACpuHeadroomParams *_Nonnull params,
  int windowMillis
)

Sets the CPU headroom calculation window size in milliseconds.

Available since API level 36.

Details

Parameters

`params`	The params to be set.
`windowMillis`	The window size in milliseconds ranges from 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 ACpuHeadroomParams_getCalculationWindowMillis if not set. The device will try to use the closest feasible window size to this param.

ACpuHeadroomParams_setTids

Declared in android/system_health.h

void ACpuHeadroomParams_setTids(
  ACpuHeadroomParams *_Nonnull params,
  const int *_Nonnull tids,
  size_t tidsSize
)

Sets the thread TIDs to track in 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.

Details

Parameters

`params`	The params to be set.
`tids`	Non-null array of TIDs, where maximum size can be read from ASystemHealth_getMaxCpuHeadroomTidsSize.
`tidsSize`	The size of the tids array.

AGpuHeadroomParams_create

Declared in android/system_health.h

AGpuHeadroomParams *_Nonnull AGpuHeadroomParams_create(
  void
)

Creates a new instance of AGpuHeadroomParams.

When the client finishes using AGpuHeadroomParams, AGpuHeadroomParams_destroy must be called to destroy and free up the resources associated with AGpuHeadroomParams.

Available since API level 36.

Details
Returns	A new instance of AGpuHeadroomParams.

AGpuHeadroomParams_destroy

Declared in android/system_health.h

void AGpuHeadroomParams_destroy(
  AGpuHeadroomParams *_Nullable params
)

Deletes the AGpuHeadroomParams instance.

Available since API level 36.

Details

Parameters

params

The params to be deleted.

AGpuHeadroomParams_getCalculationType

Declared in android/system_health.h

AGpuHeadroomCalculationType AGpuHeadroomParams_getCalculationType(
  AGpuHeadroomParams *_Nonnull params
)

Gets the GPU headroom calculation type in AGpuHeadroomParams.

This will return the default value chosen by the device if not set.

Available since API level 36.

Details

Parameters

params

The params to read from.

Returns

The headroom calculation type.

AGpuHeadroomParams_getCalculationWindowMillis

Declared in android/system_health.h

int AGpuHeadroomParams_getCalculationWindowMillis(
  AGpuHeadroomParams *_Nonnull params
)

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.

Details

Parameters

params

The params to read from.

Returns

This will return the default value chosen by the device if the params is not set.

AGpuHeadroomParams_setCalculationType

Declared in android/system_health.h

void AGpuHeadroomParams_setCalculationType(
  AGpuHeadroomParams *_Nonnull params,
  AGpuHeadroomCalculationType calculationType
)

Sets the GPU headroom calculation type in AGpuHeadroomParams.

Available since API level 36.

Details

Parameters

`params`	The params to be set.
`calculationType`	The headroom calculation type.

AGpuHeadroomParams_setCalculationWindowMillis

Declared in android/system_health.h

void AGpuHeadroomParams_setCalculationWindowMillis(
  AGpuHeadroomParams *_Nonnull params,
  int windowMillis
)

Sets the GPU headroom calculation window size in milliseconds.

Available since API level 36.

Details

Parameters

`params`	The params to be set.
`windowMillis`	The window size in milliseconds ranges from 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 AGpuHeadroomParams_getCalculationWindowMillis if not set. The device will try to use the closest feasible window size to this param.

ASystemHealth_getCpuHeadroom

Declared in android/system_health.h

int ASystemHealth_getCpuHeadroom(
  const ACpuHeadroomParams *_Nullable params,
  float *_Nonnull outHeadroom
)

Provides an estimate of available CPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was CPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also 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.

Details

Parameters

`params`	The params to customize the CPU headroom calculation, or nullptr to use default.
`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 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.

Returns

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.

ASystemHealth_getCpuHeadroomCalculationWindowRange

Declared in android/system_health.h

int ASystemHealth_getCpuHeadroomCalculationWindowRange(
  int32_t *_Nonnull outMinMillis,
  int32_t *_Nonnull outMaxMillis
)

Gets the range of the calculation window size for CPU headroom.

Available since API level 36.

Details

Parameters

`outMinMillis`	Non-null output pointer to be set to the minimum window size in milliseconds.
`outMaxMillis`	Non-null output pointer to be set to the maximum window size in milliseconds.

Returns

0 on success. ENOTSUP if API is unsupported.

ASystemHealth_getCpuHeadroomMinIntervalMillis

Declared in android/system_health.h

int ASystemHealth_getCpuHeadroomMinIntervalMillis(
  int64_t *_Nonnull outMinIntervalMillis
)

Gets minimum polling interval for calling ASystemHealth_getCpuHeadroom in milliseconds.

The ASystemHealth_getCpuHeadroom API may return cached result if called more frequently than the interval.

Available since API level 36.

Details

Parameters

outMinIntervalMillis

Non-null output pointer to a int64_t, which will be set to the minimum polling interval in milliseconds.

Returns

0 on success. ENOTSUP if API is unsupported.

ASystemHealth_getGpuHeadroom

Declared in android/system_health.h

int ASystemHealth_getGpuHeadroom(
  const AGpuHeadroomParams *_Nullable params,
  float *_Nonnull outHeadroom
)

Provides an estimate of available GPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was GPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also 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.

Available since API level 36

Details

Parameters

`params`	The params to customize the GPU headroom calculation, or nullptr to use default
`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.

Returns

0 on success. EPIPE if failed to get the GPU headroom. ENOTSUP if API or requested params is unsupported.

ASystemHealth_getGpuHeadroomCalculationWindowRange

Declared in android/system_health.h

int ASystemHealth_getGpuHeadroomCalculationWindowRange(
  int32_t *_Nonnull outMinMillis,
  int32_t *_Nonnull outMaxMillis
)

Gets the range of the calculation window size for GPU headroom.

Available since API level 36.

Details

Parameters

`outMinMillis`	Non-null output pointer to be set to the minimum window size in milliseconds.
`outMaxMillis`	Non-null output pointer to be set to the maximum window size in milliseconds.

Returns

0 on success. ENOTSUP if API is unsupported.

ASystemHealth_getGpuHeadroomMinIntervalMillis

Declared in android/system_health.h

int ASystemHealth_getGpuHeadroomMinIntervalMillis(
  int64_t *_Nonnull outMinIntervalMillis
)

Gets minimum polling interval for calling ASystemHealth_getGpuHeadroom in milliseconds.

The ASystemHealth_getGpuHeadroom API may return cached result if called more frequently than the interval.

Available since API level 36.

Details

Parameters

outMinIntervalMillis

Non-null output pointer to a int64_t, which will be set to the minimum polling interval in milliseconds.

Returns

0 on success. ENOTSUP if API is unsupported.

ASystemHealth_getMaxCpuHeadroomTidsSize

Declared in android/system_health.h

int ASystemHealth_getMaxCpuHeadroomTidsSize(
  size_t *_Nonnull outSize
)

Gets the maximum number of TIDs this device supports for getting CPU headroom.

See ACpuHeadroomParams_setTids.

Available since API level 36.

Details

Parameters

outSize

Non-null output pointer to the max size.

Returns

0 on success. ENOTSUP if the CPU headroom API is unsupported.