Command-buffer query for supported queue properties (#850)

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.

Author: Ewan Crawford

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*::
@@ -237,11 +237,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}
@@ -464,4 +464,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).

api/opencl_platform_layer.asciidoc

@@ -1742,12 +1742,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
@@ -1766,6 +1760,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[]

api/opencl_runtime_layer.asciidoc

@@ -14378,10 +14378,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}.

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"/>
@@ -7190,7 +7191,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>
@@ -7207,13 +7208,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"/>