add command buffer emulation layer support for mutable dispatch (#63)

* start to add support for mutable command buffers

mutable command buffers are working

improve reporting and checks for extension support

add support for CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR

fix bug with multiple mutable dispatch configs

add missing include

* minor fixes, update README

Author: bashbaug

layers/10_cmdbufemu/emulate.cpp

@@ -156,6 +156,21 @@ cl_int CL_API_CALL clGetCommandBufferInfoKHR_EMU(
     void* param_value,
     size_t* param_value_size_ret);
 
+#if defined(cl_khr_command_buffer_mutable_dispatch)
+
+cl_int CL_API_CALL clUpdateMutableCommandsKHR_EMU(
+    cl_command_buffer_khr command_buffer,
+    const cl_mutable_base_config_khr* mutable_config);
+
+cl_int CL_API_CALL clGetMutableCommandInfoKHR_EMU(
+    cl_mutable_command_khr command,
+    cl_mutable_command_info_khr param_name,
+    size_t param_value_size,
+    void* param_value,
+    size_t* param_value_size_ret);
+
+#endif // defined(cl_khr_command_buffer_mutable_dispatch)
+
 ///////////////////////////////////////////////////////////////////////////////
 // Override Functions
 

layers/10_cmdbufemu/emulate.h

@@ -90,6 +90,11 @@ clGetExtensionFunctionAddressForPlatform_layer(
     CHECK_RETURN_EXTENSION_FUNCTION( clCommandNDRangeKernelKHR );
     CHECK_RETURN_EXTENSION_FUNCTION( clGetCommandBufferInfoKHR );
 
+#if defined(cl_khr_command_buffer_mutable_dispatch)
+    CHECK_RETURN_EXTENSION_FUNCTION( clUpdateMutableCommandsKHR );
+    CHECK_RETURN_EXTENSION_FUNCTION( clGetMutableCommandInfoKHR );
+#endif // defined(cl_khr_command_buffer_mutable_dispatch)
+
     return nullptr;
 }
 

layers/10_cmdbufemu/main.cpp

@@ -14,7 +14,7 @@ This sample requires the OpenCL Extension Loader to get the extension APIs for c
 
 This sample demonstrates how to query the command buffer properties supported by a device, and the properties of a command buffer.
 
-This sample also demostrates how to create, finalize, and execute a command buffer.
+This sample also demonstrates how to create, finalize, and execute a command buffer.
 
 ```c
 clCreateCommandBufferKHR

samples/12_commandbuffers/README.md

@@ -85,7 +85,7 @@ int main(
 
         if (printUsage || !op.unknown_options().empty() || !op.non_option_args().empty()) {
             fprintf(stderr,
-                "Usage: copybufferkernel [options]\n"
+                "Usage: commandbuffers [options]\n"
                 "%s", op.help().c_str());
             return -1;
         }

samples/12_commandbuffers/main.cpp

@@ -85,7 +85,7 @@ int main(
 
         if (printUsage || !op.unknown_options().empty() || !op.non_option_args().empty()) {
             fprintf(stderr,
-                "Usage: copybufferkernel [options]\n"
+                "Usage: commandbufferspp [options]\n"
                 "%s", op.help().c_str());
             return -1;
         }

samples/12_commandbufferspp/main.cpp

@@ -0,0 +1,11 @@
+# Copyright (c) 2022 Ben Ashbaugh
+#
+# SPDX-License-Identifier: MIT
+
+add_opencl_sample(
+    TEST
+    NUMBER 12
+    TARGET mutablecommandbuffers
+    VERSION 120
+    SOURCES main.cpp
+    LIBS OpenCLExt)

samples/13_mutablecommandbuffers/CMakeLists.txt

@@ -0,0 +1,29 @@
+# mutablecommandbuffers
+
+## Sample Purpose
+
+This is an intermediate-level sample that demonstrates how to use the OpenCL extension [cl_khr_command_buffer_mutable_dispatch](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_command_buffer_mutable_dispatch) to modify a command buffer after it has been finalized.
+As of this writing, `cl_khr_command_buffer_mutable_dispatch` is a provisional extension.
+This sample uses the functionality described in v0.9.0 of the extension.
+
+This is an optional extension and some devices may not support `cl_khr_command_buffer_mutable_dispatch`, but the sample may still run using the [cl_khr_command_buffer emulation layer](../../layers/10_cmdbufemu).
+
+This sample requires the OpenCL Extension Loader to get the extension APIs for command buffers.
+
+## Key APIs and Concepts
+
+This sample demonstrates how to query the mutable dispatch capabilities supported by a device, how to create a mutable command buffer, and how to query the properties of a mutable command.
+
+This sample also demonstrates how to mutate (modify) a command buffer after it has been finalized.
+
+```c
+clGetMutableCommandInfoKHR
+clUpdateMutableCommandsKHR
+```
+
+## Command Line Options
+
+| Option | Default Value | Description |
+|:--|:-:|:--|
+| `-d <index>` | 0 | Specify the index of the OpenCL device in the platform to execute on the sample on.
+| `-p <index>` | 0 | Specify the index of the OpenCL platform to execute the sample on.