Add properties parameter to all command-buffer commands (KhronosGroup…

…#1215)

* Add properties parameter to all command-buffer commands

See Issue KhronosGroup#1207
disucssion how it could make the `cl_khr_command_buffer` extension
more extensible if we allowed all the command-recording parameters
to have a `properties` parameter that could be used.

* fix misspelling

* Update clGetMutableCommandInfoKHR table

* Rename query to `CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR`

---------

Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

api/cl_khr_command_buffer.asciidoc

@@ -4,15 +4,15 @@
 include::{generated}/meta/{refprefix}cl_khr_command_buffer.txt[]
 
 // *Revision*::
-//    0.9.4
+//    0.9.5
 // *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*::
-    2023-03-31
+    2024-07-24
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -137,13 +137,15 @@ retain its provisional extension status until other layered extensions are
 released, as these may reveal modifications needed to the base specification to
 support their intended use cases.
 
-==== ND-range Kernel Command Properties
+==== Command Properties
 
-The {clCommandNDRangeKernelKHR} entry-point defines a `properties` parameter of
-new type {cl_ndrange_kernel_command_properties_khr_TYPE}. No properties are defined
-in {cl_khr_command_buffer_EXT}, but the parameter enables layered extensions like
-{cl_khr_command_buffer_mutable_dispatch_EXT} to define properties that inform
-the characteristics of the kernel command.
+The command recording entry-points allow a `properties` parameter of
+new type {cl_command_properties_khr_TYPE} to be passed. No properties are
+defined in {cl_khr_command_buffer_EXT}, but the parameter enables layered
+extensions to define characteristics of the individual commands.
+
+For example, {cl_khr_command_buffer_mutable_dispatch_EXT} defines properties
+that can be set when appending a kernel command with {clCommandNDRangeKernelKHR}.
 
 ==== Command Handles
 
@@ -214,7 +216,7 @@ features:
   * {cl_command_buffer_state_khr_TYPE}
   * {cl_command_buffer_properties_khr_TYPE}
   * {cl_command_buffer_flags_khr_TYPE}
-  * {cl_ndrange_kernel_command_properties_khr_TYPE}
+  * {cl_command_properties_khr_TYPE}
   * {cl_mutable_command_khr_TYPE}
 
 === New Enums
@@ -433,4 +435,7 @@ features:
   * 0.9.4, 2023-05-11
   ** Add clCommandSVMMemcpyKHR and clCommandSVMMemFillKHR command entries
      (provisional).
+  * 0.9.5, 2024-07-24
+  ** Add a properties parameter to all command recording entry-points
+     (provisional).
 

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-06-19
+    2024-09-05
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -72,7 +72,7 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}.
 
   * {cl_device_info_TYPE}
   ** {CL_DEVICE_MUTABLE_DISPATCH_CAPABILITIES_KHR}
-  * {cl_ndrange_kernel_command_properties_khr_TYPE}
+  * {cl_command_properties_khr_TYPE}
   ** {CL_MUTABLE_DISPATCH_ASSERTS_KHR}
   ** {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR}
   * {cl_mutable_dispatch_asserts_khr_TYPE}
@@ -86,7 +86,7 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}.
   * {cl_mutable_command_info_khr_TYPE}
   ** {CL_MUTABLE_COMMAND_COMMAND_QUEUE_KHR}
   ** {CL_MUTABLE_COMMAND_COMMAND_BUFFER_KHR}
-  ** {CL_MUTABLE_DISPATCH_PROPERTIES_ARRAY_KHR}
+  ** {CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR}
   ** {CL_MUTABLE_DISPATCH_KERNEL_KHR}
   ** {CL_MUTABLE_DISPATCH_DIMENSIONS_KHR}
   ** {CL_MUTABLE_DISPATCH_GLOBAL_WORK_OFFSET_KHR}
@@ -196,7 +196,7 @@ kernel void vector_addition(global int* tile1, global int* tile2,
   CL_CHECK(clSetKernelArg(kernel, 2, sizeof(cl_mem), &output_buffers[0]));
 
   // Instruct the nd-range command to allow for mutable kernel arguments
-  cl_ndrange_kernel_command_properties_khr mutable_properties[] = {
+  cl_command_properties_khr mutable_properties[] = {
       CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR,
       CL_MUTABLE_DISPATCH_ARGUMENTS_KHR, 0};
 
@@ -360,3 +360,6 @@ may be a introduced as a stand alone extension.
   * Revision 0.9.2, 2024-06-19
   ** Change {clUpdateMutableCommandsKHR} API to pass configs as an array rather
      than linked list (provisional).
+  * Revision 0.9.3, 2024-09-05
+  ** Rename `CL_MUTABLE_DISPATCH_PROPERTIES_ARRAY_KHR` to
+     `CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR` (provisional).

api/opencl_runtime_layer.asciidoc

@@ -14396,6 +14396,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
     synchronization-points that need to complete before this particular
     command can be executed.
@@ -14458,6 +14463,7 @@ ifdef::cl_khr_command_buffer_multi_device[]
     associated with _command_queue_ and _command_buffer_ is not the same.
 endif::cl_khr_command_buffer_multi_device[]
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
   * {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR} if _sync_point_wait_list_ is
     `NULL` and _num_sync_points_in_wait_list_ is > 0, or
@@ -14490,6 +14496,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _src_buffer_, _dst_buffer_, _src_offset_, _dst_offset_, _size_ refer
     to {clEnqueueCopyBuffer}.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
@@ -14558,6 +14569,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -14581,6 +14593,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _src_origin_, _dst_origin_, _region_, _src_row_pitch_,
     _src_slice_pitch_, _dst_row_pitch_, _dst_slice_pitch_ refer to
     {clEnqueueCopyBufferRect}.
@@ -14667,6 +14684,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -14690,6 +14708,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _src_buffer_, _dst_image_, _src_offset_, _dst_origin_, _region_ refer to
     {clEnqueueCopyBufferToImage}
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
@@ -14759,6 +14782,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -14781,6 +14805,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _src_image_, _dst_image_, _src_origin_, _dst_origin_, _region_ refer to
     {clEnqueueCopyImage}.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
@@ -14857,6 +14886,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -14880,6 +14910,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _src_image_, _dst_buffer_, _src_origin_, _region_, _dst_offset_ refer to
     {clEnqueueCopyImageToBuffer}.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
@@ -14949,6 +14984,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -14980,6 +15016,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _buffer_, _pattern_, _pattern_size_, _offset_, _size_ refer to
     {clEnqueueFillBuffer}.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
@@ -15048,6 +15089,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -15078,6 +15120,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _image_, _fill_color_, _origin_, _region_ refer to {clEnqueueFillImage}.
   * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify
     synchronization-points that need to complete before this particular
@@ -15145,6 +15192,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -15180,7 +15228,7 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[]
     The {cl_khr_command_buffer_EXT} extension does not define any
     properties, but supported properties defined by extensions are defined
     in the <<ndrange-kernel-properties-table, List of supported properties
-    by {clCommandNDRangeKernelKHR}>> table.
+    by clCommandNDRangeKernelKHR>> table.
 endif::cl_khr_command_buffer_mutable_dispatch[]
   * _kernel_ is a valid kernel object which **must** have its arguments set.
     Any changes to _kernel_ after calling {clCommandNDRangeKernelKHR}, such
@@ -15392,8 +15440,8 @@ New errors:
 
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
-  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if the {cl_khr_command_buffer_mutable_dispatch_EXT}
     extension is not supported and _mutable_handle_ is not `NULL`.
   * {CL_INVALID_OPERATION} if the device associated with _command_queue_
@@ -15442,6 +15490,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and thier
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _dst_ptr_ is the pointer to a host (if the device supports system SVM)
     or SVM memory allocation where data is copied to.
   * _src_ptr_ is the pointer to a host (if the device supports system SVM)
@@ -15516,6 +15569,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -15539,6 +15593,11 @@ ifdef::cl_khr_command_buffer_multi_device[]
     _command_queue_ is `NULL`, then only one command-queue must have been set on
     _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`.
 endif::cl_khr_command_buffer_multi_device[]
+  * _properties_ specifies a list of properties for the command and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with 0. The
+    {cl_khr_command_buffer_EXT} extension does not define any properties, but
+    supported properties may be defined by layered extensions in future.
   * _svm_ptr_ is a pointer to a (if the device supports system SVM)
     or SVM memory region that will be filled with _pattern_.
     It must be aligned to _pattern_size_ bytes.
@@ -15628,6 +15687,7 @@ New errors:
   * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid
     command-buffer.
   * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized.
+  * {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
   * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
 --
 
@@ -16165,23 +16225,20 @@ include::{generated}/api/version-notes/CL_MUTABLE_COMMAND_COMMAND_TYPE_KHR.ascii
 
       The list of supported event command types defined by {clGetEventInfo}
       is used with the matching command.
-| {CL_MUTABLE_DISPATCH_PROPERTIES_ARRAY_KHR_anchor}
+| {CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR_anchor}
 
-include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_PROPERTIES_ARRAY_KHR.asciidoc[]
-  | {cl_ndrange_kernel_command_properties_khr_TYPE}[]
-    | Return the properties argument specified on _command_ recording with
-      {clCommandNDRangeKernelKHR}.
+include::{generated}/api/version-notes/CL_MUTABLE_COMMAND_PROPERTIES_ARRAY_KHR.asciidoc[]
+  | {cl_command_properties_khr_TYPE}[]
+    | Return the properties argument specified on _command_ recording.
 
       If the properties argument specified on creation of _command_ was not
       `NULL`, the implementation must return the values specified in the
       properties argument in the same order and without including additional
       properties.
 
       If the properties argument specified on creation of _command_ was
-      `NULL`, or _command_ was not recorded from a
-      {clCommandNDRangeKernelKHR} command, the implementation must return
-      _param_value_size_ret_ equal to 0, indicating that there are no
-      properties to be returned.
+      `NULL`, the implementation must return _param_value_size_ret_ equal to 0,
+      indicating that there are no properties to be returned.
 | {CL_MUTABLE_DISPATCH_KERNEL_KHR_anchor}
 
 include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_KERNEL_KHR.asciidoc[]

config/rouge/lib/rouge/lexers/opencl.rb

@@ -158,7 +158,7 @@ class OpenCL < Cpp
         cl_command_buffer_state_khr
         cl_command_buffer_properties_khr
         cl_command_buffer_flags_khr
-        cl_ndrange_kernel_command_properties_khr
+        cl_command_properties_khr
         cl_mutable_command_khr
         cl_mutable_dispatch_fields_khr
         cl_mutable_command_info_khr