Command List - Extensions

Command List - Extensions#

oneAPI Level Zero Specification - Version 1.18.31

Command List - Extension Functions#

zeCommandListAppendImageCopyToMemoryExt#

Added in version 1.3

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyToMemoryExt(ze_command_list_handle_t hCommandList, void *dstptr, ze_image_handle_t hSrcImage, const ze_image_region_t *pSrcRegion, uint32_t destRowPitch, uint32_t destSlicePitch, 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 that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.

  • If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width

  • The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.

  • If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.

  • 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

  • destRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being written

  • destSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being written

  • 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:

zeCommandListAppendImageCopyFromMemoryExt#

Added in version 1.3

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendImageCopyFromMemoryExt(ze_command_list_handle_t hCommandList, ze_image_handle_t hDstImage, const void *srcptr, const ze_image_region_t *pDstRegion, uint32_t srcRowPitch, uint32_t srcSlicePitch, 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 that the rowPitch is set to 0 if image is a 1D image. Otherwise the rowPitch must be greater than or equal to the element size in bytes x width.

  • If rowPitch is set to 0, the appropriate row pitch is calculated based on the size of each element in bytes multiplied by width

  • The application must ensure that the slicePitch is set to 0 if image is a 1D or 2D image. Otherwise this value must be greater than or equal to rowPitch x height.

  • If slicePitch is set to 0, the appropriate slice pitch is calculated based on the rowPitch x height.

  • 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

  • srcRowPitch – [in] size in bytes of the 1D slice of the 2D region of a 2D or 3D image or each image of a 1D or 2D image array being read

  • srcSlicePitch – [in] size in bytes of the 2D slice of the 3D region of a 3D image or each image of a 1D or 2D image array being read

  • 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:

zeCommandListAppendSignalExternalSemaphoreExt#

Added in version 1.12

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendSignalExternalSemaphoreExt(ze_command_list_handle_t hCommandList, uint32_t numSemaphores, ze_external_semaphore_ext_handle_t *phSemaphores, ze_external_semaphore_signal_params_ext_t *signalParams, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Signal an external semaphore.

  • Signals an external semaphore.

  • This function must only be used with an immediate command list.

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

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

Parameters:

  • hCommandList – [in] The command list handle.

  • numSemaphores – [in] The number of external semaphores.

  • phSemaphores – [in][range(0, numSemaphores)] The array of pointers to external semaphore handles to be appended into command list.

  • signalParams – [in][range(0, numSemaphores)] The array of pointers to external semaphore signal parameters.

  • 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:

zeCommandListAppendWaitExternalSemaphoreExt#

Added in version 1.12

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendWaitExternalSemaphoreExt(ze_command_list_handle_t hCommandList, uint32_t numSemaphores, ze_external_semaphore_ext_handle_t *phSemaphores, ze_external_semaphore_wait_params_ext_t *waitParams, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Wait on external semaphores.

  • Waits on external semaphores.

  • This function must only be used with an immediate command list.

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

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

Parameters:

  • hCommandList – [in] The command list handle.

  • numSemaphores – [in] The number of external semaphores.

  • phSemaphores – [in][range(0,numSemaphores)] The array of pointers to external semaphore handles to append into command list.

  • waitParams – [in][range(0,numSemaphores)] The array of pointers to external semaphore wait parameters.

  • 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:

zeCommandListBeginGraphCaptureExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListBeginGraphCaptureExt(ze_command_list_handle_t hCommandList, const void *pNext)#

Begins recording asynchronous append operations into a new graph associated with an immediate command list.

  • Graph capture is intended for asynchronous append operations only; synchronous operations are not supported while capture is active and return ZE_RESULT_ERROR_GRAPH_CAPTURE_UNSUPPORTED.

  • The application must call this function only with an immediate command list.

  • The application must not call this function with a synchronous immediate command list.

  • After this call succeeds, append operations issued to the command list are recorded into a graph and are not submitted to the device. Events used by these operations are not signaled until capture ends and the graph is instantiated and executed.

  • If the device does not support ZE_RECORD_REPLAY_GRAPH_EXT_FLAG_APPEND_COMMANDLIST, then while capture is active, calling zeCommandListImmediateAppendCommandListsExp on the capturing command list returns an error (ZE_RESULT_ERROR_GRAPH_CAPTURE_UNSUPPORTED).

  • If the device does not support ZE_RECORD_REPLAY_GRAPH_EXT_FLAG_SUBGRAPHS, then while capture is active, calling zeCommandListAppendGraphExt on the capturing command list returns an error (ZE_RESULT_ERROR_GRAPH_CAPTURE_UNSUPPORTED).

  • While capture is active, host-side synchronization operations on recorded work, such as zeCommandListHostSynchronize or zeEventHostSynchronize, return ZE_RESULT_ERROR_GRAPH_CAPTURE_UNSUPPORTED.

  • While capture is active, internal counter-based events (i.e. without ZEX_COUNTER_BASED_EVENT_FLAG_GRAPH_EXTERNAL) captured in the graph cannot be used outside the graph; such use returns an error (ZE_RESULT_ERROR_GRAPH_INTERNAL_EVENT).

  • The command list on which capture starts is called the primary command list for a given capture session.

  • If an event signaled by a captured command list is used in the wait list of another immediate command list, that command list also enters graph capture mode. This creates a fork. The command list from which the fork originated is called the parent, and the forked command list is called the child. A child command list may itself be used to create additional forks, resulting in a tree of command lists participating in the same graph capture.

  • Subsequent signals from the parent command list to a child command list are allowed and do not create additional forks or capture sessions; the child command list remains in the same capture session as the parent command list.

  • Each fork must be joined by signaling on the child command list and by waiting on the parent command list.

  • A child command list may signal multiple times back to the parent command list, but only the last signal on the child command list may become part of the join operation.

  • Child command lists continue recording as long as the primary command list is in capture mode.

  • Commands that append work (for example, compute kernels or data transfers) to a recording child command list after the intended join operation are treated as unjoined work, and the graph is considered invalid. Commands that do not append work (for example, event signal and wait operations) are allowed after the join operation and do not invalidate the graph.

  • All restrictions described for zeCommandListBeginGraphCaptureExt apply to recording child command lists as well.

  • It is invalid to merge two separate graph capture sessions (i.e. with different primary command lists) by waiting on an event associated with a different graph (operation will return ZE_RESULT_ERROR_GRAPH_CAPTURE_MERGE_ATTEMPT).

  • If the device does not support ZE_RECORD_REPLAY_GRAPH_EXT_FLAG_CB_EXTERNAL_IPC, then using an event that was created with both ZEX_COUNTER_BASED_EVENT_FLAG_IPC and ZEX_COUNTER_BASED_EVENT_FLAG_GRAPH_EXTERNAL returns an error (ZE_RESULT_ERROR_GRAPH_CAPTURE_UNSUPPORTED) during append operations.

Parameters:

  • hCommandList – [in] handle of the command list to start capture on

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

Returns:

zeCommandListBeginCaptureIntoGraphExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListBeginCaptureIntoGraphExt(ze_command_list_handle_t hCommandList, ze_graph_handle_t hGraph, const void *pNext)#

Begins recording asynchronous append operations into an existing graph.

  • The graph must be created with zeGraphCreateExt before calling this function.

  • The graph must be empty when capture begins.

  • After this call succeeds, the command list enters graph capture mode and all restrictions described for zeCommandListBeginGraphCaptureExt apply.

Parameters:

  • hCommandList – [in] handle of the command list to start capture on

  • hGraph – [in] handle of the graph to capture into

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

Returns:

zeCommandListIsGraphCaptureEnabledExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListIsGraphCaptureEnabledExt(ze_command_list_handle_t hCommandList)#

Queries whether a command list is in graph capture mode.

  • The function returns ZE_RESULT_QUERY_TRUE when the command list is in graph capture mode.

  • The function returns ZE_RESULT_QUERY_FALSE when the command list is not in graph capture mode.

Parameters:

hCommandList – [in] handle of the command list

Returns:

zeCommandListEndGraphCaptureExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListEndGraphCaptureExt(ze_command_list_handle_t hCommandList, const void *pNext, ze_graph_handle_t *phGraph)#

Ends graph capture on the primary command list and returns the recorded graph.

  • This function may only be called on the primary command list used with zeCommandListBeginGraphCaptureExt or zeCommandListBeginCaptureIntoGraphExt.

  • If capture was started with zeCommandListBeginCaptureIntoGraphExt, the returned graph handle is the same graph handle that was provided when capture began.

  • The returned graph must be instantiated before execution.

  • This call ends graph capture mode on all command lists participating in the same graph capture (including forks).

  • After this call succeeds, subsequent append operations submit work to the device normally.

  • If capture mode is not active on the command list, an error is returned.

  • After this call succeeds, events signaled by previously captured commands do not create new forks.

  • After this call succeeds, internal counter-based events (i.e. without ZEX_COUNTER_BASED_EVENT_FLAG_GRAPH_EXTERNAL) can be reused by the application and don’t interfere with recorded state.

Parameters:

  • hCommandList – [in] handle of the command list to end capture on

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

  • phGraph – [out] pointer to the captured graph handle

Returns:

zeCommandListGetGraphExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListGetGraphExt(ze_command_list_handle_t hCommandList, ze_graph_handle_t *phGraph)#

Returns the graph associated with a command list that is in graph capture mode.

  • This function may only be called while the command list is in graph capture mode.

  • The returned graph handle cannot be instantiated until capture is ended by zeCommandListEndGraphCaptureExt.

  • This function does not transfer ownership of the graph handle.

  • If the command list is not in graph capture mode, an error is returned and *phGraph is set to null.

Parameters:

  • hCommandList – [in] handle of the command list that is in capture mode

  • phGraph – [out] pointer to the graph handle associated with the command list

Returns:

zeCommandListAppendGraphExt#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandListAppendGraphExt(ze_command_list_handle_t hCommandList, ze_executable_graph_handle_t hGraph, const void *pNext, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Appends execution of an executable graph to a command list.

  • The destination command list must match the type and execution characteristics of the command list used to initiate recording, including the queue group ordinal and immediate mode configuration.

  • Only one execution of the same executable graph object may run at a time; concurrent graph execution requires multiple executable graph instances.

  • If this function is called while the executable graph is already running, the new execution is scheduled after the current execution completes.

  • Graph execution obeys the implicit in-order dependency semantics of the destination command list.

  • If hSignalEvent is provided, it is signaled after all recorded append operations on all recorded queues complete.

  • If wait events are provided, graph execution does not begin until all wait events are satisfied.

Parameters:

  • hCommandList – [in] handle of the command list to execute the graph on

  • hGraph – [in] handle of the executable graph

  • pNext – [in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext)

  • 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: