Command Queue - Extensions#

oneAPI Level Zero Specification - Version 1.19.12

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:

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.