Frequency

Contents

Frequency#

oneAPI Level Zero Specification - Version 1.18.31

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:

zesFrequencyOcGetCapabilities#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetCapabilities(zes_freq_handle_t hFrequency, zes_oc_capabilities_t *pOcCapabilities)#

Get the overclocking capabilities.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcCapabilities – [in,out] Pointer to the capabilities structure.

Returns:

zesFrequencyOcGetFrequencyTarget#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetFrequencyTarget(zes_freq_handle_t hFrequency, double *pCurrentOcFrequency)#

Get the current overclocking frequency target, if extended moded is supported, will returned in 1 Mhz granularity.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentOcFrequency – [out] Overclocking Frequency in MHz, if extended moded is supported, will returned in 1 Mhz granularity, else, in multiples of 50 Mhz. This cannot be greater than the maxOcFrequency member of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetFrequencyTarget#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetFrequencyTarget(zes_freq_handle_t hFrequency, double CurrentOcFrequency)#

Set the current overclocking frequency target, if extended moded is supported, can be set in 1 Mhz granularity.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentOcFrequency – [in] Overclocking Frequency in MHz, if extended moded is supported, it could be set in 1 Mhz granularity, else, in multiples of 50 Mhz. This cannot be greater than the maxOcFrequency member of zes_oc_capabilities_t.

Returns:

zesFrequencyOcGetVoltageTarget#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetVoltageTarget(zes_freq_handle_t hFrequency, double *pCurrentVoltageTarget, double *pCurrentVoltageOffset)#

Get the current overclocking voltage settings.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentVoltageTarget – [out] Overclock voltage in Volts. This cannot be greater than the maxOcVoltage member of zes_oc_capabilities_t.

  • pCurrentVoltageOffset – [out] This voltage offset is applied to all points on the voltage/frequency curve, including the new overclock voltageTarget. Valid range is between the minOcVoltageOffset and maxOcVoltageOffset members of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetVoltageTarget#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetVoltageTarget(zes_freq_handle_t hFrequency, double CurrentVoltageTarget, double CurrentVoltageOffset)#

Set the current overclocking voltage settings.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentVoltageTarget – [in] Overclock voltage in Volts. This cannot be greater than the maxOcVoltage member of zes_oc_capabilities_t.

  • CurrentVoltageOffset – [in] This voltage offset is applied to all points on the voltage/frequency curve, include the new overclock voltageTarget. Valid range is between the minOcVoltageOffset and maxOcVoltageOffset members of zes_oc_capabilities_t.

Returns:

zesFrequencyOcSetMode#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetMode(zes_freq_handle_t hFrequency, zes_oc_mode_t CurrentOcMode)#

Set the current overclocking mode.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • CurrentOcMode – [in] Current Overclocking Mode zes_oc_mode_t.

Returns:

zesFrequencyOcGetMode#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetMode(zes_freq_handle_t hFrequency, zes_oc_mode_t *pCurrentOcMode)#

Get the current overclocking mode.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pCurrentOcMode – [out] Current Overclocking Mode zes_oc_mode_t.

Returns:

zesFrequencyOcGetIccMax#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetIccMax(zes_freq_handle_t hFrequency, double *pOcIccMax)#

Get the maximum current limit setting.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcIccMax – [in,out] Will contain the maximum current limit in Amperes on successful return.

Returns:

zesFrequencyOcSetIccMax#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetIccMax(zes_freq_handle_t hFrequency, double ocIccMax)#

Change the maximum current limit setting.

  • Setting ocIccMax to 0.0 will return the value to the factory default.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • ocIccMax – [in] The new maximum current limit in Amperes.

Returns:

zesFrequencyOcGetTjMax#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcGetTjMax(zes_freq_handle_t hFrequency, double *pOcTjMax)#

Get the maximum temperature limit setting.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pOcTjMax – [in,out] Will contain the maximum temperature limit in degrees Celsius on successful return.

Returns:

zesFrequencyOcSetTjMax#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFrequencyOcSetTjMax(zes_freq_handle_t hFrequency, double ocTjMax)#

Change the maximum temperature limit setting.

  • Setting ocTjMax to 0.0 will return the value to the factory default.

  • The application may call this function from simultaneous threads.

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

  • [DEPRECATED] No longer supported.

Parameters:

  • hFrequency – [in] Handle for the component.

  • ocTjMax – [in] The new maximum temperature limit in degrees Celsius.

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.

zes_oc_mode_t#

Added in version 1.0

enum zes_oc_mode_t#

Overclocking modes.

  • [DEPRECATED] No longer supported.

Values:

enumerator ZES_OC_MODE_OFF#

Overclocking if off - hardware is running using factory default voltages/frequencies.

enumerator ZES_OC_MODE_OVERRIDE#

Overclock override mode - In this mode, a fixed user-supplied voltage is applied independent of the frequency request. The maximum permitted frequency can also be increased. This mode disables INTERPOLATIVE and FIXED modes.

enumerator ZES_OC_MODE_INTERPOLATIVE#

Overclock interpolative mode - In this mode, the voltage/frequency curve can be extended with a new voltage/frequency point that will be interpolated. The existing voltage/frequency points can also be offset (up or down) by a fixed voltage. This mode disables FIXED and OVERRIDE modes.

enumerator ZES_OC_MODE_FIXED#

Overclocking fixed Mode - In this mode, hardware will disable most frequency throttling and lock the frequency and voltage at the specified overclock values. This mode disables OVERRIDE and INTERPOLATIVE modes. This mode can damage the part, most of the protections are disabled on this mode.

enumerator ZES_OC_MODE_FORCE_UINT32#

Value marking end of ZES_OC_MODE_* 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.

zes_oc_capabilities_t#

Added in version 1.0

struct zes_oc_capabilities_t#

Overclocking properties.

  • Provides all the overclocking capabilities and properties supported by the device for the frequency domain.

  • [DEPRECATED] No longer supported.

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

ze_bool_t isOcSupported#

[out] Indicates if any overclocking features are supported on this frequency domain.

double maxFactoryDefaultFrequency#

[out] Factory default non-overclock maximum frequency in Mhz.

double maxFactoryDefaultVoltage#

[out] Factory default voltage used for the non-overclock maximum frequency in MHz.

double maxOcFrequency#

[out] Maximum hardware overclocking frequency limit in Mhz.

double minOcVoltageOffset#

[out] The minimum voltage offset that can be applied to the voltage/frequency curve. Note that this number can be negative.

double maxOcVoltageOffset#

[out] The maximum voltage offset that can be applied to the voltage/frequency curve.

double maxOcVoltage#

[out] The maximum overclock voltage that hardware supports.

ze_bool_t isTjMaxSupported#

[out] Indicates if the maximum temperature limit (TjMax) can be changed for this frequency domain.

ze_bool_t isIccMaxSupported#

[out] Indicates if the maximum current (IccMax) can be changed for this frequency domain.

ze_bool_t isHighVoltModeCapable#

[out] Indicates if this frequency domains supports a feature to set very high voltages.

ze_bool_t isHighVoltModeEnabled#

[out] Indicates if very high voltages are permitted on this frequency domain.

ze_bool_t isExtendedModeSupported#

[out] Indicates if the extended overclocking features are supported. If this is supported, increments are on 1 Mhz basis.

ze_bool_t isFixedModeSupported#

[out] Indicates if the fixed mode is supported. In this mode, hardware will disable most frequency throttling and lock the frequency and voltage at the specified overclock values.