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[]