Driver - Extensions

Driver - Extensions#

oneAPI Level Zero Specification - Version 1.19.12

Driver - Extension Functions#

zesDriverEventRegisterExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventRegisterExt(zes_driver_handle_t hDriver, zes_event_type_flags_t events)#

Specify the list of driver scoped events to listen to for a given driver.

  • This function registers the driver scoped events the application wants to be notified about. Unlike zesDeviceEventRegister the registration is not tied to a device: the underlying event source is shared by all devices of the driver.

  • Registered events are reported only by zesDriverEventListenExt, in its pDriverEvents argument. As the events are driver scoped they have no device handle to be reported against, so zesDriverEventListen and zesDriverEventListenEx never report them.

  • Calling this function while another thread is blocked in a listen call updates that call, so an event registered after a listen has started can still be reported by it.

  • The application may call this function from simultaneous threads.

Parameters:

  • hDriver – [in] handle of the driver instance

  • events – [in] List of driver scoped events to listen to. Must be 0 or a combination of the driver scoped zes_event_type_flags_t values.

Returns:

zesDriverEventListenExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEventListenExt(zes_driver_handle_t hDriver, uint64_t timeout, uint32_t count, zes_device_handle_t *phDevices, uint32_t *pNumDeviceEvents, zes_event_type_flags_t *pEvents, zes_event_type_flags_t *pDriverEvents)#

Wait for device scoped and driver scoped events to be received from one or more devices.

  • This function extends zesDriverEventListenEx with the ability to report the driver scoped events registered with zesDriverEventRegisterExt.

  • The hDriver, timeout, count, phDevices, pNumDeviceEvents and pEvents arguments behave exactly as in zesDriverEventListenEx.

  • pDriverEvents is optional. When it is nullptr this function behaves exactly like zesDriverEventListenEx and no driver scoped event source is listened to.

  • When pDriverEvents is not nullptr it is cleared on entry and, on return, contains the driver scoped events which have been registered and occurred, i.e. 0 or a combination of the driver scoped zes_event_type_flags_t values.

  • *pNumDeviceEvents accounts for device scoped events only. A driver scoped event which occurs without any device scoped event therefore returns *pNumDeviceEvents set to 0 and *pDriverEvents set to the events which occurred, so an application must check both values.

  • The application should not call this function from simultaneous threads with the same driver handle.

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 device scoped events. If non-zero, check pEvents to determine the devices and events that were received.

  • pEvents – [in,out] An array that will contain the list of device scoped 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.

  • pDriverEvents – [in,out][optional] Returns the driver scoped events which occurred, i.e. 0 or a combination of the driver scoped zes_event_type_flags_t values. When nullptr, driver scoped events are not listened to.

Returns:

zesDriverEnumInfoLogsExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zesDriverEnumInfoLogsExt(zes_driver_handle_t hDriver, uint32_t *pCount, zes_info_log_handle_t *phInfoLogs)#

Get handles to the info logs supported by the driver.

  • An info log is a driver scoped object. Records collected from an info log may originate from any of the devices managed by the driver, and the originating device is reported in the metadata of each record.

  • The application should first call this function with pCount pointing to a value of zero to retrieve the number of info logs available.

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

  • 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 info logs. if count is zero, then the driver shall update the value with the total number of info logs available. if count is greater than the number of info logs available, then the driver shall update the value with the correct number of info logs available.

  • phInfoLogs – [in,out][optional][range(0, *pCount)] array of info log handles. if count is less than the number of info logs available, then the driver shall only retrieve that number of info log handles.

Returns:

In this class