Command Queue

Command Queue#

oneAPI Level Zero Specification - Version 1.18.31

Command Queue Functions#

zeCommandQueueCreate#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueCreate(ze_context_handle_t hContext, ze_device_handle_t hDevice, const ze_command_queue_desc_t *desc, ze_command_queue_handle_t *phCommandQueue)#

Creates a command queue on the context.

  • A command queue represents a logical input stream to the device, tied to a physical input stream.

  • The application must only use the command queue 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.

Remark

Analogues

  • clCreateCommandQueue

Parameters:

  • hContext – [in] handle of the context object

  • hDevice – [in] handle of the device object

  • desc – [in] pointer to command queue descriptor

  • phCommandQueue – [out] pointer to handle of command queue object created

Returns:

zeCommandQueueDestroy#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueDestroy(ze_command_queue_handle_t hCommandQueue)#

Destroys a command queue.

  • The application must destroy all fence handles created from the command queue before destroying the command queue itself

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

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

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

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

Remark

Analogues

  • clReleaseCommandQueue

Parameters:

hCommandQueue – [in][release] handle of command queue object to destroy

Returns:

zeCommandQueueExecuteCommandLists#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueExecuteCommandLists(ze_command_queue_handle_t hCommandQueue, uint32_t numCommandLists, ze_command_list_handle_t *phCommandLists, ze_fence_handle_t hFence)#

Executes a command list in a command queue.

  • The command lists are submitted to the device in the order they are received, whether from multiple calls (on the same or different threads) or a single call with multiple command lists.

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

  • The application must ensure the device is not currently referencing the command list since the implementation is allowed to modify the contents of the command list for submission.

  • The application must only execute command lists created with an identical command queue group ordinal to the command queue.

  • The application must use a fence created using the same command queue.

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

  • The application must ensure the command lists being executed are not immediate command lists.

  • The application may call this function from simultaneous threads.

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

Remark

Analogues

  • vkQueueSubmit

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • numCommandLists – [in] number of command lists to execute

  • phCommandLists – [in][range(0, numCommandLists)] list of handles of the command lists to execute

  • hFence – [in][optional] handle of the fence to signal on completion

Returns:

zeCommandQueueSynchronize#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueSynchronize(ze_command_queue_handle_t hCommandQueue, uint64_t timeout)#

Synchronizes a command queue by waiting on the host.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • 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 immediately returns the status of the command queue; 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:

zeCommandQueueGetOrdinal#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetOrdinal(ze_command_queue_handle_t hCommandQueue, uint32_t *pOrdinal)#

Gets the command queue group ordinal.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • pOrdinal – [out] command queue group ordinal

Returns:

zeCommandQueueGetIndex#

Added in version 1.9

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetIndex(ze_command_queue_handle_t hCommandQueue, uint32_t *pIndex)#

Gets the command queue index within the group.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • pIndex – [out] command queue index within the group

Returns:

zeCommandQueueGetFlags#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetFlags(ze_command_queue_handle_t hCmdQueue, ze_command_queue_flags_t *pFlags)#

Gets command queue creation flags.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCmdQueue – [in] handle of the command queue

  • pFlags – [out] pointer to flags used during command queue creation

Returns:

zeCommandQueueGetMode#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetMode(ze_command_queue_handle_t hCmdQueue, ze_command_queue_mode_t *pMode)#

Gets command queue operation mode.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCmdQueue – [in] handle of the command queue

  • pMode – [out] pointer to mode used during command queue creation

Returns:

zeCommandQueueGetPriority#

Added in version 1.17

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetPriority(ze_command_queue_handle_t hCmdQueue, ze_command_queue_priority_t *pPriority)#

Gets command queue priority.

  • The application may call this function from simultaneous threads.

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

Parameters:

  • hCmdQueue – [in] handle of the command queue

  • pPriority – [out] pointer to priority used during command queue creation

Returns:

Command Queue Enums#

ze_command_queue_flags_t#

Added in version 1.0

enum ze_command_queue_flag_t#

Values:

enumerator ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY#

command queue should be optimized for submission to a single device engine. driver must disable any implicit optimizations for distributing work across multiple engines. this flag should be used when applications want full control over multi-engine submission and scheduling. This flag is DEPRECATED as flag ZE_COMMAND_LIST_FLAG_EXPLICIT_ONLY is DEPRECATED.

enumerator ZE_COMMAND_QUEUE_FLAG_IN_ORDER#

To be used only when creating immediate command lists. Commands appended to the immediate command list are executed in-order, with driver implementation enforcing dependencies between them. Application is not required to have the signal event of a given command being the wait event of the next to define an in-order list, and application is allowed to pass signal and wait events to each appended command to implement more complex dependency graphs. (since v1.7)

enumerator ZE_COMMAND_QUEUE_FLAG_COPY_OFFLOAD_HINT#

To be used only when creating immediate command lists and only for compute queues. Try to offload copy operations to different engines. This is only a hint. Driver may ignore it per append call, based on platform capabilities or internal heuristics. (since v1.14)

enumerator ZE_COMMAND_QUEUE_FLAG_FORCE_UINT32#

Value marking end of ZE_COMMAND_QUEUE_FLAG_* ENUMs.

ze_command_queue_mode_t#

Added in version 1.0

enum ze_command_queue_mode_t#

Supported command queue modes.

Values:

enumerator ZE_COMMAND_QUEUE_MODE_DEFAULT#

implicit default behavior; uses driver-based heuristics

enumerator ZE_COMMAND_QUEUE_MODE_SYNCHRONOUS#

Device execution always completes immediately on execute; Host thread is blocked using wait on implicit synchronization object

enumerator ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS#

Device execution is scheduled and will complete in future; explicit synchronization object must be used to determine completeness

enumerator ZE_COMMAND_QUEUE_MODE_FORCE_UINT32#

Value marking end of ZE_COMMAND_QUEUE_MODE_* ENUMs.

ze_command_queue_priority_t#

Added in version 1.0

enum ze_command_queue_priority_t#

Supported command queue priorities.

Values:

enumerator ZE_COMMAND_QUEUE_PRIORITY_NORMAL#

[default] normal priority

enumerator ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_LOW#

lower priority than normal

enumerator ZE_COMMAND_QUEUE_PRIORITY_PRIORITY_HIGH#

higher priority than normal

enumerator ZE_COMMAND_QUEUE_PRIORITY_FORCE_UINT32#

Value marking end of ZE_COMMAND_QUEUE_PRIORITY_* ENUMs.

Command Queue Structures#

ze_command_queue_desc_t#

Added in version 1.0

struct ze_command_queue_desc_t#

Command Queue 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 ordinal#

[in] command queue group ordinal

uint32_t index#

[in] command queue index within the group; must be zero.

ze_command_queue_flags_t flags#

[in] usage flags. must be 0 (default) or a valid combination of ze_command_queue_flag_t; default behavior may use implicit driver-based heuristics to balance latency and throughput.

ze_command_queue_mode_t mode#

[in] operation mode

ze_command_queue_priority_t priority#

[in] priority