Driver

Driver#

oneAPI Level Zero Specification - Version 1.18.31

Driver Functions#

zesDriverEventListen#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventListen(ze_driver_handle_t hDriver, uint32_t timeout, uint32_t count, zes_device_handle_t *phDevices, uint32_t *pNumDeviceEvents, zes_event_type_flags_t *pEvents)#

Wait for events to be received from a one or more devices.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then will check status and return immediately; if UINT32_MAX, then function will not return until events arrive.

  • count – [in] Number of device handles in phDevices.

  • phDevices – [in][range(0, count)] Device handles to listen to for events. Only devices from the provided driver handle can be specified in this list.

  • pNumDeviceEvents – [in,out] Will contain the actual number of devices in phDevices that generated events. If non-zero, check pEvents to determine the devices and events that were received.

  • pEvents – [in,out] An array that will continue the list of events for each device listened in phDevices. This array must be at least as big as count. For every device handle in phDevices, this will provide the events that occurred for that device at the same position in this array. If no event was received for a given device, the corresponding array entry will be zero.

Returns:

zesDriverEventListenEx#

Added in version 1.1

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventListenEx(ze_driver_handle_t hDriver, uint64_t timeout, uint32_t count, zes_device_handle_t *phDevices, uint32_t *pNumDeviceEvents, zes_event_type_flags_t *pEvents)#

Wait for events to be received from a one or more devices.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • timeout – [in] if non-zero, then indicates the maximum time (in milliseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then will check status and return immediately; if UINT64_MAX, then function will not return until events arrive.

  • count – [in] Number of device handles in phDevices.

  • phDevices – [in][range(0, count)] Device handles to listen to for events. Only devices from the provided driver handle can be specified in this list.

  • pNumDeviceEvents – [in,out] Will contain the actual number of devices in phDevices that generated events. If non-zero, check pEvents to determine the devices and events that were received.

  • pEvents – [in,out] An array that will continue the list of events for each device listened in phDevices. This array must be at least as big as count. For every device handle in phDevices, this will provide the events that occurred for that device at the same position in this array. If no event was received for a given device, the corresponding array entry will be zero.

Returns:

zesDriverGet#

Added in version 1.5

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGet(uint32_t *pCount, zes_driver_handle_t *phDrivers)#

Retrieves sysman driver instances.

  • A sysman driver represents a collection of physical devices.

  • Multiple calls to this function will return identical sysman driver handles, in the same order.

  • The application may pass nullptr for pDrivers when only querying the number of sysman drivers.

  • The application may call this function from simultaneous threads.

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

Parameters:

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

  • phDrivers – [in,out][optional][range(0, *pCount)] array of sysman driver instance handles. if count is less than the number of sysman drivers available, then the loader shall only retrieve that number of sysman drivers.

Returns:

zesDriverGetExtensionProperties#

Added in version 1.8

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGetExtensionProperties(zes_driver_handle_t hDriver, uint32_t *pCount, zes_driver_extension_properties_t *pExtensionProperties)#

Retrieves extension properties.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

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

  • pExtensionProperties – [in,out][optional][range(0, *pCount)] array of query results for extension properties. if count is less than the number of extension properties available, then driver shall only retrieve that number of extension properties.

Returns:

zesDriverGetExtensionFunctionAddress#

Added in version 1.8

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverGetExtensionFunctionAddress(zes_driver_handle_t hDriver, const char *name, void **ppFunctionAddress)#

Retrieves function pointer for vendor-specific or experimental extensions.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hDriver – [in] handle of the driver instance

  • name – [in] extension function name

  • ppFunctionAddress – [out] pointer to function pointer

Returns:

Driver Enums#

zes_event_type_flags_t#

Added in version 1.0

enum zes_event_type_flag_t#

Values:

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_DETACH#

Event is triggered when the device is no longer available (due to a reset or being disabled).

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_ATTACH#

Event is triggered after the device is available again.

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_ENTER#

Event is triggered when the driver is about to put the device into a deep sleep state

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_SLEEP_STATE_EXIT#

Event is triggered when the driver is waking the device up from a deep sleep state

enumerator ZES_EVENT_TYPE_FLAG_FREQ_THROTTLED#

Event is triggered when the frequency starts being throttled.

enumerator ZES_EVENT_TYPE_FLAG_ENERGY_THRESHOLD_CROSSED#

Event is triggered when the energy consumption threshold is reached (use zesPowerSetEnergyThreshold() to configure).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_CRITICAL#

Event is triggered when the critical temperature is reached (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD1#

Event is triggered when the temperature crosses threshold 1 (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_TEMP_THRESHOLD2#

Event is triggered when the temperature crosses threshold 2 (use zesTemperatureSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_MEM_HEALTH#

Event is triggered when the health of device memory changes.

enumerator ZES_EVENT_TYPE_FLAG_FABRIC_PORT_HEALTH#

Event is triggered when the health of fabric ports change.

enumerator ZES_EVENT_TYPE_FLAG_PCI_LINK_HEALTH#

Event is triggered when the health of the PCI link changes.

enumerator ZES_EVENT_TYPE_FLAG_RAS_CORRECTABLE_ERRORS#

Event is triggered when accelerator RAS correctable errors cross thresholds (use zesRasSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_RAS_UNCORRECTABLE_ERRORS#

Event is triggered when accelerator RAS uncorrectable errors cross thresholds (use zesRasSetConfig() to configure - disabled by default).

enumerator ZES_EVENT_TYPE_FLAG_DEVICE_RESET_REQUIRED#

Event is triggered when the device needs to be reset (use zesDeviceGetState() to determine the reasons for the reset).

enumerator ZES_EVENT_TYPE_FLAG_SURVIVABILITY_MODE_DETECTED#

Event is triggered when graphics driver encounter an error condition. (since v1.9)

enumerator ZES_EVENT_TYPE_FLAG_FORCE_UINT32#

Value marking end of ZES_EVENT_TYPE_FLAG_* ENUMs.

Driver Structures#

zes_driver_extension_properties_t#

Added in version 1.8

struct zes_driver_extension_properties_t#

Extension properties queried using zesDriverGetExtensionProperties.

Public Members

char name[ZES_MAX_EXTENSION_NAME]#

[out] extension name

uint32_t version#

[out] extension version using ZE_MAKE_VERSION