Temperature

oneAPI Level Zero Specification - Version 1.18.31

Temperature Functions

zesTemperatureGetProperties

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetProperties(zes_temp_handle_t hTemperature, zes_temp_properties_t *pProperties)

Get temperature sensor properties.

• The application may call this function from simultaneous threads.

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

Parameters:

• hTemperature – [in] Handle for the component.

• pProperties – [in,out] Will contain the temperature sensor properties.

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 == hTemperature

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

zesTemperatureGetConfig

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetConfig(zes_temp_handle_t hTemperature, zes_temp_config_t *pConfig)

Get temperature configuration for this sensor - which events are triggered and the trigger conditions.

• The application may call this function from simultaneous threads.

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

Parameters:

• hTemperature – [in] Handle for the component.

• pConfig – [in,out] Returns current configuration.

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_DEPENDENCY_UNAVAILABLE

• 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 == hTemperature

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pConfig

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

  • Temperature thresholds are not supported on this temperature sensor. Generally this is only supported for temperature sensor ZES_TEMP_SENSORS_GLOBAL.

  • One or both of the thresholds is not supported. Check the isThreshold1Supported and isThreshold2Supported members of zes_temp_properties_t.

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to request this feature.

zesTemperatureSetConfig

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureSetConfig(zes_temp_handle_t hTemperature, const zes_temp_config_t *pConfig)

Set temperature configuration for this sensor - indicates which events are triggered and the trigger conditions.

• Events ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL will be triggered when temperature reaches the critical range. Use the function zesDeviceEventRegister() to start receiving this event.

• Events ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 and ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 will be generated when temperature cross the thresholds set using this function. Use the function zesDeviceEventRegister() to start receiving these events.

• Only one running process can set the temperature configuration at a time. If another process attempts to change the configuration, the error ZE_RESULT_ERROR_NOT_AVAILABLE will be returned. The function zesTemperatureGetConfig() will return the process ID currently controlling these settings.

• The application may call this function from simultaneous threads.

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

Parameters:

• hTemperature – [in] Handle for the component.

• pConfig – [in] New configuration.

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_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 == hTemperature

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pConfig

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

  • Temperature thresholds are not supported on this temperature sensor. Generally they are only supported for temperature sensor ZES_TEMP_SENSORS_GLOBAL.

  • Enabling the critical temperature event is not supported. Check the isCriticalTempSupported member of zes_temp_properties_t.

  • One or both of the thresholds is not supported. Check the isThreshold1Supported and isThreshold2Supported members of zes_temp_properties_t.

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to request this feature.

• ZE_RESULT_ERROR_NOT_AVAILABLE

  • Another running process is controlling these settings.

• ZE_RESULT_ERROR_INVALID_ARGUMENT

  • One or both the thresholds is above TjMax (see zesFrequencyOcGetTjMax()). Temperature thresholds must be below this value.

zesTemperatureGetState

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesTemperatureGetState(zes_temp_handle_t hTemperature, double *pTemperature)

Get the temperature from a specified sensor.

• The application may call this function from simultaneous threads.

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

Parameters:

• hTemperature – [in] Handle for the component.

• pTemperature – [in,out] Will contain the temperature read from the specified sensor in degrees Celsius.

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 == hTemperature

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pTemperature

Temperature Enums

zes_temp_sensors_t

Added in version 1.0

enum zes_temp_sensors_t

Temperature sensors.

Values:

enumerator ZES_TEMP_SENSORS_GLOBAL

The maximum temperature across all device sensors.

enumerator ZES_TEMP_SENSORS_GPU

The maximum temperature across all sensors in the GPU.

enumerator ZES_TEMP_SENSORS_MEMORY

The maximum temperature across all sensors in the local memory.

enumerator ZES_TEMP_SENSORS_GLOBAL_MIN

The minimum temperature across all device sensors.

enumerator ZES_TEMP_SENSORS_GPU_MIN

The minimum temperature across all sensors in the GPU.

enumerator ZES_TEMP_SENSORS_MEMORY_MIN

The minimum temperature across all sensors in the local device memory.

enumerator ZES_TEMP_SENSORS_GPU_BOARD

The maximum temperature across all sensors in the GPU Board. (since v1.8)

enumerator ZES_TEMP_SENSORS_GPU_BOARD_MIN

The minimum temperature across all sensors in the GPU Board. (since v1.8)

enumerator ZES_TEMP_SENSORS_VOLTAGE_REGULATOR

The maximum temperature across all sensors in the Voltage Regulator. (since v1.10)

enumerator ZES_TEMP_SENSORS_COMPOSITE

The normalized temperature across the SOC, Memory and Voltage Regulators at which shutdown will occur (since v1.18)

enumerator ZES_TEMP_SENSORS_FORCE_UINT32

Value marking end of ZES_TEMP_SENSORS_* ENUMs.

Temperature Structures

zes_temp_properties_t

Added in version 1.0

struct zes_temp_properties_t

Temperature sensor properties.

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_temp_sensors_t type

[out] Which part of the device the temperature sensor measures

ze_bool_t onSubdevice

[out] True if the 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

double maxTemperature

[out] Will contain the maximum temperature for the specific device in degrees Celsius.

ze_bool_t isCriticalTempSupported

[out] Indicates if the critical temperature event ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL is supported

ze_bool_t isThreshold1Supported

[out] Indicates if the temperature threshold 1 event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 is supported

ze_bool_t isThreshold2Supported

[out] Indicates if the temperature threshold 2 event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 is supported

zes_temp_threshold_t

Added in version 1.0

struct zes_temp_threshold_t

Temperature sensor threshold.

Public Members

ze_bool_t enableLowToHigh

[in,out] Trigger an event when the temperature crosses from below the threshold to above.

ze_bool_t enableHighToLow

[in,out] Trigger an event when the temperature crosses from above the threshold to below.

double threshold

[in,out] The threshold in degrees Celsius.

zes_temp_config_t

Added in version 1.0

struct zes_temp_config_t

Temperature configuration - which events should be triggered and the trigger conditions.

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 enableCritical

[in,out] Indicates if event ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL should be triggered by the driver.

zes_temp_threshold_t threshold1

[in,out] Configuration controlling if and when event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1 should be triggered by the driver.

zes_temp_threshold_t threshold2

[in,out] Configuration controlling if and when event ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2 should be triggered by the driver.