Command Queue - Extensions

Command Queue - Extensions#

oneAPI Level Zero Specification - Version 1.20.41

Command Queue - Extension Functions#

zeCommandQueueSetPriorityExt#

Added in version 1.18

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueSetPriorityExt(ze_command_queue_handle_t hCommandQueue, ze_command_queue_priority_t priority)#

Sets the priority of a command queue.

  • The application may call this function from simultaneous threads.

  • This function changes the priority of an existing command queue, overriding the priority specified at creation through ze_command_queue_desc_t; the updated value is reported by zeCommandQueueGetPriority.

  • Whether the new priority affects commands already submitted to the command queue, or only commands submitted after this call, is implementation-defined.

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • priority – [in] priority to set for the command queue

Returns:

zeCommandQueueSetQosExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueSetQosExt(ze_command_queue_handle_t hCommandQueue, const ze_command_queue_qos_ext_desc_t *desc)#

Sets the Quality of Service level of a command queue.

  • The application may call this function from simultaneous threads.

  • This function changes the QoS level of an existing command queue, overriding both the driver default and any level specified at creation through ze_command_queue_qos_ext_desc_t; the updated value is reported by zeCommandQueueGetQosExt.

  • Setting qos of the descriptor to ZE_COMMAND_QUEUE_QOS_EXT_DEFAULT clears any active override and returns the queue to the driver/OS-selected default.

  • Whether the new QoS level affects commands already submitted to the command queue, or only commands submitted after this call, is implementation-defined.

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • desc – [in] pointer to QoS descriptor

Returns:

zeCommandQueueGetQosExt#

Added in version 1.19

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueGetQosExt(ze_command_queue_handle_t hCommandQueue, ze_command_queue_qos_ext_properties_t *pProperties)#

Gets the effective Quality of Service level of a command queue.

  • The application may call this function from simultaneous threads.

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

  • Reports the effective QoS level after resolving any application-specified level against the driver/OS default, and whether that level was application-specified.

Parameters:

  • hCommandQueue – [in] handle of the command queue

  • pProperties – [in,out] query result for QoS properties of the command queue

Returns:

zeCommandQueueSignalExternalSemaphoreExt#

Added in version 1.20

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueSignalExternalSemaphoreExt(ze_command_queue_handle_t hCommandQueue, 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 on a command queue.

  • Signals an external semaphore.

  • The signal is ordered against the command lists submitted to the same command queue, and is honoured when the command queue reaches this point in its submission order.

  • Unlike zeCommandListAppendSignalExternalSemaphoreExt, the value is taken at submission rather than when the operation is appended, so a command list recorded once may be replayed with zeCommandQueueExecuteCommandLists against a different value each time.

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

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

Parameters:

  • hCommandQueue – [in] The command queue handle.

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

  • phSemaphores – [in][range(0, numSemaphores)] The array of pointers to external semaphore handles to be signaled by the command queue.

  • 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 signaling; must be 0 if nullptr == phWaitEvents

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

Returns:

zeCommandQueueWaitExternalSemaphoreExt#

Added in version 1.20

ZE_APIEXPORT ze_result_t ZE_APICALL zeCommandQueueWaitExternalSemaphoreExt(ze_command_queue_handle_t hCommandQueue, 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 on a command queue.

  • Waits on external semaphores.

  • The wait is ordered against the command lists submitted to the same command queue, and blocks execution of subsequent submissions until the semaphores reach the requested values.

  • Unlike zeCommandListAppendWaitExternalSemaphoreExt, the value is taken at submission rather than when the operation is appended, so a command list recorded once may be replayed with zeCommandQueueExecuteCommandLists against a different value each time.

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

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

Parameters:

  • hCommandQueue – [in] The command queue handle.

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

  • phSemaphores – [in][range(0, numSemaphores)] The array of pointers to external semaphore handles to be waited on by the command queue.

  • 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 waiting; must be 0 if nullptr == phWaitEvents

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

Returns:

Command Queue - Extension Enums#

ze_command_queue_qos_ext_t#

Added in version 1.19

enum ze_command_queue_qos_ext_t#

Supported command queue Quality of Service (QoS) levels. Expresses desired power/energy characteristics for work submitted through a command queue; orthogonal to ze_command_queue_priority_t, which expresses scheduling urgency instead. A queue may combine an explicit priority with an explicit QoS level. Applications must not perform relational comparisons (e.g. less-than, greater-than) between QoS levels; only equality checks are guaranteed to be meaningful. The numeric values are not guaranteed to be ordered by energy efficiency, and future levels may be added without preserving any such order.

Values:

enumerator ZE_COMMAND_QUEUE_QOS_EXT_DEFAULT#

[default] implicit default behavior; uses the driver/OS-selected QoS level

enumerator ZE_COMMAND_QUEUE_QOS_EXT_HIGH#

foreground / latency-sensitive workloads

enumerator ZE_COMMAND_QUEUE_QOS_EXT_MEDIUM#

nominal scheduling class

enumerator ZE_COMMAND_QUEUE_QOS_EXT_LOW#

reduced energy usage with forward progress guaranteed

enumerator ZE_COMMAND_QUEUE_QOS_EXT_UTILITY#

more energy efficient than LOW while still guaranteeing forward progress

enumerator ZE_COMMAND_QUEUE_QOS_EXT_ECO#

maximum energy savings; no forward progress guarantee

enumerator ZE_COMMAND_QUEUE_QOS_EXT_FORCE_UINT32#

Value marking end of ZE_COMMAND_QUEUE_QOS_EXT_* ENUMs.

Command Queue - Extension Structures#

ze_command_queue_qos_ext_desc_t#

Added in version 1.19

struct ze_command_queue_qos_ext_desc_t#

Command Queue QoS 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_command_queue_qos_ext_t qos#

[in] requested QoS level for this command queue

ze_command_queue_qos_ext_properties_t#

Added in version 1.19

struct ze_command_queue_qos_ext_properties_t#

Command Queue QoS properties queried from a command queue.

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_command_queue_qos_ext_t qos#

[out] effective QoS level of the command queue; never ZE_COMMAND_QUEUE_QOS_EXT_DEFAULT

ze_bool_t isOverridden#

[out] true if qos was specified by the application, either at creation time through ze_command_queue_qos_ext_desc_t or by a call to zeCommandQueueSetQosExt; false if qos is the driver/OS-selected default