cl_khr_command_buffer_mutable_memory_commands extension

Draft of `cl_khr_command_buffer_mutable_memory_commands` based
ontop of KhronosGroup#1045
which updates `clUpdateMutableCommandsKHR` to pass configs
by an array rather than linked list.

The goal of this extension is to be able to update the parameters to memory
operation commands in a command-buffer after the command-buffer has been
finalized using the `clUpdateMutableCommandsKHR` entry-point defined by
`cl_khr_command_buffer_mutable_dispatch`.

api/cl_khr_command_buffer.asciidoc

@@ -129,6 +129,7 @@ functionality expanding on this is provided as layered extensions on top of
 
 * `<<cl_khr_command_buffer_multi_device>>`
 * `<<cl_khr_command_buffer_mutable_dispatch>>`
+* `<<cl_khr_command_buffer_mutable_memory_commands>>`
 
 Having `cl_khr_command_buffer` as a minimal base specification means that the
 API defines mechanisms for functionality that is not enabled by this extension,

api/cl_khr_command_buffer_mutable_dispatch.asciidoc

@@ -44,15 +44,19 @@ in a new command-buffer.
 === Interactions With Other Extensions
 
 The {clUpdateMutableCommandsKHR} entry-point has been designed for the purpose
-of allowing expansion of mutable functionality in future extensions layered on
-top of `cl_khr_command_buffer_mutable_dispatch`.
+of allowing expansion of mutable functionality in extensions layered on top of
+`cl_khr_command_buffer_mutable_dispatch`.
 
 A new extension can define its own structure type to specify the update
 configuration it requires, with a matching
 {cl_command_buffer_update_type_khr_TYPE} value. This new structure type can
 then be passed to {clUpdateMutableCommandsKHR} where it is reinterpreted from a
 void pointer using {cl_command_buffer_update_type_khr_TYPE}.
 
+<<cl_khr_command_buffer_mutable_memory_commands>> is one such extension that
+takes advantage of this mechanism to enable updating arguments to command-buffer
+memory commands.
+
 === New Types
 
   * {cl_mutable_dispatch_fields_khr_TYPE}

api/cl_khr_command_buffer_mutable_memory_commands.asciidoc

@@ -0,0 +1,209 @@
+// Copyright 2018-2024 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_memory_commands.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2024-03-28
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Ewan Crawford, Codeplay Software Ltd.
+  - Kenneth Benzie, Codeplay Software Ltd.
+  - Jack Frankland, Codeplay Software Ltd.
+  - Ben Ashbaugh, Intel.
+  - Balaji Calidas, Qualcomm Technologies Inc.
+  - Sreelakshmi Haridas Maruthur, Qualcomm Technologies Inc.
+  - Kevin Petit, Arm Ltd.
+
+=== Description
+
+The <<cl_khr_command_buffer>> extension separates command construction from
+enqueue by providing a mechanism to record an immutable set of commands which
+can then be repeatedly enqueued. Another extension layered on top,
+<<cl_khr_command_buffer_mutable_dispatch>> allows ND-Range kernel execution
+commands recorded to a command-buffer to be modified between command-buffer
+enqueues by providing a command-buffer update API {clUpdateMutableCommandsKHR}.
+
+`cl_khr_command_buffer_mutable_memory_commands` builds on
+<<cl_khr_command_buffer_mutable_dispatch>> to use the {clUpdateMutableCommandsKHR}
+entry-point for enabling mutability of _memory-commands_ recorded to a
+command-buffer, those commands taking a {cl_mem_TYPE} or SVM pointer argument.
+
+=== New Structures
+
+  * {cl_mutable_copy_buffer_command_config_khr_TYPE}
+  * {cl_mutable_copy_buffer_rect_command_config_khr_TYPE}
+  * {cl_mutable_copy_buffer_to_image_command_config_khr_TYPE}
+  * {cl_mutable_copy_image_command_config_khr_TYPE}
+  * {cl_mutable_copy_image_to_buffer_command_config_khr_TYPE}
+  * {cl_mutable_fill_buffer_command_config_khr_TYPE}
+  * {cl_mutable_fill_image_command_config_khr_TYPE}
+  * {cl_mutable_svm_memcpy_command_config_khr_TYPE}
+  * {cl_mutable_svm_memfill_command_config_khr_TYPE}
+
+=== New Enums
+
+  * {cl_device_command_buffer_capabilities_khr_TYPE}
+  ** {CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR}
+  * {cl_command_buffer_flags_khr_TYPE}
+  ** {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}
+  * {cl_command_buffer_update_type_khr_TYPE}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_RECT_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_TO_IMAGE_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_TO_IMAGE_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_TO_BUFFER_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_FILL_BUFFER_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_FILL_IMAGE_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMCPY_COMMAND_CONFIG_KHR}
+  ** {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMFILL_COMMAND_CONFIG_KHR}
+
+=== Sample Code
+
+==== Sample Application Updating the Arguments to a Copy Buffer Command Between Command-buffer Submissions
+
+[source,cpp]
+----
+  #define CL_CHECK(ERROR)                             \
+    if (ERROR) {                                      \
+      std::cerr << "OpenCL error: " << ERROR << "\n"; \
+      return ERROR;                                   \
+    }
+
+  int main() {
+    cl_platform_id platform;
+    CL_CHECK(clGetPlatformIDs(1, &platform, nullptr));
+    cl_device_id device;
+    CL_CHECK(clGetDeviceIDs(platform, CL_DEVICE_TYPE_ALL, 1, &device, nullptr));
+
+    cl_int error;
+    cl_context context =
+        clCreateContext(nullptr, 1, &device, nullptr, nullptr, &error);
+    CL_CHECK(error);
+
+    cl_command_queue command_queue =
+      clCreateCommandQueue(context, device, 0, &error);
+    CL_CHECK(error);
+
+    size_t num_bytes = 128;
+    cl_mem bufferA =
+        clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
+    CL_CHECK(error);
+
+    // Populate bufferA with data
+
+    cl_mem bufferB =
+        clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
+    CL_CHECK(error);
+
+    // Populate bufferB with data
+
+    cl_mem bufferC =
+        clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
+    CL_CHECK(eror);
+
+    cl_command_buffer_properties_khr properties[3] = {
+       CL_COMMAND_BUFFER_FLAGS_KHR,
+       CL_COMMAND_BUFFER_MUTABLE_KHR | CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR,
+       0
+    };
+
+    cl_command_buffer_khr command_buffer =
+        clCreateCommandBufferKHR(1, &command_queue, properties, &error);
+    CL_CHECK(error)
+
+    cl_mutable_command_khr copy_command_handle;
+    CL_CHECK(clCommandCopyBufferKHR(
+               command_buffer,
+               command_queue,
+               bufferA,
+               bufferC,
+               0,
+               0,
+               num_bytes,
+               0,
+               nullptr,
+               nullptr,
+               &copy_command_handle);
+
+    CL_CHECK(clFinalizeCommandBufferKHR(command_buffer));
+    CL_CHECK(clEnqueueCommandBufferKHR(0, nullptr, command_buffer, 0, nullptr,
+                                       nullptr));
+
+    cl_mutable_copy_buffer_command_config_khr buffer_copy_config = {
+      copy_command_handle,  // command
+      bufferB,              // src_buffer
+      bufferC,              // dst_buffer
+      0,                    // src_offset
+      0,                    // dst_offset
+      num_bytes             // size
+    };
+
+    cl_uint num_configs = 1;
+    cl_update_config_type_khr config_types[1] = {
+       CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_COMMAND_CONFIG_KHR
+    };
+    void* configs[1] = {&buffer_copy_config};
+    CL_CHECK(clUpdateMutableCommandsKHR(command_buffer, num_configs,
+                                        config_types, configs));
+    CL_CHECK(clEnqueueCommandBufferKHR(command_buffer, 0, nullptr, nullptr));
+    CL_CHECK(clFinish(command_queue));
+
+    CL_CHECK(clReleaseCommandBufferKHR(command_buffer));
+    CL_CHECK(clReleaseCommandQueue(command_queue));
+    CL_CHECK(clReleaseContext(context));
+
+    CL_CHECK(clReleaseMemObject(bufferA));
+    CL_CHECK(clReleaseMemObject(bufferB));
+    CL_CHECK(clReleaseMemObject(bufferC));
+
+    return 0;
+  }
+----
+
+=== Conformance tests
+
+TODO - OpenCL-CTS Github issue with CTS plan once API design has been agreed.
+
+=== Modifications to Section 5.X - Command Buffers of OpenCL API specification
+
+==== Memory-Command Modifications
+
+The descriptions of command recording entry-points that operate on {cl_mem_TYPE}
+or SVM pointer arguments are modified as described in this section. These
+changes apply to all of {clCommandCopyBufferKHR}, {clCommandCopyBufferRectKHR},
+{clCommandCopyBufferToImageKHR}, {clCommandCopyImageKHR},
+{clCommandCopyImageToBufferKHR}, {clCommandFillBufferKHR},
+{clCommandFillImageKHR}, {clCommandSVMMemcpyKHR}, and {clCommandSVMMemFillKHR}.
+
+===== Parameter Update
+
+Parameter description of _mutable_handle_ is changed to:
+
+_mutable_handle_ Returns a handle to the command that can be used to modify the
+command between enqueues of _command_buffer_. _mutable_handle_ may be `NULL`. The
+lifetime of this handle is tied to the parent command-buffer, such that freeing
+the command-buffer will also free this handle.
+
+===== Error Updates
+
+The error condition
+
+* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
+
+Is replaced with
+
+* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_
+  was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}.
+
+
+include::provisional_notice.asciidoc[]
+
+=== Version History
+
+  * Revision 0.9.0, 2024-03-28
+  ** First assigned version (provisional).

api/opencl_platform_layer.asciidoc

@@ -1729,6 +1729,15 @@ ifdef::cl_khr_command_buffer_multi_device[]
 include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR.asciidoc[]
 endif::cl_khr_command_buffer_multi_device[]
 
+ifdef::cl_khr_command_buffer_mutable_memory_commands[]
+        {CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR_anchor} Device
+        supports the ability to modify the {cl_mem_TYPE} arguments and SVM
+        pointers to commands operating on memory objects between command-buffer
+        invocations.
+
+include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR.asciidoc[]
+endif::cl_khr_command_buffer_mutabl_memory_commands[]
+
 | {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR_anchor}
 
 include::{generated}/api/version-notes/CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR.asciidoc[]