Use array for clUpdateMutableCommandsKHR

Implementation change to prototype specification changes proposed
in KhronosGroup/OpenCL-Docs#1041

Uses OpenCL changes from
* KhronosGroup/OpenCL-Docs#1045
* KhronosGroup/OpenCL-Headers#245
* KhronosGroup/OpenCL-CTS#1984

doc/source/cl/extension.rst

@@ -317,20 +317,20 @@ before the extension can be turned on by default in the oneAPI Construction Kit:
 * Event profiling is not implemented (see CA-3322).
 
 .. _cl_khr_command_buffer:
-  https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_command_buffer
+  https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#cl_khr_command_buffer
 
 Command Buffers: Mutable Dispatch - ``cl_khr_command_buffer_mutable_dispatch``
 ------------------------------------------------------------------------------
 
-oneAPI Construction Kit implements version 0.9.0 of the provisional
+oneAPI Construction Kit implements version 0.9.2 of the provisional
 `cl_khr_command_buffer_mutable_dispatch`_ extension.
 
 `cl_khr_command_buffer_mutable_dispatch`_  builds upon `cl_khr_command_buffer`_
 to allow users to modify kernel execution commands between enqueues of a
 command-buffer.
 
 .. _cl_khr_command_buffer_mutable_dispatch:
-  https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_command_buffer_mutable_dispatch
+  https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#cl_khr_command_buffer_mutable_dispatch
 
 Extended Async Copies - ``cl_khr_extended_async_copies``
 ---------------------------------------------------------

external/CMakeLists.txt

@@ -25,8 +25,8 @@ set(CMAKE_CXX_EXTENSIONS ON)
 # them available here rather here rather than in source/cl/external.
 FetchContent_Declare(
   OpenCLHeaders
-  GIT_REPOSITORY https://github.com/KhronosGroup/OpenCL-Headers.git
-  GIT_TAG        v2024.05.08
+  GIT_REPOSITORY git@github.com:EwanC/OpenCL-Headers.git
+  GIT_TAG        array_update
 )
 FetchContent_MakeAvailable(OpenCLHeaders)
 

source/cl/examples/MutableDispatchKHR/source/main.cpp

@@ -209,16 +209,11 @@ int main(const int argc, const char **argv) {
     // If not executing the first frame
     if (i != 0) {
       // Configure the mutable configuration to update the kernel arguments
-      const cl_mutable_dispatch_arg_khr arg_0{0, sizeof(cl_mem),
-                                              &input_A_buffer};
-      const cl_mutable_dispatch_arg_khr arg_1{1, sizeof(cl_mem),
-                                              &input_B_buffer};
-      const cl_mutable_dispatch_arg_khr arg_2{2, sizeof(cl_mem),
-                                              &output_buffer};
-      const cl_mutable_dispatch_arg_khr args[] = {arg_0, arg_1, arg_2};
-      const cl_mutable_dispatch_config_khr dispatch_config{
-          CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR,
-          nullptr,
+      cl_mutable_dispatch_arg_khr arg_0{0, sizeof(cl_mem), &input_A_buffer};
+      cl_mutable_dispatch_arg_khr arg_1{1, sizeof(cl_mem), &input_B_buffer};
+      cl_mutable_dispatch_arg_khr arg_2{2, sizeof(cl_mem), &output_buffer};
+      cl_mutable_dispatch_arg_khr args[] = {arg_0, arg_1, arg_2};
+      cl_mutable_dispatch_config_khr dispatch_config{
           command_handle,
           3 /* num_args */,
           0 /* num_svm_arg */,
@@ -230,12 +225,14 @@ int main(const int argc, const char **argv) {
           nullptr /* global_work_offset */,
           nullptr /* global_work_size */,
           nullptr /* local_work_size */};
-      const cl_mutable_base_config_khr mutable_config{
-          CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR, nullptr, 1,
-          &dispatch_config};
 
       // Update the command buffer with the mutable configuration
-      error = clUpdateMutableCommandsKHR(command_buffer, &mutable_config);
+      cl_uint num_configs = 1;
+      cl_command_buffer_update_type_khr config_types[1] = {
+          CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR};
+      const void *configs[1] = {&dispatch_config};
+      error = clUpdateMutableCommandsKHR(command_buffer, num_configs,
+                                         config_types, configs);
       CL_CHECK(error);
     }
 

source/cl/source/extension/include/extension/khr_command_buffer.h

@@ -463,7 +463,9 @@ struct _cl_command_buffer_khr final : public cl::base<_cl_command_buffer_khr> {
   /// @param[in] mutable_config New configuration for one or more commands
   ///
   /// @return CL_SUCCESS or appropriate OpenCL error code.
-  cl_int updateCommandBuffer(const cl_mutable_base_config_khr &mutable_config);
+  cl_int updateCommandBuffer(
+      cargo::array_view<const cl_mutable_dispatch_config_khr *>
+          &mutable_configs);
 
   /// @brief Verifies whether a queue is compatible with the command-buffer.
   ///

source/cl/source/extension/source/khr_command_buffer.cpp

@@ -1072,19 +1072,15 @@ cargo::expected<mux_descriptor_info_s, cl_int> createArgumentDescriptor(
 }  // anonymous namespace
 
 [[nodiscard]] cl_int _cl_command_buffer_khr::updateCommandBuffer(
-    const cl_mutable_base_config_khr &mutable_config) {
-  const std::lock_guard<std::mutex> guard(mutex);
+    cargo::array_view<const cl_mutable_dispatch_config_khr *>
+        &mutable_dispatch_configs) {
+  std::lock_guard<std::mutex> guard(mutex);
   const cl_device_id device = command_queue->device;
 
-  const cargo::array_view<const cl_mutable_dispatch_config_khr>
-      mutable_dispatch_configs(mutable_config.mutable_dispatch_list,
-                               mutable_config.num_mutable_dispatch);
-
   // Verify struct configures kernel arguments and return error if malformed
-  for (const auto &config : mutable_dispatch_configs) {
-    OCL_CHECK(config.type != CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR,
-              return CL_INVALID_VALUE);
-
+  for (const auto config_ptr : mutable_dispatch_configs) {
+    OCL_CHECK(config_ptr == nullptr, return CL_INVALID_VALUE);
+    cl_mutable_dispatch_config_khr config = *config_ptr;
     OCL_CHECK(!config.command, return CL_INVALID_MUTABLE_COMMAND_KHR);
     OCL_CHECK(config.command->command_buffer != this,
               return CL_INVALID_MUTABLE_COMMAND_KHR);
@@ -1100,7 +1096,7 @@ cargo::expected<mux_descriptor_info_s, cl_int> createArgumentDescriptor(
 
   for (auto config : mutable_dispatch_configs) {
     unsigned update_index = 0;
-    const unsigned num_args = config.num_args + config.num_svm_args;
+    const unsigned num_args = config->num_args + config->num_svm_args;
     UpdateInfo update_info;
     if (update_info.descriptors.alloc(num_args)) {
       return CL_OUT_OF_HOST_MEMORY;
@@ -1110,16 +1106,16 @@ cargo::expected<mux_descriptor_info_s, cl_int> createArgumentDescriptor(
       return CL_OUT_OF_HOST_MEMORY;
     }
 
-    if (update_info.pointers.alloc(config.num_svm_args)) {
+    if (update_info.pointers.alloc(config->num_svm_args)) {
       return CL_OUT_OF_HOST_MEMORY;
     }
 
-    const auto mutable_command = config.command;
+    const auto mutable_command = config->command;
     update_info.id = mutable_command->id;
-    cargo::array_view<const cl_mutable_dispatch_arg_khr> args(config.arg_list,
-                                                              config.num_args);
+    cargo::array_view<const cl_mutable_dispatch_arg_khr> args(config->arg_list,
+                                                              config->num_args);
 
-    for (unsigned i = 0; i < config.num_args; ++i) {
+    for (unsigned i = 0; i < config->num_args; ++i) {
       auto arg = args[i];
       update_info.indices[update_index] = arg.arg_index;
       auto descriptor =
@@ -1135,9 +1131,9 @@ cargo::expected<mux_descriptor_info_s, cl_int> createArgumentDescriptor(
 
 #ifdef OCL_EXTENSION_cl_intel_unified_shared_memory
     cargo::array_view<const cl_mutable_dispatch_arg_khr> svm_args(
-        config.arg_svm_list, config.num_svm_args);
+        config->arg_svm_list, config->num_svm_args);
 
-    for (unsigned i = 0; i < config.num_svm_args; ++i) {
+    for (unsigned i = 0; i < config->num_svm_args; ++i) {
       // Unpack the argument.
       const auto arg = svm_args[i];
       const auto arg_index = arg.arg_index;

source/cl/source/extension/source/khr_command_buffer_mutable_dispatch.cpp

@@ -82,10 +82,11 @@ cl_int extension::khr_command_buffer_mutable_dispatch::GetDeviceInfo(
 }
 
 #ifdef OCL_EXTENSION_cl_khr_command_buffer_mutable_dispatch
-CL_API_ENTRY cl_int CL_API_CALL
-clUpdateMutableCommandsKHR(cl_command_buffer_khr command_buffer,
-                           const cl_mutable_base_config_khr *mutable_config) {
-  const tracer::TraceGuard<tracer::OpenCL> guard("clUpdateMutableCommandsKHR");
+CL_API_ENTRY cl_int CL_API_CALL clUpdateMutableCommandsKHR(
+    cl_command_buffer_khr command_buffer, cl_uint num_configs,
+    const cl_command_buffer_update_type_khr *config_types,
+    const void **configs) {
+  tracer::TraceGuard<tracer::OpenCL> guard("clUpdateMutableCommandsKHR");
   OCL_CHECK(!command_buffer, return CL_INVALID_COMMAND_BUFFER_KHR);
   OCL_CHECK(!command_buffer->is_finalized, return CL_INVALID_OPERATION);
 
@@ -102,20 +103,24 @@ clUpdateMutableCommandsKHR(cl_command_buffer_khr command_buffer,
     return CL_INVALID_OPERATION;
   }
 
-  OCL_CHECK(!mutable_config, return CL_INVALID_VALUE);
-  OCL_CHECK(mutable_config->type != CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR,
-            return CL_INVALID_VALUE);
+  OCL_CHECK(config_types && 0 == num_configs, return CL_INVALID_VALUE);
+  OCL_CHECK(!config_types && num_configs, return CL_INVALID_VALUE);
 
-  // Values for next would be defined by implementation of mutable mem commands
-  // layered extension. Later checks assume next is NULL and so the
-  // mutable_dispatch_list field must be set.
-  OCL_CHECK(mutable_config->next, return CL_INVALID_VALUE);
+  OCL_CHECK(configs && 0 == num_configs, return CL_INVALID_VALUE);
+  OCL_CHECK(!configs && num_configs, return CL_INVALID_VALUE);
 
-  OCL_CHECK(!mutable_config->mutable_dispatch_list ||
-                !mutable_config->num_mutable_dispatch,
-            return CL_INVALID_VALUE);
+  for (size_t i = 0; i < num_configs; i++) {
+    if (config_types[i] != CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR) {
+      return CL_INVALID_VALUE;
+    }
+  }
+
+  const cl_mutable_dispatch_config_khr **casted_configs =
+      reinterpret_cast<const cl_mutable_dispatch_config_khr **>(configs);
+  cargo::array_view<const cl_mutable_dispatch_config_khr *>
+      mutable_dispatch_configs(casted_configs, num_configs);
 
-  return command_buffer->updateCommandBuffer(*mutable_config);
+  return command_buffer->updateCommandBuffer(mutable_dispatch_configs);
 }
 
 CL_API_ENTRY cl_int CL_API_CALL clGetMutableCommandInfoKHR(