diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index a71d0ec9..d56fd97e 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -129,6 +129,7 @@ functionality expanding on this is provided as layered extensions on top of * `<>` * `<>` +* `<>` 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, diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index 0dca75da..19290cd7 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -44,8 +44,8 @@ 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 @@ -53,6 +53,10 @@ configuration it requires, with a matching then be passed to {clUpdateMutableCommandsKHR} where it is reinterpreted from a void pointer using {cl_command_buffer_update_type_khr_TYPE}. +<> 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} diff --git a/api/cl_khr_command_buffer_mutable_memory_commands.asciidoc b/api/cl_khr_command_buffer_mutable_memory_commands.asciidoc new file mode 100644 index 00000000..f2b793bd --- /dev/null +++ b/api/cl_khr_command_buffer_mutable_memory_commands.asciidoc @@ -0,0 +1,177 @@ +// 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 <> 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, +<> 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 +<> 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, + ©_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. + +include::provisional_notice.asciidoc[] + +=== Version History + + * Revision 0.9.0, 2024-03-28 + ** First assigned version (provisional). diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index c09ff430..6b2b763f 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/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[] diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 75d4bc4e..1a438aac 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14059,6 +14059,15 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] include::{generated}/api/version-notes/CL_COMMAND_BUFFER_MUTABLE_KHR.asciidoc[] endif::cl_khr_command_buffer_mutable_dispatch[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR_anchor} - Enable or disable modification of + command-buffer memory-commands between enqueues. If set, the modification + of the memory-commands in the command-buffer is enabled, otherwise it is + disabled. + +include::{generated}/api/version-notes/CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR.asciidoc[] +endif::cl_khr_command_buffer_mutable_memory_commands[] + The default value of this property is `0`. ifdef::cl_khr_command_buffer_mutable_dispatch[] @@ -14471,8 +14480,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_copy_buffer_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -14510,6 +14531,14 @@ New errors: command-buffer. * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized. * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandCopyBufferRectKHR',desc='Record a command to copy a rectangular region from one buffer object to another',type='protos'] @@ -14559,8 +14588,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_copy_buffer_rect_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] [NOTE] ==== @@ -14614,7 +14655,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandCopyBufferToImageKHR',desc='Record a command to copy a buffer object to an image object',type='protos'] @@ -14663,8 +14711,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_copy_buffer_to_image_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -14702,7 +14762,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandCopyImageKHR',desc='Record a command to copy between two image objects',type='protos'] @@ -14750,8 +14817,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_copy_image_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] [NOTE] ==== @@ -14796,7 +14875,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandCopyImageToBufferKHR',desc='Record a command to copy an image object to a buffer object',type='protos'] @@ -14845,8 +14931,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_copy_image_to_buffer_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -14884,7 +14982,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandFillBufferKHR',desc='Record a command to fill a buffer object with a pattern',type='protos'] @@ -14941,8 +15046,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_fill_buffer_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -14979,7 +15096,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandFillImageKHR',desc='Record a command to fill an image object with a specified color',type='protos'] @@ -15034,8 +15158,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_fill_image_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -15072,7 +15208,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandNDRangeKernelKHR',desc='Record a command to execute a kernel on a device',type='protos'] @@ -15382,8 +15525,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_svm_memcpy_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -15420,7 +15575,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- [open,refpage='clCommandSVMMemFillKHR',desc='Record a command to fill a region in SVM with a pattern of a given pattern size',type='protos'] @@ -15488,8 +15650,20 @@ after the function returns. If the _sync_point_wait_list_ and the _sync_point_ arguments are not `NULL`, the _sync_point_ argument should not refer to an element of the _sync_point_wait_list_ array. - * _mutable_handle_ returns a handle to the command. - This parameter is unused, and **must** be `NULL`. + * _mutable_handle_ Returns a handle to the command that can be used to modify + the command between enqueues of _command_buffer_. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is not + supported, this parameter is unused, and **must** be `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + If the `<>` extension is + supported, and _mutable_handle_ is not `NULL`, it can be used in the + {cl_mutable_svm_memfill_command_config_khr_TYPE} struct to update the + command configuration between recordings. The lifetime of this handle is + tied to the parent command-buffer, such that freeing the command-buffer + will also free this handle. +endif::cl_khr_command_buffer_mutable_memory_commands[] // refError @@ -15526,7 +15700,14 @@ 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 _mutable_handle_ is not `NULL`. +ifndef::cl_khr_command_buffer_mutable_memory_commands[] + * {CL_INVALID_VALUE} if the `<>` + extension is not supported and _mutable_handle_ is not `NULL`. +endif::cl_khr_command_buffer_mutable_memory_commands[] +ifdef::cl_khr_command_buffer_mutable_memory_commands[] +* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_ + was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}. +endif::cl_khr_command_buffer_mutable_memory_commands[] -- @@ -15684,6 +15865,23 @@ kernel commands using that object as an argument have had their arguments replaced with a different object. ==== +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + +Further mutability for modifying _memory-commands_ recorded to a command-buffer +is also possible, defined as those commands taking a {cl_mem_TYPE} or SVM +pointer argument. + +The struct types defined by the <> extension +for each memory-command type can be used in {clUpdateMutableCommandsKHR} to +update the command configuration. + +The {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR} flag must be set on command-buffer +creation to enable memory-command update functionality, in combination with +{CL_COMMAND_BUFFER_MUTABLE_KHR} which is requires to use the +{clUpdateMutableCommandsKHR} entry-point. + +endif::cl_khr_command_buffer_mutable_memory_commands[] + To facilitate performant usage for pipelined work flows, where applications repeatedly call command-buffer update then enqueue, implementations may defer some of the work to allow {clUpdateMutableCommandsKHR} to return @@ -15792,6 +15990,22 @@ conditions: or _arg_svm_list_ is not `NULL` and _num_svm_args_ is 0. * {CL_INVALID_VALUE} if _exec_info_list_ is `NULL` and _num_exec_infos_ > 0, or _exec_info_list_ is not `NULL` and _num_exec_infos_ is 0. + +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + +If _configs_ is non-`NULL`, then for any memory-command structs in the +_configs_ array, the errors defined by the associated command-buffer command +creation entry-point are returned if a struct element is set to an invlaid +value. Additionally, the following erros are returned: + +* {CL_INVALID_MUTABLE_COMMAND_KHR} if the _command_ element of the struct is + not a valid mutable command object returned from the matching memory-command + entry-point. + +* {CL_INVALID_MUTABLE_COMMAND_KHR} if the _command_ was not created from + _command_buffer_. +endif::cl_khr_command_buffer_mutable_memory_commands[] + -- [[mutable-commands-update-structs]] @@ -15810,6 +16024,45 @@ reinterpreting a void pointer as when passed to {clUpdateMutableCommandsKHR}. | {cl_mutable_dispatch_config_khr_TYPE} | {clCommandNDRangeKernelKHR} +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + +| {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_copy_buffer_command_config_khr_TYPE} +| {clCommandCopyBufferKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_RECT_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_copy_buffer_rect_command_config_khr_TYPE} +| {clCommandCopyBufferRectKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_TO_IMAGE_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_copy_buffer_to_image_command_config_khr_TYPE} +| {clCommandCopyBufferToImageKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_copy_image_command_config_khr_TYPE} +| {clCommandCopyImageKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_TO_BUFFER_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_copy_image_to_buffer_command_config_khr_TYPE} +| {clCommandCopyImageToBufferKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_FILL_BUFFER_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_fill_buffer_command_config_khr_TYPE} +| {clCommandFillBufferKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_FILL_IMAGE_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_fill_image_command_config_khr_TYPE} +| {clCommandFillImageKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMCPY_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_svm_memcpy_command_config_khr_TYPE} +| {clCommandSVMMemcpyKHR} + +| {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMFILL_COMMAND_CONFIG_KHR_anchor} +| {cl_mutable_svm_memfill_command_config_khr_TYPE} +| {clCommandSVMMemFillKHR} +endif::cl_khr_command_buffer_mutable_memory_commands[] + |==== ==== Kernel Command Update Structs @@ -15892,6 +16145,86 @@ _param_name_ is of type {cl_uint_TYPE} rather than OpenCL 1.2 where the {cl_kernel_exec_info_TYPE} typedef is unavailable. ==== -- + +ifdef::cl_khr_command_buffer_mutable_memory_commands[] + +==== Memory Command Update Structs + +[[cl_mutable_copy_buffer_command_config_khr]] +include::{generated}/api/structs/cl_mutable_copy_buffer_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandCopyBufferKHR}. + +_src_buffer_, _dst_buffer_, _src_offset_, _dst_offset_, _size_ as specified by +the associated {clCommandCopyBufferKHR} parameters. + +[[cl_mutable_copy_buffer_rect_command_config_khr]] +include::{generated}/api/structs/cl_mutable_copy_buffer_rect_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandCopyBufferRectKHR}. + +_src_buffer_, _dst_buffer_, _src_origin_, _dst_origin_, _region_, _src_row_pitch_, +_src_slice_pitch_, _dst_row_pitch_, _dst_slice_pitch_ as specified by the +associated {clCommandCopyBufferRectKHR} parameters. + +[[cl_mutable_copy_buffer_to_image_command_config_khr]] +include::{generated}/api/structs/cl_mutable_copy_buffer_to_image_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandCopyBufferToImageKHR}. + +_src_buffer_, _dst_image_, _src_offset_, _dst_origin_, _region_ as specified by the +associated {clCommandCopyBufferToImageKHR} parameters. + +[[cl_mutable_copy_image_command_config_khr]] +include::{generated}/api/structs/cl_mutable_copy_image_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandCopyImageKHR}. + +_src_image_, _dst_image_, _src_origin_, _dst_origin_, _region_ as specified by the +associated {clCommandCopyImageKHR} parameters. + +[[cl_mutable_copy_image_to_buffer_command_config_khr]] +include::{generated}/api/structs/cl_mutable_copy_image_to_buffer_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandCopyImageToBufferKHR}. + +_src_image_, _dst_buffer_, _src_origin_, _region_, _dst_offset_ as specified by the +associated {clCommandCopyImageToBufferKHR} parameters. + +[[cl_mutable_fill_buffer_command_config_khr]] +include::{generated}/api/structs/cl_mutable_fill_buffer_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandFillBufferKHR}. + +_buffer_, _pattern_, _pattern_size_, _offset_, _size_ as specified by the +associated {clCommandFillBufferKHR} parameters. + +[[cl_mutable_fill_image_command_config_khr]] +include::{generated}/api/structs/cl_mutable_fill_image_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandFillImageKHR}. + +_image_, _fill_color_, _origin_, _region_ as specified by the associated +{clCommandFillImageKHR} parameters. + +[[cl_mutable_svm_memcpy_command_config_khr]] +include::{generated}/api/structs/cl_mutable_svm_memcpy_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandSVMMemcpyKHR}. + +_dst_ptr_, _src_ptr_, _size_ as specified by the associated {clCommandSVMMemcpyKHR} +parameters. + +[[cl_mutable_svm_memfill_command_config_khr]] +include::{generated}/api/structs/cl_mutable_svm_memfill_command_config_khr.txt[] + +_command_ A mutable-command object returned by {clCommandSVMMemFillKHR}. + +_svm_ptr_, _pattern_, _pattern_size_, _size_ as specified by the associated +{clCommandSVMMemFillKHR} parameters. + +endif::cl_khr_command_buffer_mutable_memory_commands[] + endif::cl_khr_command_buffer_mutable_dispatch[] diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index 3b47e039..db736c05 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -48,6 +48,10 @@ Language Specifications. | Modify kernel execution commands between enqueues of a command-buffer | Provisional Extension +| [[cl_khr_command_buffer_mutable_memory_commands]] link:{APISpecURL}#cl_khr_command_buffer_mutable_memory_commands[`cl_khr_command_buffer_mutable_memory_commands`] +| Modify memory commands between enqueues of a command-buffer +| Provisional Extension + | [[cl_khr_create_command_queue]] link:{APISpecURL}#cl_khr_create_command_queue[`cl_khr_create_command_queue`] | API to Create Command-Queues with Properties | Core Feature in OpenCL 2.0 diff --git a/xml/cl.xml b/xml/cl.xml index da5bc029..f1f74c3f 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -366,6 +366,88 @@ server's OpenCL/api-docs repository. const size_t* global_work_size const size_t* local_work_size + + + cl_mutable_command_khr command + cl_mem src_buffer + cl_mem dst_buffer + size_t src_offset + size_t dst_offset + size_t size + + + + cl_mutable_command_khr command + cl_mem src_buffer + cl_mem dst_buffer + const size_t* src_origin + const size_t* dst_origin + const size_t* region + size_t src_row_pitch + size_t src_slice_pitch + size_t dst_row_pitch + size_t dst_slice_pitch + + + + cl_mutable_command_khr command + cl_mem src_buffer + cl_mem dst_image + size_t src_offset + const size_t* dst_origin + const size_t* region + + + + cl_mutable_command_khr command + cl_mem src_image + cl_mem dst_image + const size_t* src_origin + const size_t* dst_origin + const size_t* region + + + + cl_mutable_command_khr command + cl_mem src_image + cl_mem dst_buffer + const size_t* src_origin + const size_t* region + size_t dst_offset + + + + cl_mutable_command_khr command + cl_mem buffer + const void* pattern + size_t pattern_size + size_t offset + size_t size + + + + cl_mutable_command_khr command + cl_mem image + const void* fill_color + const size_t* origin + const size_t* region + + + + cl_mutable_command_khr command + void* dst_ptr + const void* src_ptr + size_t pattern_size + size_t size + + + + cl_mutable_command_khr command + void* svm_ptr + const void* pattern + size_t pattern_size + size_t size + @@ -1316,7 +1398,7 @@ server's OpenCL/api-docs repository. - + @@ -1324,7 +1406,7 @@ server's OpenCL/api-docs repository. - + @@ -1346,8 +1428,17 @@ server's OpenCL/api-docs repository. - - + + + + + + + + + + + @@ -1770,7 +1861,7 @@ server's OpenCL/api-docs repository. - + @@ -7435,10 +7526,45 @@ server's OpenCL/api-docs repository. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +