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.

Author: EwanC

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 characterisitcs 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

@@ -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}
@@ -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};
 

api/opencl_runtime_layer.asciidoc

@@ -14326,6 +14326,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.
@@ -14388,6 +14393,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
@@ -14420,6 +14426,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
@@ -14488,6 +14499,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`.
 --
 
@@ -14511,6 +14523,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}.
@@ -14597,6 +14614,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`.
 --
 
@@ -14620,6 +14638,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
@@ -14689,6 +14712,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`.
 --
 
@@ -14711,6 +14735,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
@@ -14787,6 +14816,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`.
 --
 
@@ -14810,6 +14840,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
@@ -14879,6 +14914,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`.
 --
 
@@ -14910,6 +14946,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
@@ -14978,6 +15019,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`.
 --
 
@@ -15008,6 +15050,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
@@ -15075,6 +15122,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`.
 --
 
@@ -15110,7 +15158,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
@@ -15322,8 +15370,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_
@@ -15372,6 +15420,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)
@@ -15446,6 +15499,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`.
 --
 
@@ -15469,6 +15523,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.
@@ -15558,6 +15617,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`.
 --
 

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