Move simultaneous-use optional feature to mutable-dispatch

Author: Ewan Crawford

api/cl_khr_command_buffer.asciidoc

@@ -122,14 +122,6 @@ There are no gurantees made around the values of sync-points returned from
 adding commands to a command-buffer. Any semantics that a could be inferred
 from the sync-point values returned is implementation defined.
 
-==== Simultaneous Use
-
-The optional <<simultaneous-use, simultaneous use>> capability was added to the
-extension so that vendors could support concurrent execution of the same
-command-buffer. However, simultaneous use may result in command-buffers having
-a larger overhead to implement, so the capability is optional to enable
-optimizations when this usage isn't required by a user.
-
 === Interactions With Other Extensions
 
 The introduction of the command-buffer abstraction enables functionality
@@ -240,11 +232,8 @@ features:
   * {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_properties_khr_TYPE}
   ** {CL_COMMAND_BUFFER_FLAGS_KHR}
-  * {cl_command_buffer_flags_khr_TYPE}
-  ** {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR}
   * {cl_command_buffer_info_khr_TYPE}
   ** {CL_COMMAND_BUFFER_QUEUES_KHR}
   ** {CL_COMMAND_BUFFER_NUM_QUEUES_KHR}

api/cl_khr_command_buffer_mutable_dispatch.asciidoc

@@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_dispatch.txt[
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2024-09-05
+    2025-08-08
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -41,6 +41,15 @@ This allows inputs and outputs to the kernel, as well as work-item sizes and
 offsets, to change without having to re-record the entire command sequence
 in a new command-buffer.
 
+==== Simultaneous Use
+
+The optional <<simultaneous-use, simultaneous use>> capability was added to the
+extension so that vendors could support concurrent execution of the same
+command-buffer object which has been updated between submissions. However,
+simultaneous use may result in command-buffers having a larger overhead to
+implement, so the capability is optional to enable optimizations when this
+usage isn't required by a user.
+
 === Interactions With Other Extensions
 
 The {clUpdateMutableCommandsKHR} entry-point has been designed for the purpose
@@ -72,6 +81,8 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}.
 
   * {cl_device_info_TYPE}
   ** {CL_DEVICE_MUTABLE_DISPATCH_CAPABILITIES_KHR}
+  * {cl_device_command_buffer_capabilities_khr_TYPE}
+  ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR}
   * {cl_command_properties_khr_TYPE}
   ** {CL_MUTABLE_DISPATCH_ASSERTS_KHR}
   ** {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR}
@@ -95,6 +106,7 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}.
   ** {CL_MUTABLE_COMMAND_COMMAND_TYPE_KHR}
   * {cl_command_buffer_flags_khr_TYPE}
   ** {CL_COMMAND_BUFFER_MUTABLE_KHR}
+  ** {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR}
   * {cl_command_buffer_properties_khr_TYPE}
   ** {CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR}
   * {cl_command_buffer_update_type_khr_TYPE}
@@ -363,3 +375,7 @@ may be a introduced as a stand alone extension.
   * Revision 0.9.3, 2024-09-05
   ** Rename `CL_MUTABLE_DISPATCH_PROPERTIES_ARRAY_KHR` to
      `CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR` (experimental).
+  * Revision 0.9.4, 2025-08-08
+    **  Move `CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR` and
+        `CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR` in this
+        extension from the base extension (experimental).

api/opencl_platform_layer.asciidoc

@@ -1790,11 +1790,13 @@ include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINT
 
 include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR.asciidoc[]
 
+ifdef::cl_khr_command_buffer_mutable_dispatch[]
         {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR_anchor} Device
         supports enqueueing command-buffers with a <<simultaneous-use,
         simultaneous use>> usage pattern.
 
 include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR.asciidoc[]
+endif::cl_khr_command_buffer_mutable_dispatch[]
 
 ifdef::cl_khr_command_buffer_multi_device[]
         {CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR_anchor} Device

api/opencl_runtime_layer.asciidoc

@@ -14692,10 +14692,17 @@ usage>>.
 ====
 
 Simultaneous use is defined using the _prerequisite_ terminology from the
-<<_execution_model, execution model>>, and is an optional feature for devices
-to support concurrent executions of a command-buffer. A command-buffer must
-be created with {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} to avoid undefined
-behavior if a simultaneous use usage pattern occurs.
+<<_execution_model, execution model>>.
+ifndef::cl_khr_command_buffer_multi_device[]
+A command-buffer exhibits undefined behavior if a simultaneous use usage
+pattern occurs.
+endif::cl_khr_command_buffer_multi_device[]
+ifdef::cl_khr_command_buffer_multi_device[]
+Simultaneous use is an optional feature for devices to support concurrent
+executions of a command-buffer which have been updated between submissions.
+A command-buffer must be created with {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR}
+to avoid undefined behavior if a simultaneous use usage pattern occurs.
+endif::cl_khr_command_buffer_multi_device[]
 
 [[simultaneous-use]]
 Simultaneous Use:: When a command-buffer is submitted for
@@ -14708,9 +14715,7 @@ An example of simultaneous use would be two submissions of the same
 command-buffer to a single out-of-order queue, without any events or barriers
 used to express a dependency between the two enqueue calls. Using a single
 in-order queue, events, or barriers to express dependencies between submissions
-of the same command-buffer would each be ways to avoid simultaneous use and are
-valid usage of command-buffers created without the
-{CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} flag.
+of the same command-buffer would each be ways to avoid simultaneous use.
 ====
 
 ifdef::cl_khr_command_buffer_multi_device[]
@@ -14820,13 +14825,15 @@ include::{generated}/api/version-notes/CL_COMMAND_BUFFER_FLAGS_KHR.asciidoc[]
   | {cl_command_buffer_flags_khr_TYPE}
       | This is a bitfield and can be set to a combination of the following values:
 
+ifdef::cl_khr_command_buffer_mutable_dispatch[]
         {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR_anchor} - Allow multiple
         instances of the command-buffer to be scheduled for execution on the
         device in a usage pattern that exhibits <<simultaneous-use,
         simultaneous use>>. If set, devices must support
         {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR}.
 
 include::{generated}/api/version-notes/CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR.asciidoc[]
+endif::cl_khr_command_buffer_mutable_dispatch[]
 
 ifdef::cl_khr_command_buffer_multi_device[]
       {CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR_anchor} - All commands in the
@@ -15120,10 +15127,17 @@ execution was successfully queued, or one of the errors below:
     required by the OpenCL implementation on the host.
 --
 
+ifndef::cl_khr_command_buffer_mutable_dispatch[]
+Calling {clEnqueueCommandBufferKHR} in a usage pattern that exhbits
+<<simultaneous-use, simultaneous use>> results in undefined behavior.
+endif::cl_khr_command_buffer_mutable_dispatch[]
+
+ifdef::cl_khr_command_buffer_mutable_dispatch[]
 Calling {clEnqueueCommandBufferKHR} in a usage pattern that exhbits
 <<simultaneous-use, simultaneous use>> when _command_buffer_ was not created
 with the {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} flag results in undefined
 behavior.
+endif::cl_khr_command_buffer_mutable_dispatch[]
 
 === Recording Commands to a Command-Buffer
 

xml/cl.xml

@@ -7346,14 +7346,10 @@ server's OpenCL/api-docs repository.
             <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"/>
             </require>
             <require comment="cl_command_buffer_properties_khr">
                <enum name="CL_COMMAND_BUFFER_FLAGS_KHR"/>
             </require>
-            <require comment="cl_command_buffer_flags_khr - bitfield">
-               <enum name="CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR"/>
-            </require>
             <require comment="Error codes">
                 <enum name="CL_INVALID_COMMAND_BUFFER_KHR"/>
                 <enum name="CL_INVALID_SYNC_POINT_WAIT_LIST_KHR"/>
@@ -7469,7 +7465,7 @@ server's OpenCL/api-docs repository.
                 <enum name="CL_QUEUE_JOB_SLOT_ARM"/>
             </require>
         </extension>
-        <extension name="cl_khr_command_buffer_mutable_dispatch" revision="0.9.3" supported="opencl" depends="cl_khr_command_buffer" ratified="opencl" experimental="true" comment="requires cl_khr_command_buffer 0.9.5 or later">
+        <extension name="cl_khr_command_buffer_mutable_dispatch" revision="0.9.4" supported="opencl" depends="cl_khr_command_buffer" ratified="opencl" experimental="true" comment="requires cl_khr_command_buffer 0.9.8 or later">
             <require>
                 <type name="CL/cl.h"/>
             </require>
@@ -7483,8 +7479,14 @@ server's OpenCL/api-docs repository.
                 <type name="cl_mutable_dispatch_asserts_khr"/>
             </require>
             <require comment="cl_command_buffer_flags_khr - bitfield">
+               <enum name="CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR"/>
                <enum name="CL_COMMAND_BUFFER_MUTABLE_KHR"/>
             </require>
+
+            <require comment="cl_device_command_buffer_capabilities_khr - bitfield">
+                <enum name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
+            </require>
+
             <require comment="Error codes">
                 <enum name="CL_INVALID_MUTABLE_COMMAND_KHR"/>
             </require>