Command-buffer query for supported queue properties

This change introduces a new device query related to the command-buffer extension - `CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`. This is different from `CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR`, as we want to convey to the user that an implementation supports using a queue property with a command-buffer, but is not *required* to use the property. This supersedes reporting queue related values from the `CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` query. The flaw with `CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` is that it contains bits explicitly added by the command-buffer extension for reporting support for queue properties. This is a brittle design, as any new queue property added in future would need to have a new bit added here in the command-buffer extension to report support when used with command-buffers. Instead a better design is to have a new query reporting queue properties supported, `CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`, and keeping `CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` for capabilities unrelated to the command-queue properties. The `CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR` use-case can now be covered by returning `CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE` from `CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`, so it is removed.
KhronosGroup · Oct 2, 2024 · 6fa65be · 6fa65be
1 parent 4f04321
commit 6fa65be
Show file tree

Hide file tree

Showing 4 changed files with 25 additions and 18 deletions.
diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc
@@ -4,15 +4,15 @@
 include::{generated}/meta/{refprefix}cl_khr_command_buffer.txt[]
 
 // *Revision*::
-//    0.9.5
+//    0.9.6
 // *Extension and Version Dependencies*::
 //     This extension requires OpenCL 1.2 or later.
 //     Buffering of SVM commands requires OpenCL 2.0 or later.
 
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2024-07-24
+    2024-10-02
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -224,11 +224,11 @@ features:
   * {cl_device_info_TYPE}
   ** {CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR}
   ** {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR}
+  ** {CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR}
   * {cl_device_command_buffer_capabilities_khr_TYPE}
   ** {CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR}
   ** {CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR}
   ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR}
-  ** {CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR}
   * {cl_command_buffer_properties_khr_TYPE}
   ** {CL_COMMAND_BUFFER_FLAGS_KHR}
   * {cl_command_buffer_flags_khr_TYPE}
@@ -438,4 +438,5 @@ features:
   * 0.9.5, 2024-07-24
   ** Add a properties parameter to all command recording entry-points
      (provisional).
-
+  * 0.9.6, 2024-10-02
+  ** Add device query for supported queue properties (provisional).
diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc
@@ -1718,12 +1718,6 @@ include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_
 
 include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR.asciidoc[]
 
-        {CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR_anchor} Device
-        supports the ability to record command-buffers to out-of-order
-        command-queues.
-
-include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR.asciidoc[]
-
 ifdef::cl_khr_command_buffer_multi_device[]
         {CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR_anchor} Device
         supports the ability to record commands to more than one
@@ -1742,6 +1736,18 @@ include::{generated}/api/version-notes/CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_P
         It is valid for a command-queue to be created with extra properties
         in addition to this base requirement and still be compatible with
         command-buffer execution.
+
+| {CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR.asciidoc[]
+
+  | {cl_command_queue_properties_TYPE}
+      | Bitmask of the supported properties with which a command-queue may be
+        created to allow a command-buffer to be executed on it. It is invalid
+        for a command-queue to be created with a property not reported and
+        still be compatible with command-buffer execution.
+
+        The mandated minimum capability is: {CL_QUEUE_PROFILING_ENABLE}.
 endif::cl_khr_command_buffer[]
 
 ifdef::cl_khr_command_buffer_multi_device[]

diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
@@ -14178,10 +14178,9 @@ returned in _errcode_ret_:
 
   * {CL_INVALID_COMMAND_QUEUE} if any command-queue in _queues_ is not a
     valid command-queue.
-  * {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} if any command-queue in _queues_ is
-    an out-of-order command-queue and the device associated with the
-    command-queue does not support the
-    {CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR} capability.
+  * {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} if the properties of any command-queue
+    in _queues_ contains a property not specified by
+    {CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR}.
   * {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} if the properties of any
     command-queue in _queues_ does not contain the minimum properties
     specified by {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR}.

diff --git a/xml/cl.xml b/xml/cl.xml
@@ -1330,7 +1330,7 @@ server's OpenCL/api-docs repository.
         <enum bitpos="0"            name="CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR"/>
         <enum bitpos="1"            name="CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR"/>
         <enum bitpos="2"            name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
-        <enum bitpos="3"            name="CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR"/>
+            <unused start="3" end="3" comment="Available for future use"/>
         <enum bitpos="4"            name="CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR"/>
             <unused start="5" end="6" comment="Used by future command-buffer extensions"/>
             <unused start="6" end="31"/>
@@ -1780,7 +1780,8 @@ server's OpenCL/api-docs repository.
         <enum value="0x1297"             name="CL_COMMAND_BUFFER_STATE_KHR"/>
         <enum value="0x1298"             name="CL_COMMAND_BUFFER_PROPERTIES_ARRAY_KHR"/>
         <enum value="0x1299"             name="CL_COMMAND_BUFFER_CONTEXT_KHR"/>
-            <unused start="0x129A" end="0x129F" comment="Available to use"/>
+        <enum value="0x129A"             name="CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR"/>
+            <unused start="0x129B" end="0x129F" comment="Available to use"/>
         <enum value="0x12A0"             name="CL_MUTABLE_COMMAND_COMMAND_QUEUE_KHR"/>
         <enum value="0x12A1"             name="CL_MUTABLE_COMMAND_COMMAND_BUFFER_KHR"/>
         <enum value="0x12A2"             name="CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR"/>
@@ -7186,7 +7187,7 @@ server's OpenCL/api-docs repository.
                 <command name="clSetContentSizeBufferPoCL"/>
             </require>
         </extension>
-        <extension name="cl_khr_command_buffer" revision="0.9.5" supported="opencl" depends="CL_VERSION_1_2" ratified="opencl" provisional="true">
+        <extension name="cl_khr_command_buffer" revision="0.9.6" supported="opencl" depends="CL_VERSION_1_2" ratified="opencl" provisional="true">
             <require>
                 <type name="CL/cl.h"/>
             </require>
@@ -7203,13 +7204,13 @@ server's OpenCL/api-docs repository.
             </require>
             <require comment="cl_device_info">
                 <enum name="CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR"/>
+                <enum name="CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR"/>
                 <enum name="CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR"/>
             </require>
             <require comment="cl_device_command_buffer_capabilities_khr - bitfield">
                 <enum name="CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR"/>
                 <enum name="CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR"/>
                 <enum name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
-                <enum name="CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR"/>
             </require>
             <require comment="cl_command_buffer_properties_khr">
                <enum name="CL_COMMAND_BUFFER_FLAGS_KHR"/>