Event

Contents

Event#

oneAPI Level Zero Specification - Version 1.18.31

Event Functions#

zeEventCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCreate(ze_event_pool_handle_t hEventPool, const ze_event_desc_t *desc, ze_event_handle_t *phEvent)#

Creates an event from the pool.

  • An event is used to communicate fine-grain host-to-device, device-to-host or device-to-device dependencies have completed.

  • The application must ensure the location in the pool is not being used by another event.

  • The application must not call this function from simultaneous threads with the same event pool handle.

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

Remark

Analogues

  • clCreateUserEvent

  • vkCreateEvent

Parameters:

  • hEventPool – [in] handle of the event pool

  • desc – [in] pointer to event descriptor

  • phEvent – [out] pointer to handle of event object created

Returns:

zeEventDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventDestroy(ze_event_handle_t hEvent)#

Deletes an event object.

  • The application must ensure the device is not currently referencing the event before it is deleted.

  • The implementation of this function may immediately free all Host and Device allocations associated with this event.

  • The application must not call this function from simultaneous threads with the same event handle.

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

Remark

Analogues

  • clReleaseEvent

  • vkDestroyEvent

Parameters:

hEvent – [in][release] handle of event object to destroy

Returns:

zeEventHostSignal#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSignal(ze_event_handle_t hEvent)#

Signals a event from host.

  • The duration of an event created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP or ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flags is undefined. However, for consistency and orthogonality the event will report correctly as signaled when used by other event API functionality.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clSetUserEventStatus

Parameters:

hEvent – [in] handle of the event

Returns:

zeEventHostSynchronize#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostSynchronize(ze_event_handle_t hEvent, uint64_t timeout)#

The current host thread waits on an event to be signaled.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clWaitForEvents

Parameters:

  • hEvent – [in] handle of the event

  • timeout – [in] if non-zero, then indicates the maximum time (in nanoseconds) to yield before returning ZE_RESULT_SUCCESS or ZE_RESULT_NOT_READY; if zero, then operates exactly like zeEventQueryStatus; if UINT64_MAX, then function will not return until complete or device is lost. Due to external dependencies, timeout may be rounded to the closest value allowed by the accuracy of those dependencies.

Returns:

zeEventQueryStatus#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryStatus(ze_event_handle_t hEvent)#

Queries an event object’s status on the host.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • clGetEventInfo

  • vkGetEventStatus

Parameters:

hEvent – [in] handle of the event

Returns:

zeEventHostReset#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventHostReset(ze_event_handle_t hEvent)#

The current host thread resets an event back to not signaled state.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkResetEvent

Parameters:

hEvent – [in] handle of the event

Returns:

zeEventQueryKernelTimestamp#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventQueryKernelTimestamp(ze_event_handle_t hEvent, ze_kernel_timestamp_result_t *dstptr)#

Queries an event’s timestamp value on the host.

Parameters:

  • hEvent – [in] handle of the event

  • dstptr – [in,out] pointer to memory for where timestamp result will be written.

Returns:

zeEventGetEventPool#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetEventPool(ze_event_handle_t hEvent, ze_event_pool_handle_t *phEventPool)#

Gets the handle of the event pool for the event.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • phEventPool – [out] handle of the event pool for the event

Returns:

zeEventGetSignalScope#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetSignalScope(ze_event_handle_t hEvent, ze_event_scope_flags_t *pSignalScope)#

Gets the signal event scope.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • pSignalScope – [out] signal event scope. This is the scope of relevant cache hierarchies that are flushed on a signal action before the event is triggered. May be 0 or a valid combination of ze_event_scope_flag_t.

Returns:

zeEventGetWaitScope#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetWaitScope(ze_event_handle_t hEvent, ze_event_scope_flags_t *pWaitScope)#

Gets the wait event scope.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hEvent – [in] handle of the event

  • pWaitScope – [out] wait event scope. This is the scope of relevant cache hierarchies invalidated on a wait action after the event is complete. May be 0 or a valid combination of ze_event_scope_flag_t.

Returns:

zeEventCounterBasedCreate#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCounterBasedCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_event_counter_based_desc_t *desc, ze_event_handle_t *phEvent)#

Creates Counter Based Event.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • desc – [in] pointer to counter based event descriptor

  • phEvent – [out] pointer to handle of event object created

Returns:

zeEventCounterBasedGetIpcHandle#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCounterBasedGetIpcHandle(ze_event_handle_t hEvent, ze_ipc_event_counter_based_handle_t *phIpc)#

Gets an IPC counter based event handle that can be shared with another process.

  • When the event was created with ZE_EVENT_COUNTER_BASED_FLAG_IPC_BIDIRECTIONAL, it may be shared before it is enqueued for signaling for the first time, and the returned handle remains valid after the event state is replaced by a signal operation. It does not have to be obtained again.

  • Without that flag, a handle represents the state captured at the time of this call. A new handle must be obtained every time the state is replaced, and this function returns ZE_RESULT_ERROR_INVALID_ARGUMENT for an event that has not been enqueued for signaling yet.

Parameters:

  • hEvent – [in] handle of event object

  • phIpc – [out] Returned IPC event handle

Returns:

zeEventCounterBasedOpenIpcHandle#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCounterBasedOpenIpcHandle(ze_context_handle_t hContext, ze_ipc_event_counter_based_handle_t hIpc, ze_event_handle_t *phEvent)#

Opens an IPC event handle to retrieve from another process.

  • IPC sharing is bi-directional when the exported event was created with ZE_EVENT_COUNTER_BASED_FLAG_IPC_BIDIRECTIONAL. The opened event then refers to the same synchronization point as the event in the exporting process and may be used for waiting, querying and signaling. Without that flag the opened event holds the state captured when its handle was obtained, may be used only for waiting and querying, and must be opened again every time the state is replaced in the exporting process.

  • With bi-directional sharing, the opened event remains valid after its state is replaced by a signal operation performed in either process. It does not have to be opened again, and both processes observe the latest state.

  • With bi-directional sharing, the application must keep both processes alive for as long as the opened event is used. Waiting on, querying or signaling the event after the process that produced the latest state has exited results in undefined behavior.

  • The hContext parameter has no requirement to match the context that was used to create the event in the exporting process. Any context of the importing process may be used, including the driver’s default context.

  • Device association of the opened event depends on its current state at the time of the call: if the event has not yet been enqueued for signaling, no device is yet associated with it; if the event has been enqueued for signaling, it is associated with the device performing that signal operation.

  • With bi-directional sharing, any device of the importing process may signal the opened event. Enqueuing a signal operation overwrites the previous tracking point.

  • A device may wait on the opened event only if it has P2P access to the device associated with the current tracking point. The set of devices that may wait therefore depends on the P2P capabilities relative to the signaling device.

Parameters:

  • hContext – [in] handle of the context object to associate with the IPC event handle

  • hIpc – [in] IPC event handle

  • phEvent – [out] pointer handle of event object created

Returns:

zeEventCounterBasedCloseIpcHandle#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCounterBasedCloseIpcHandle(ze_event_handle_t hEvent)#

Closes an IPC event handle in the current process.

Parameters:

hEvent – [in][release] handle of event object

Returns:

zeEventCounterBasedGetDeviceAddress#

Added in version 1.15

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventCounterBasedGetDeviceAddress(ze_event_handle_t hEvent, uint64_t *completionValue, uint64_t *deviceAddress)#

Returns Counter Based Event completion value (counter) and its device address.

Parameters:

  • hEvent – [in] handle of event object

  • completionValue – [in][out] completion value

  • deviceAddress – [in][out] counter device address

Returns:

zeEventGetCounterBasedFlags#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeEventGetCounterBasedFlags(ze_event_handle_t hEvent, ze_event_counter_based_flags_t *pFlags)#

Gets counter based flags of an event.

Parameters:

  • hEvent – [in] handle of the event

  • pFlags – [out] flags used during creation of a counter based event; may be 0 or a valid combination of ze_event_counter_based_flag_t

Returns:

Event Enums#

ze_event_scope_flags_t#

Added in version 1.0

enum ze_event_scope_flag_t#

Values:

enumerator ZE_EVENT_SCOPE_FLAG_SUBDEVICE#

cache hierarchies are flushed or invalidated sufficient for local sub-device access

enumerator ZE_EVENT_SCOPE_FLAG_DEVICE#

cache hierarchies are flushed or invalidated sufficient for global device access and peer device access

enumerator ZE_EVENT_SCOPE_FLAG_HOST#

cache hierarchies are flushed or invalidated sufficient for device and host access

enumerator ZE_EVENT_SCOPE_FLAG_FORCE_UINT32#

Value marking end of ZE_EVENT_SCOPE_FLAG_* ENUMs.

ze_event_counter_based_flags_t#

Added in version 1.15

enum ze_event_counter_based_flag_t#

Values:

enumerator ZE_EVENT_COUNTER_BASED_FLAG_IMMEDIATE#

Counter-based event is used for immediate command lists (default)

enumerator ZE_EVENT_COUNTER_BASED_FLAG_NON_IMMEDIATE#

Counter-based event is used for non-immediate command lists.

enumerator ZE_EVENT_COUNTER_BASED_FLAG_HOST_VISIBLE#

Signals and waits are also visible to host.

enumerator ZE_EVENT_COUNTER_BASED_FLAG_IPC#

Event can be shared across processes for waiting.

enumerator ZE_EVENT_COUNTER_BASED_FLAG_DEVICE_TIMESTAMP#

Event contains timestamps populated in the device time domain. Implementation of this can be vendor specific, but typically pulled from timers on the offload device and not the host. Cannot be combined with ZE_EVENT_COUNTER_BASED_FLAG_HOST_TIMESTAMP

enumerator ZE_EVENT_COUNTER_BASED_FLAG_HOST_TIMESTAMP#

Indicates that event will contain timestamps converted to the host time domain Cannot be combined with ZE_EVENT_COUNTER_BASED_FLAG_DEVICE_TIMESTAMP It is recommended to use this flag for most users that want to correlate timestamps from the host and device into a single timeline. For host timestamps see zeDeviceGetGlobalTimestamps.

enumerator ZE_EVENT_COUNTER_BASED_FLAG_GRAPH_EXTERNAL#

Counter-based event is used for synchronization between recorded graph commands and commands submitted outside the graph (see zeGraphInstantiateExt in ZE_RECORD_REPLAY_GRAPH_EXT_NAME for details). (since v1.17)

enumerator ZE_EVENT_COUNTER_BASED_FLAG_IPC_BIDIRECTIONAL#

Extends ZE_EVENT_COUNTER_BASED_FLAG_IPC with bi-directional sharing. Event opened in another process observes the latest state and can also be used for signaling. Must be combined with ZE_EVENT_COUNTER_BASED_FLAG_IPC (since v1.18)

enumerator ZE_EVENT_COUNTER_BASED_FLAG_FORCE_UINT32#

Value marking end of ZE_EVENT_COUNTER_BASED_FLAG_* ENUMs.

ze_event_sync_mode_flags_t#

Added in version 1.15

enum ze_event_sync_mode_flag_t#

Values:

enumerator ZE_EVENT_SYNC_MODE_FLAG_LOW_POWER_WAIT#

Low power host synchronization mode, for better CPU utilization.

enumerator ZE_EVENT_SYNC_MODE_FLAG_SIGNAL_INTERRUPT#

Generate interrupt when Event is signalled on Device. It may be used to optimize low power CPU synchronization

enumerator ZE_EVENT_SYNC_MODE_FLAG_EXTERNAL_INTERRUPT_WAIT#

Host synchronization APIs wait for external interrupt id. Can be used only for Counter Based Events

enumerator ZE_EVENT_SYNC_MODE_FLAG_FORCE_UINT32#

Value marking end of ZE_EVENT_SYNC_MODE_FLAG_* ENUMs.

Event Structures#

ze_device_event_properties_t#

Added in version 1.15

struct ze_device_event_properties_t#

Device Event properties struct. Can be passed as pNext to ze_device_properties_t to obtain properties.

Public Members

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

ze_device_event_properties_flags_t flags#

[out] Supported Event properties. Valid combination of ze_device_event_properties_flag_t.

ze_event_sync_mode_desc_t#

Added in version 1.15

struct ze_event_sync_mode_desc_t#

Event sync mode descriptor.

Public Members

ze_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_event_sync_mode_flags_t syncModeFlags#

[in] valid combination of ze_event_sync_mode_flag_t

uint32_t externalInterruptId#

[in] External interrupt id. Used only when ZE_EVENT_SYNC_MODE_FLAG_EXTERNAL_INTERRUPT_WAIT flag is set

ze_event_desc_t#

Added in version 1.0

struct ze_event_desc_t#

Event descriptor.

Public Members

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

uint32_t index#

[in] index of the event within the pool; must be less than the count specified during pool creation

ze_event_scope_flags_t signal#

[in] defines the scope of relevant cache hierarchies to flush on a signal action before the event is triggered. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are flushed.

ze_event_scope_flags_t wait#

[in] defines the scope of relevant cache hierarchies to invalidate on a wait action after the event is complete. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are invalidated.

ze_event_counter_based_desc_t#

Added in version 1.15

struct ze_event_counter_based_desc_t#

Counter Based Event descriptor.

Public Members

ze_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_event_counter_based_flags_t flags#

[in] counter based event flags. Must be 0 (default) or a valid combination of ze_event_counter_based_flag_t

ze_event_scope_flags_t signal#

[in] defines the scope of relevant cache hierarchies to flush on a signal action before the event is triggered. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are flushed.

ze_event_scope_flags_t wait#

[in] defines the scope of relevant cache hierarchies to invalidate on a wait action after the event is complete. must be 0 (default) or a valid combination of ze_event_scope_flag_t; default behavior is synchronization within the command list only, no additional cache hierarchies are invalidated.

ze_event_counter_based_external_sync_allocation_desc_t#

Added in version 1.15

struct ze_event_counter_based_external_sync_allocation_desc_t#

Counter Based Event external sync allocation descriptor. Passed as pNext to ze_event_counter_based_desc_t.

Public Members

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

uint64_t *deviceAddress#

[in] device address for external synchronization allocation

uint64_t *hostAddress#

[in] host address for external synchronization allocation

uint64_t completionValue#

[in] completion value for external synchronization allocation. Must not exceed the value returned by zeDeviceGetCounterBasedEventMaxValue. User is also responsible for ensuring that any value written by the application to deviceAddress or hostAddress does not exceed that maximum.

ze_event_counter_based_external_aggregate_storage_desc_t#

Added in version 1.15

struct ze_event_counter_based_external_aggregate_storage_desc_t#

Counter Based Event external aggregate storage. Passed as pNext to ze_event_counter_based_desc_t.

Public Members

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

uint64_t *deviceAddress#

[in] device address that would be updated with atomic_add upon signaling of this event, must be device USM memory. When this event is signaled from append operations that execute on more than one device, the driver performs cross-device (peer) atomic updates to this address. Not all devices support cross-device atomic operations; the user must ensure atomics are supported between the involved devices (see ZE_DEVICE_P2P_PROPERTY_FLAG_ATOMICS returned by zeDeviceGetP2PProperties, and cross-device capabilities returned by zeDeviceGetMemoryAccessProperties). Using cross-device signaling on devices that do not support cross-device atomics results in undefined behavior.

uint64_t incrementValue#

[in] value which would by atomically added upon each completion

uint64_t completionValue#

[in] final completion value, when value under deviceAddress is equal or greater then this value then event is considered as completed. Must not exceed the value returned by zeDeviceGetCounterBasedEventMaxValue. User is responsible for ensuring that the value aggregated under deviceAddress (initial value plus any number of incrementValue additions) does not exceed that maximum at any point in time.

ze_kernel_timestamp_data_t#

Added in version 1.0

struct ze_kernel_timestamp_data_t#

Kernel timestamp clock data.

  • The timestamp frequency can be queried from the timerResolution member of ze_device_properties_t.

  • The number of valid bits in the timestamp values can be inferred from the kernelTimestampValidBits member of ze_device_properties_t.

Public Members

uint64_t kernelStart#

[out] time sample in tick counts at start of kernel execution

uint64_t kernelEnd#

[out] time sample in tick counts at end of kernel execution

ze_kernel_timestamp_result_t#

Added in version 1.0

struct ze_kernel_timestamp_result_t#

Kernel timestamp result.

Public Members

ze_kernel_timestamp_data_t global#

[out] wall-clock data; free running device clock indicating active device state.

ze_kernel_timestamp_data_t context#

[out] context specific active data; only includes clocks while context was actively executing on the device.