Power - Extensions

oneAPI Level Zero Specification - Version 1.18.31

Power - Extension Functions

zesPowerGetLimitsExt

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetLimitsExt(zes_pwr_handle_t hPower, uint32_t *pCount, zes_power_limit_ext_desc_t *pSustained)

Get power limits.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

• This function returns all the power limits associated with the supplied power domain.

Parameters:

• hPower – [in] Power domain handle instance.

• pCount – [in,out] Pointer to the number of power limit descriptors. If count is zero, then the driver shall update the value with the total number of components of this type that are available. If count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

• pSustained – [in,out][optional][range(0, *pCount)] Array of query results for power limit descriptors. If count is less than the number of components of this type that are available, then the driver shall only retrieve that number of components.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hPower

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zesPowerSetLimitsExt

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetLimitsExt(zes_pwr_handle_t hPower, uint32_t *pCount, zes_power_limit_ext_desc_t *pSustained)

Set power limits.

• The application can only modify unlocked members of the limit descriptors returned by zesPowerGetLimitsExt.

• Not all the limits returned by zesPowerGetLimitsExt need to be supplied to this function.

• Limits do not have to be supplied in the same order as returned by zesPowerGetLimitsExt.

• The same limit can be supplied multiple times. Limits are applied in the order in which they are supplied.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hPower – [in] Handle for the component.

• pCount – [in] Pointer to the number of power limit descriptors.

• pSustained – [in][optional][range(0, *pCount)] Array of power limit descriptors.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hPower

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to make these modifications.

• ZE_RESULT_ERROR_NOT_AVAILABLE

  • The device is in use, meaning that the GPU is under Over clocking, applying power limits under overclocking is not supported.

Power - Extension Structures

zes_power_limit_ext_desc_t

Added in version 1.4

struct zes_power_limit_ext_desc_t

Device power/current limit descriptor.

Public Members

zes_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

zes_power_level_t level

[in,out] duration type over which the power draw is measured, i.e. sustained, burst, peak, or critical.

zes_power_source_t source

[out] source of power used by the system, i.e. AC or DC.

zes_limit_unit_t limitUnit

[out] unit used for specifying limit, i.e. current units (milliamps) or power units (milliwatts).

ze_bool_t enabledStateLocked

[out] indicates if the power limit state (enabled/ignored) can be set (false) or is locked (true).

ze_bool_t enabled

[in,out] indicates if the limit is enabled (true) or ignored (false). If enabledStateIsLocked is True, this value is ignored.

ze_bool_t intervalValueLocked

[out] indicates if the interval can be modified (false) or is fixed (true).

int32_t interval

[in,out] power averaging window in milliseconds. If intervalValueLocked is true, this value is ignored.

ze_bool_t limitValueLocked

[out] indicates if the limit can be set (false) or if the limit is fixed (true).

int32_t limit

[in,out] limit value. If limitValueLocked is true, this value is ignored. The value should be provided in the unit specified by limitUnit.

zes_power_ext_properties_t

Added in version 1.4

struct zes_power_ext_properties_t

Extension properties related to device power settings.

• This structure may be returned from zesPowerGetProperties via the pNext member of zes_power_properties_t.

• This structure may also be returned from zesPowerGetProperties via the pNext member of zes_power_ext_properties_t

• Used for determining the power domain level, i.e. card-level v/s package-level v/s stack-level & the factory default power limits.

Public Members

zes_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

zes_power_domain_t domain

[out] domain that the power limit belongs to.

zes_power_limit_ext_desc_t *defaultLimit

[out] the factory default limit of the part.