Command List

Contents

Command List#

oneAPI Level Zero Specification - Version 1.18.31

Command List Functions#

zeCommandListCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_list_desc_t *desc, ze_command_list_handle_t *phCommandList)#

Creates a command list on the context.

  • A command list represents a sequence of commands for execution on a command queue.

  • The command list is created in the ‘open’ state.

  • The application must only use the command list for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • desc – [in] pointer to command list descriptor

  • phCommandList – [out] pointer to handle of command list object created

Returns:

zeCommandListCreateImmediate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListCreateImmediate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_queue_desc_t *altdesc, ze_command_list_handle_t *phCommandList)#

Creates an immediate command list on the context.

  • An immediate command list is used for low-latency submission of commands.

  • An immediate command list creates an implicit command queue.

  • Immediate command lists must not be passed to zeCommandQueueExecuteCommandLists.

  • Commands appended into an immediate command list may execute synchronously, by blocking until the command is complete.

  • The command list is created in the ‘open’ state and never needs to be closed.

  • The application must only use the command list for the device, or its sub-devices, which was provided during creation.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • altdesc – [in] pointer to command queue descriptor

  • phCommandList – [out] pointer to handle of command list object created

Returns:

zeCommandListDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListDestroy(ze_command_list_handle_t hCommandList)#

Destroys a command list.

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

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

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

  • The implementation of this function must be thread-safe.

Parameters:

hCommandList – [in][release] handle of command list object to destroy

Returns:

zeCommandListClose#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListClose(ze_command_list_handle_t hCommandList)#

Closes a command list; ready to be executed by a command queue.

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

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

Parameters:

hCommandList – [in] handle of command list object to close

Returns:

zeCommandListReset#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListReset(ze_command_list_handle_t hCommandList)#

Reset a command list to initial (empty) state; ready for appending commands.

  • The application must ensure the device is not currently referencing the command list before it is reset

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

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

Parameters:

hCommandList – [in] handle of command list object to reset

Returns:

zeCommandListAppendWriteGlobalTimestamp#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendWriteGlobalTimestamp(ze_command_list_handle_t hCommandList, uint64_t *dstptr, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends a memory write of the device’s global timestamp value into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

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

  • The number of valid bits in the timestamp value can be queried from the timestampValidBits member of ze_device_properties_t.

  • The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • dstptr – [in,out] pointer to memory where timestamp value will be written; must be 8byte-aligned.

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before executing query; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query

Returns:

zeCommandListAppendBarrier#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendBarrier(ze_command_list_handle_t hCommandList, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends an execution and global memory barrier into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • If numWaitEvents is zero, then all previous commands, enqueued on same command queue, must complete prior to the execution of the barrier. This is not the case when numWaitEvents is non-zero.

  • If numWaitEvents is non-zero, then only all phWaitEvents must be signaled prior to the execution of the barrier.

  • This command blocks all following commands from beginning until the execution of the barrier completes.

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

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

Remark

Analogues

  • vkCmdPipelineBarrier

  • clEnqueueBarrierWithWaitList

Parameters:

  • hCommandList – [in] handle of the command list

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before executing barrier; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier

Returns:

zeCommandListAppendMemoryRangesBarrier#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryRangesBarrier(ze_command_list_handle_t hCommandList, uint32_t numRanges, const size_t *pRangeSizes, const void **pRanges, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends a global memory ranges barrier into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • If numWaitEvents is zero, then all previous commands are completed prior to the execution of the barrier.

  • If numWaitEvents is non-zero, then then all phWaitEvents must be signaled prior to the execution of the barrier.

  • This command blocks all following commands from beginning until the execution of the barrier completes.

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • numRanges – [in] number of memory ranges

  • pRangeSizes – [in][range(0, numRanges)] array of sizes of memory range

  • pRanges – [in][range(0, numRanges)] array of memory ranges

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before executing barrier; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing barrier

Returns:

zeCommandListAppendMemoryCopy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopy(ze_command_list_handle_t hCommandList, void *dstptr, const void *srcptr, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies host, device, or shared memory.

  • The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Remark

Analogues

  • clEnqueueCopyBuffer

  • clEnqueueReadBuffer

  • clEnqueueWriteBuffer

  • clEnqueueSVMMemcpy

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination memory to copy to

  • srcptr – [in] pointer to source memory to copy from

  • size – [in] size in bytes to copy

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendMemoryFill#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryFill(ze_command_list_handle_t hCommandList, void *ptr, const void *pattern, size_t pattern_size, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Initializes host, device, or shared memory.

  • The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by ptr as it is free to be modified by either the Host or device up until execution.

  • The ptr must be aligned to pattern_size

  • The value to initialize memory to is described by the pattern and the pattern size.

  • The pattern size must be a power-of-two and less than or equal to the maxMemoryFillPatternSize member of ze_command_queue_group_properties_t.

  • The size must be a multiple of pattern size.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Remark

Analogues

  • clEnqueueFillBuffer

  • clEnqueueSVMMemFill

Parameters:

  • hCommandList – [in] handle of command list

  • ptr – [in] pointer to memory to initialize

  • pattern – [in] pointer to value to initialize memory to

  • pattern_size – [in] size in bytes of the value to initialize memory to

  • size – [in] size in bytes to initialize

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendMemoryCopyRegion#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopyRegion(ze_command_list_handle_t hCommandList, void *dstptr, const ze_copy_region_t *dstRegion, uint32_t dstPitch, uint32_t dstSlicePitch, const void *srcptr, const ze_copy_region_t *srcRegion, uint32_t srcPitch, uint32_t srcSlicePitch, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies a region from a 2D or 3D array of host, device, or shared memory.

  • The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

  • The region width, height, and depth for both src and dst must be same. The origins can be different.

  • The src and dst regions cannot be overlapping.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination memory to copy to

  • dstRegion – [in] pointer to destination region to copy to

  • dstPitch – [in] destination pitch in bytes

  • dstSlicePitch – [in] destination slice pitch in bytes. This is required for 3D region copies where the depth member of ze_copy_region_t is not 0, otherwise it’s ignored.

  • srcptr – [in] pointer to source memory to copy from

  • srcRegion – [in] pointer to source region to copy from

  • srcPitch – [in] source pitch in bytes

  • srcSlicePitch – [in] source slice pitch in bytes. This is required for 3D region copies where the depth member of ze_copy_region_t is not 0, otherwise it’s ignored.

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendMemoryCopyFromContext#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryCopyFromContext(ze_command_list_handle_t hCommandList, void *dstptr, ze_context_handle_t hContextSrc, const void *srcptr, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies host, device, or shared memory from another context.

  • The current active and source context must be from the same driver.

  • The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination memory to copy to

  • hContextSrc – [in] handle of source context object

  • srcptr – [in] pointer to source memory to copy from

  • size – [in] size in bytes to copy

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendImageCopy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopy(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, ze_image_handle_t hSrcImage, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies an image.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The application must ensure the image format descriptors for both source and destination images are the same.

  • The application must ensure the command list, images and events were created on the same context.

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

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

Remark

Analogues

  • clEnqueueCopyImage

Parameters:

  • hCommandList – [in] handle of command list

  • hDstImage – [in] handle of destination image to copy to

  • hSrcImage – [in] handle of source image to copy from

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendImageCopyRegion#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyRegion(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, ze_image_handle_t hSrcImage, const ze_image_region_t *pDstRegion, const ze_image_region_t *pSrcRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies a region of an image to another image.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The region width and height for both src and dst must be same. The origins can be different.

  • The src and dst regions cannot be overlapping.

  • The application must ensure the image format descriptors for both source and destination images are the same.

  • The application must ensure the command list, images and events were created, and the memory was allocated, on the same context.

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

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

Parameters:

  • hCommandList – [in] handle of command list

  • hDstImage – [in] handle of destination image to copy to

  • hSrcImage – [in] handle of source image to copy from

  • pDstRegion – [in][optional] destination region descriptor

  • pSrcRegion – [in][optional] source region descriptor

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendImageCopyToMemory#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyToMemory(ze_command_list_handle_t hCommandList, void *dstptr, ze_image_handle_t hSrcImage, const ze_image_region_t *pSrcRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies from an image to device or shared memory.

  • The application must ensure the memory pointed to by dstptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr as it is free to be modified by either the Host or device up until execution.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The application must ensure the image format descriptor for the source image is a single-planar format.

  • The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

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

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

Remark

Analogues

  • clEnqueueReadImage

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination memory to copy to

  • hSrcImage – [in] handle of source image to copy from

  • pSrcRegion – [in][optional] source region descriptor

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendImageCopyFromMemory#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyFromMemory(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, const void *srcptr, const ze_image_region_t *pDstRegion, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies to an image from device or shared memory.

  • The application must ensure the memory pointed to by srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by srcptr as it is free to be modified by either the Host or device up until execution.

  • The application must ensure the image and events are accessible by the device on which the command list was created.

  • The application must ensure the image format descriptor for the destination image is a single-planar format.

  • The application must ensure the command list, image and events were created, and the memory was allocated, on the same context.

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

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

Remark

Analogues

  • clEnqueueWriteImage

Parameters:

  • hCommandList – [in] handle of command list

  • hDstImage – [in] handle of destination image to copy to

  • srcptr – [in] pointer to source memory to copy from

  • pDstRegion – [in][optional] destination region descriptor

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendMemoryPrefetch#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemoryPrefetch(ze_command_list_handle_t hCommandList, const void *ptr, size_t size)#

Asynchronously prefetches shared memory to the device associated with the specified command list.

  • This is a hint to improve performance only and is not required for correctness.

  • Only prefetching to the device associated with the specified command list is supported. Prefetching to the host or to a peer device is not supported.

  • Prefetching may not be supported for all allocation types for all devices. If memory prefetching is not supported for the specified memory range the prefetch hint may be ignored.

  • Prefetching may only be supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.

  • The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.

  • The application must ensure the command list was created, and the memory was allocated, on the same context.

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

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

Remark

Analogues

  • clEnqueueSVMMigrateMem

Parameters:

  • hCommandList – [in] handle of command list

  • ptr – [in] pointer to start of the memory range to prefetch

  • size – [in] size in bytes of the memory range to prefetch

Returns:

zeCommandListAppendMemAdvise#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendMemAdvise(ze_command_list_handle_t hCommandList, ze_device_handle_t hDevice, const void *ptr, size_t size, ze_memory_advice_t advice)#

Provides advice about the use of a shared memory range.

  • Memory advice is a performance hint only and is not required for functional correctness.

  • Memory advice can be used to override driver heuristics to explicitly control shared memory behavior.

  • Not all memory advice hints may be supported for all allocation types for all devices. If a memory advice hint is not supported by the device it will be ignored.

  • Memory advice may only be supported at a device-specific granularity, such as at a page boundary. In this case, the memory range may be expanded such that the start and end of the range satisfy granularity requirements.

  • The application must ensure the memory pointed to by ptr is accessible by the device on which the command list was created.

  • The application must ensure the command list was created, and memory was allocated, on the same context.

  • The application must not call this function from simultaneous threads with the same command list handle, and the memory was allocated.

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

Parameters:

  • hCommandList – [in] handle of command list

  • hDevice – [in] device associated with the memory advice

  • ptr – [in] Pointer to the start of the memory range

  • size – [in] Size in bytes of the memory range

  • advice – [in] Memory advice for the memory range

Returns:

zeCommandListAppendSignalEvent#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendSignalEvent(ze_command_list_handle_t hCommandList, ze_event_handle_t hEvent)#

Appends a signal of the event from the device into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created. This requirement does not apply to counter-based events.

  • For counter-based events, the event may be signaled on any device, regardless of the device used to create the event. When a counter-based event is passed for signaling, it drops its previous tracking point and re-associates with the device on which the command list was created, tracking the new signaling point. No peer-to-peer access between the previously associated device and the new signaling device is required.

  • 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 must ensure the command list and events were created on the same context.

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

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

  • Passing additional parameters is possible with zeCommandListAppendSignalEventWithParameters function.

Remark

Analogues

  • clSetUserEventStatus

  • vkCmdSetEvent

Parameters:

  • hCommandList – [in] handle of the command list

  • hEvent – [in] handle of the event

Returns:

zeCommandListAppendWaitOnEvents#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendWaitOnEvents(ze_command_list_handle_t hCommandList, uint32_t numEvents, ze_event_handle_t *phEvents)#

Appends wait on event(s) on the device into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • For counter-based events, the device on which the command list was created must have peer-to-peer access to the device that last signaled the event. Unlike signaling, waiting on a counter-based event does not re-associate it with another device.

  • The application must ensure the command list and events were created on the same context.

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

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

  • Passing additional parameters is possible with zeCommandListAppendWaitOnEventsWithParameters function.

Parameters:

  • hCommandList – [in] handle of the command list

  • numEvents – [in] number of events to wait on before continuing

  • phEvents – [in][range(0, numEvents)] handles of the events to wait on before continuing

Returns:

zeCommandListAppendEventReset#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendEventReset(ze_command_list_handle_t hCommandList, ze_event_handle_t hEvent)#

Appends a reset of an event back to not signaled state into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created on the same context.

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

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

Remark

Analogues

  • vkResetEvent

Parameters:

  • hCommandList – [in] handle of the command list

  • hEvent – [in] handle of the event

Returns:

zeCommandListAppendQueryKernelTimestamps#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendQueryKernelTimestamps(ze_command_list_handle_t hCommandList, uint32_t numEvents, ze_event_handle_t *phEvents, void *dstptr, const size_t *pOffsets, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends a query of an events’ timestamp value(s) into a command list.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the events were created from an event pool that was created using ZE_EVENT_POOL_FLAG_KERNEL_TIMESTAMP or ZE_EVENT_POOL_FLAG_KERNEL_MAPPED_TIMESTAMP flag.

  • The application must ensure the memory pointed to by both dstptr and pOffsets is accessible by the device on which the command list was created.

  • The value(s) written to the destination buffer are undefined if any timestamp event has not been signaled.

  • If pOffsets is nullptr, then multiple results will be appended sequentially into memory in the same order as phEvents.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

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

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

Parameters:

  • hCommandList – [in] handle of the command list

  • numEvents – [in] the number of timestamp events to query

  • phEvents – [in][range(0, numEvents)] handles of timestamp events to query

  • dstptr – [in,out] pointer to memory where ze_kernel_timestamp_result_t will be written; must be size-aligned.

  • pOffsets – [in][optional][range(0, numEvents)] offset, in bytes, to write results; address must be 4byte-aligned and offsets must be size-aligned.

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before executing query; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before executing query

Returns:

zeCommandListAppendLaunchKernel#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchKernel(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchFuncArgs, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Launch kernel over one or more work groups.

  • The application must ensure the kernel and events are accessible by the device on which the command list was created.

  • This may only be called for a command list created with command queue group ordinal that supports compute.

  • The application must ensure the command list, kernel and events were created on the same context.

  • This function may not be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

  • pLaunchFuncArgs – [in] thread group launch arguments

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendLaunchCooperativeKernel#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchCooperativeKernel(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchFuncArgs, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Launch kernel cooperatively over one or more work groups.

  • The application must ensure the kernel and events are accessible by the device on which the command list was created.

  • This may only be called for a command list created with command queue group ordinal that supports compute.

  • This may only be used for a command list that are submitted to command queue with cooperative flag set.

  • The application must ensure the command list, kernel and events were created on the same context.

  • This function may not be called from simultaneous threads with the same command list handle.

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

  • Use zeKernelSuggestMaxCooperativeGroupCount to recommend max group count for device for cooperative functions that device supports.

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

  • pLaunchFuncArgs – [in] thread group launch arguments

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeCommandListAppendLaunchKernelIndirect#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendLaunchKernelIndirect(ze_command_list_handle_t hCommandList, ze_kernel_handle_t hKernel, const ze_group_count_t *pLaunchArgumentsBuffer, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Launch kernel over one or more work groups using indirect arguments.

  • The application must ensure the kernel and events are accessible by the device on which the command list was created.

  • The application must ensure the launch arguments are visible to the device on which the command list was created.

  • The implementation must not access the contents of the launch arguments as they are free to be modified by either the Host or device up until execution.

  • This may only be called for a command list created with command queue group ordinal that supports compute.

  • The application must ensure the command list, kernel and events were created, and the memory was allocated, on the same context.

  • This function may not be called from simultaneous threads with the same command list handle.

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

Parameters:

  • hCommandList – [in] handle of the command list

  • hKernel – [in] handle of the kernel object

  • pLaunchArgumentsBuffer – [in] pointer to device buffer that will contain thread group launch arguments

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns: