Power

Contents

Power#

oneAPI Level Zero Specification - Version 1.18.31

Power Functions#

zesPowerGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetProperties(zes_pwr_handle_t hPower, zes_power_properties_t *pProperties)#

Get properties related to a power domain.

  • 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.

  • pProperties – [in,out] Structure that will contain property data.

Returns:

zesPowerGetEnergyCounter#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetEnergyCounter(zes_pwr_handle_t hPower, zes_power_energy_counter_t *pEnergy)#

Get energy counter.

  • 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.

  • pEnergy – [in,out] Will contain the latest snapshot of the energy counter and timestamp when the last counter value was measured.

Returns:

zesPowerGetLimits#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetLimits(zes_pwr_handle_t hPower, zes_power_sustained_limit_t *pSustained, zes_power_burst_limit_t *pBurst, zes_power_peak_limit_t *pPeak)#

Get power limits.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] Use zesPowerGetLimitsExt.

Parameters:

  • hPower – [in] Handle for the component.

  • pSustained – [in,out][optional] The sustained power limit. If this is null, the current sustained power limits will not be returned.

  • pBurst – [in,out][optional] The burst power limit. If this is null, the current peak power limits will not be returned.

  • pPeak – [in,out][optional] The peak power limit. If this is null, the peak power limits will not be returned.

Returns:

zesPowerSetLimits#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetLimits(zes_pwr_handle_t hPower, const zes_power_sustained_limit_t *pSustained, const zes_power_burst_limit_t *pBurst, const zes_power_peak_limit_t *pPeak)#

Set power limits.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] Use zesPowerSetLimitsExt.

Parameters:

  • hPower – [in] Handle for the component.

  • pSustained – [in][optional] The sustained power limit. If this is null, no changes will be made to the sustained power limits.

  • pBurst – [in][optional] The burst power limit. If this is null, no changes will be made to the burst power limits.

  • pPeak – [in][optional] The peak power limit. If this is null, no changes will be made to the peak power limits.

Returns:

zesPowerGetEnergyThreshold#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetEnergyThreshold(zes_pwr_handle_t hPower, zes_energy_threshold_t *pThreshold)#

Get energy threshold.

  • 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.

  • pThreshold – [in,out] Returns information about the energy threshold setting - enabled/energy threshold/process ID.

Returns:

zesPowerSetEnergyThreshold#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetEnergyThreshold(zes_pwr_handle_t hPower, double threshold)#

Set energy threshold.

  • An event ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED will be generated when the delta energy consumed starting from this call exceeds the specified threshold. Use the function zesDeviceEventRegister() to start receiving the event.

  • Only one running process can control the energy threshold at a given time. If another process attempts to change the energy threshold, the error ZE_RESULT_ERROR_NOT_AVAILABLE will be returned. The function zesPowerGetEnergyThreshold() to determine the process ID currently controlling this setting.

  • Calling this function will remove any pending energy thresholds and start counting from the time of this call.

  • Once the energy threshold has been reached and the event generated, the threshold is automatically removed. It is up to the application to request a new threshold.

  • 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.

  • threshold – [in] The energy threshold to be set in joules.

Returns:

zesPowerGetUsage#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetUsage(zes_pwr_handle_t hPower, uint32_t *pInstantPower, uint32_t *pAveragePower)#

Get power usage.

  • The application may call this function from simultaneous threads.

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

  • This function returns the different power usage values associated with the power domain.

  • Computing the average power usage may cause this API to wait and return only after the average power is computed over an interval. Applications that do not need it should pass nullptr for pAveragePower to reduce the time taken by this function.

Parameters:

  • hPower – [in] Handle of the power domain.

  • pInstantPower – [out][optional] Returns the instant power usage in milliwatts. If this is nullptr, the instant power usage will not be returned.

  • pAveragePower – [out][optional] Returns the average power usage in milliwatts. If this is nullptr, the average power usage will not be returned.

Returns:

zesPowerGetLimitsExt2#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerGetLimitsExt2(zes_pwr_handle_t hPower, uint32_t *pLimit)#

Get power limits.

  • The application may call this function from simultaneous threads.

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

  • This function returns the power limit associated with the power domain of the handle.

Parameters:

  • hPower – [in] Power domain handle instance.

  • pLimit – [out] Returns limit value in milliwatts for given power domain.

Returns:

zesPowerSetLimitsExt2#

Added in version 1.16

ZE_APIEXPORT ze_result_t ZE_APICALL zesPowerSetLimitsExt2(zes_pwr_handle_t hPower, const uint32_t limit)#

Set power limits.

  • The application may call this function from simultaneous threads.

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

  • This function sets the power limit associated with the power domain of the handle.

Parameters:

  • hPower – [in] Power domain handle instance.

  • limit – [in] Limit value in milliwatts to be set for given power domain.

Returns:

Power Enums#

zes_power_domain_t#

Added in version 1.4

enum zes_power_domain_t#

Power Domain.

Values:

enumerator ZES_POWER_DOMAIN_UNKNOWN#

The PUnit power domain level cannot be determined.

enumerator ZES_POWER_DOMAIN_CARD#

The PUnit power domain is a card-level power domain.

enumerator ZES_POWER_DOMAIN_PACKAGE#

The PUnit power domain is a package-level power domain.

enumerator ZES_POWER_DOMAIN_STACK#

The PUnit power domain is a stack-level power domain.

enumerator ZES_POWER_DOMAIN_MEMORY#

The PUnit power domain is a memory-level power domain. (since v1.8)

enumerator ZES_POWER_DOMAIN_GPU#

The PUnit power domain is a GPU-level power domain. (since v1.8)

enumerator ZES_POWER_DOMAIN_FORCE_UINT32#

Value marking end of ZES_POWER_DOMAIN_* ENUMs.

zes_power_level_t#

Added in version 1.4

enum zes_power_level_t#

Power Level Type.

Values:

enumerator ZES_POWER_LEVEL_UNKNOWN#

The PUnit power monitoring duration cannot be determined.

enumerator ZES_POWER_LEVEL_SUSTAINED#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a time interval (longer than BURST).

enumerator ZES_POWER_LEVEL_BURST#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a time interval (longer than PEAK).

enumerator ZES_POWER_LEVEL_PEAK#

The PUnit determines effective power draw by computing a moving average of the actual power draw over a very short time interval.

enumerator ZES_POWER_LEVEL_INSTANTANEOUS#

The PUnit predicts effective power draw using the current device configuration (frequency, voltage, etc…) & throttles proactively to stay within the specified limit.

enumerator ZES_POWER_LEVEL_FORCE_UINT32#

Value marking end of ZES_POWER_LEVEL_* ENUMs.

zes_power_source_t#

Added in version 1.4

enum zes_power_source_t#

Power Source Type.

Values:

enumerator ZES_POWER_SOURCE_ANY#

Limit active no matter whether the power source is mains powered or battery powered.

enumerator ZES_POWER_SOURCE_MAINS#

Limit active only when the device is mains powered.

enumerator ZES_POWER_SOURCE_BATTERY#

Limit active only when the device is battery powered.

enumerator ZES_POWER_SOURCE_FORCE_UINT32#

Value marking end of ZES_POWER_SOURCE_* ENUMs.

zes_limit_unit_t#

Added in version 1.4

enum zes_limit_unit_t#

Limit Unit.

Values:

enumerator ZES_LIMIT_UNIT_UNKNOWN#

The PUnit power monitoring unit cannot be determined.

enumerator ZES_LIMIT_UNIT_CURRENT#

The limit is specified in milliamperes of current drawn.

enumerator ZES_LIMIT_UNIT_POWER#

The limit is specified in milliwatts of power generated.

enumerator ZES_LIMIT_UNIT_FORCE_UINT32#

Value marking end of ZES_LIMIT_UNIT_* ENUMs.

Power Structures#

zes_power_properties_t#

Added in version 1.0

struct zes_power_properties_t#

Properties related to device power settings.

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).

ze_bool_t onSubdevice#

[out] True if this resource is located on a sub-device; false means that the resource is on the device of the calling Sysman handle

uint32_t subdeviceId#

[out] If onSubdevice is true, this gives the ID of the sub-device

ze_bool_t canControl#

[out] Software can change the power limits of this domain assuming the user has permissions.

ze_bool_t isEnergyThresholdSupported#

[out] Indicates if this power domain supports the energy threshold event (ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED).

int32_t defaultLimit#

[out] (Deprecated) The factory default TDP power limit of the part in milliwatts. A value of -1 means that this is not known.

int32_t minLimit#

[out] (Deprecated) The minimum power limit in milliwatts that can be requested. A value of -1 means that this is not known.

int32_t maxLimit#

[out] (Deprecated) The maximum power limit in milliwatts that can be requested. A value of -1 means that this is not known.

zes_power_energy_counter_t#

Added in version 1.0

struct zes_power_energy_counter_t#

Energy counter snapshot.

  • Average power is calculated by taking two snapshots (s1, s2) and using the equation: PowerWatts = (s2.energy - s1.energy) / (s2.timestamp - s1.timestamp)

Public Members

uint64_t energy#

[out] The monotonic energy counter in microjoules.

uint64_t timestamp#

[out] Microsecond timestamp when energy was captured. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

zes_power_sustained_limit_t#

Added in version 1.0

struct zes_power_sustained_limit_t#

Sustained power limits.

  • The power controller (Punit) will throttle the operating frequency if the power averaged over a window (typically seconds) exceeds this limit.

  • [DEPRECATED] No longer supported.

Public Members

ze_bool_t enabled#

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power#

[in,out] power limit in milliwatts

int32_t interval#

[in,out] power averaging window (Tau) in milliseconds

zes_power_burst_limit_t#

Added in version 1.0

struct zes_power_burst_limit_t#

Burst power limit.

  • The power controller (Punit) will throttle the operating frequency of the device if the power averaged over a few milliseconds exceeds a limit known as PL2. Typically PL2 > PL1 so that it permits the frequency to burst higher for short periods than would be otherwise permitted by PL1.

  • [DEPRECATED] No longer supported.

Public Members

ze_bool_t enabled#

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power#

[in,out] power limit in milliwatts

zes_power_peak_limit_t#

Added in version 1.0

struct zes_power_peak_limit_t#

Peak power limit.

  • The power controller (Punit) will reactively/proactively throttle the operating frequency of the device when the instantaneous/100usec power exceeds this limit. The limit is known as PL4 or Psys. It expresses the maximum power that can be drawn from the power supply.

  • If this power limit is removed or set too high, the power supply will generate an interrupt when it detects an overcurrent condition and the power controller will throttle the device frequencies down to min. It is thus better to tune the PL4 value in order to avoid such excursions.

  • [DEPRECATED] No longer supported.

Public Members

int32_t powerAC#

[in,out] power limit in milliwatts for the AC power source.

int32_t powerDC#

[in,out] power limit in milliwatts for the DC power source. On input, this is ignored if the product does not have a battery. On output, this will be -1 if the product does not have a battery.

zes_energy_threshold_t#

Added in version 1.0

struct zes_energy_threshold_t#

Energy threshold.

  • .

Public Members

ze_bool_t enable#

[in,out] Indicates if the energy threshold is enabled.

double threshold#

[in,out] The energy threshold in Joules. Will be 0.0 if no threshold has been set.

uint32_t processId#

[in,out] The host process ID that set the energy threshold. Will be 0xFFFFFFFF if no threshold has been set.