Frequency

Frequency#

oneAPI Level Zero Specification - Version 1.20.41

Frequency Functions#

zesFrequencyGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetProperties(zes_freq_handle_t hFrequency, zes_freq_properties_t *pProperties)#

Get frequency properties - available frequencies.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pProperties – [in,out] The frequency properties for the specified domain.

Returns:

zesFrequencyGetAvailableClocks#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetAvailableClocks(zes_freq_handle_t hFrequency, uint32_t *pCount, double *phFrequency)#

Get available non-overclocked hardware clock frequencies for the frequency domain.

  • The list of available frequencies is returned in order of slowest to fastest.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Sysman handle of the device.

  • pCount – [in,out] pointer to the number of frequencies. if count is zero, then the driver shall update the value with the total number of frequencies that are available. if count is greater than the number of frequencies that are available, then the driver shall update the value with the correct number of frequencies.

  • phFrequency – [in,out][optional][range(0, *pCount)] array of frequencies in units of MHz and sorted from slowest to fastest. if count is less than the number of frequencies that are available, then the driver shall only retrieve that number of frequencies.

Returns:

zesFrequencyGetRange#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetRange(zes_freq_handle_t hFrequency, zes_freq_range_t *pLimits)#

Get current frequency limits.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in,out] The range between which the hardware can operate for the specified domain.

Returns:

zesFrequencySetRange#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencySetRange(zes_freq_handle_t hFrequency, const zes_freq_range_t *pLimits)#

Set frequency range between which the hardware can operate.

  • The application may call this function with the frequency range min and max values set to -1 to request the frequency be (re)set to the default values.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in] The limits between which the hardware can operate for the specified domain.

Returns:

zesFrequencyGetState#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetState(zes_freq_handle_t hFrequency, zes_freq_state_t *pState)#

Get current frequency state - frequency request, actual frequency, TDP limits.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pState – [in,out] Frequency state for the specified domain.

Returns:

zesFrequencyGetThrottleTime#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyGetThrottleTime(zes_freq_handle_t hFrequency, zes_freq_throttle_time_t *pThrottleTime)#

Get frequency throttle time.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hFrequency – [in] Handle for the component.

  • pThrottleTime – [in,out] Will contain a snapshot of the throttle time counters for the specified domain.

Returns:

Frequency Enums#

zes_freq_throttle_reason_flags_t#

Added in version 1.0

enum zes_freq_throttle_reason_flag_t#

Values:

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_AVE_PWR_CAP#

frequency throttled due to average power excursion (PL1)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_BURST_PWR_CAP#

frequency throttled due to burst power excursion (PL2)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_CURRENT_LIMIT#

frequency throttled due to current excursion (PL4)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_THERMAL_LIMIT#

frequency throttled due to thermal excursion (T > TjMax)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_PSU_ALERT#

frequency throttled due to power supply assertion

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_SW_RANGE#

frequency throttled due to software supplied frequency range

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_HW_RANGE#

frequency throttled due to a sub block that has a lower frequency range when it receives clocks

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_VOLTAGE#

frequency throttled due to voltage excursion (since v1.15)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_THERMAL#

frequency throttled due to thermal conditions (since v1.15)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_POWER#

frequency throttled due to power constraints (since v1.15)

enumerator ZES_FREQ_THROTTLE_REASON_FLAG_FORCE_UINT32#

Value marking end of ZES_FREQ_THROTTLE_REASON_FLAG_* ENUMs.

Frequency Structures#

zes_freq_properties_t#

Added in version 1.0

struct zes_freq_properties_t#

Frequency properties.

  • Indicates if this frequency domain can be overclocked (if true, functions such as zesFrequencyOcSetFrequencyTarget() are supported).

  • The min/max hardware frequencies are specified for non-overclock configurations. For overclock configurations, use zesFrequencyOcGetFrequencyTarget() to determine the maximum frequency that can be requested.

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_freq_domain_t type#

[out] The hardware block that this frequency domain controls (GPU, memory, …)

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] Indicates if software can control the frequency of this domain assuming the user has permissions

ze_bool_t isThrottleEventSupported#

[out] Indicates if software can register to receive event ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED

double min#

[out] The minimum hardware clock frequency in units of MHz.

double max#

[out] The maximum non-overclock hardware clock frequency in units of MHz.

zes_freq_range_t#

Added in version 1.0

struct zes_freq_range_t#

Frequency range between which the hardware can operate.

  • When setting limits, they will be clamped to the hardware limits.

  • When setting limits, ensure that the max frequency is greater than or equal to the min frequency specified.

  • When setting limits to return to factory settings, specify -1 for both the min and max limit.

Public Members

double min#

[in,out] The min frequency in MHz below which hardware frequency management will not request frequencies. On input, setting to 0 will permit the frequency to go down to the hardware minimum while setting to -1 will return the min frequency limit to the factory value (can be larger than the hardware min). On output, a negative value indicates that no external minimum frequency limit is in effect.

double max#

[in,out] The max frequency in MHz above which hardware frequency management will not request frequencies. On input, setting to 0 or a very big number will permit the frequency to go all the way up to the hardware maximum while setting to -1 will return the max frequency to the factory value (which can be less than the hardware max). On output, a negative number indicates that no external maximum frequency limit is in effect.

zes_freq_state_t#

Added in version 1.0

struct zes_freq_state_t#

Frequency state.

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

double currentVoltage#

[out] Current voltage in Volts. A negative value indicates that this property is not known.

double request#

[out] The current frequency request in MHz. A negative value indicates that this property is not known.

double tdp#

[out] The maximum frequency in MHz supported under the current TDP conditions. This fluctuates dynamically based on the power and thermal limits of the part. A negative value indicates that this property is not known.

double efficient#

[out] The efficient minimum frequency in MHz. A negative value indicates that this property is not known.

double actual#

[out] The resolved frequency in MHz. A negative value indicates that this property is not known.

zes_freq_throttle_reason_flags_t throttleReasons#

[out] The reasons that the frequency is being limited by the hardware. Returns 0 (frequency not throttled) or a combination of zes_freq_throttle_reason_flag_t.

zes_freq_throttle_time_t#

Added in version 1.0

struct zes_freq_throttle_time_t#

Frequency throttle time snapshot.

  • Percent time throttled is calculated by taking two snapshots (s1, s2) and using the equation: throttled = (s2.throttleTime - s1.throttleTime) / (s2.timestamp - s1.timestamp)

Public Members

uint64_t throttleTime#

[out] The monotonic counter of time in microseconds that the frequency has been limited by the hardware.

uint64_t timestamp#

[out] Microsecond timestamp when throttleTime 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.