diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index 980c2dc1f..bb18e56ee 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_dispatch.txt[ === Other Extension Metadata *Last Modified Date*:: - 2025-08-08 + 2025-09-30 *IP Status*:: No known IP claims. *Contributors*:: @@ -45,10 +45,15 @@ in a new command-buffer. The optional <> capability was added to the extension so that vendors could support concurrent execution of the same -command-buffer object which has been updated between submissions. However, -simultaneous use may result in command-buffers having a larger overhead to -implement, so the capability is optional to enable optimizations when this -usage isn't required by a user. +command-buffer object. However, simultaneous use may result in command-buffers +having a larger overhead to implement, so the capability is optional to enable +optimizations when this usage isn't required by a user. + +==== Simultaneous Update + +The optional <> capability adds support +for updating the command-buffer without requiring the application to wait on the +previous enqueues of the command-buffer to reach completed state. === Interactions With Other Extensions @@ -83,6 +88,7 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}. ** {CL_DEVICE_MUTABLE_DISPATCH_CAPABILITIES_KHR} * {cl_device_command_buffer_capabilities_khr_TYPE} ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR} + ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR} * {cl_command_properties_khr_TYPE} ** {CL_MUTABLE_DISPATCH_ASSERTS_KHR} ** {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR} @@ -107,6 +113,7 @@ void pointer using {cl_command_buffer_update_type_khr_TYPE}. * {cl_command_buffer_flags_khr_TYPE} ** {CL_COMMAND_BUFFER_MUTABLE_KHR} ** {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} + ** {CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR} * {cl_command_buffer_properties_khr_TYPE} ** {CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR} * {cl_command_buffer_update_type_khr_TYPE} @@ -381,6 +388,9 @@ may be a introduced as a stand alone extension. ** Move `CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR` and `CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR` in this extension from the base extension (experimental). - * Revision 0.9.5 2025-08-28 - ** Permitting recording ND-range kernel commands without having set all of - their arguments (experimental). + * Revision 0.9.5, 2025-08-28 + ** Permitting recording ND-range kernel commands without having set all of + their arguments (experimental). + * Revision 0.9.6, 2025-09-30 + ** Add `CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR` and + `CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR` (experimental). diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 762bd5d8e..1cdf8ecdd 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -1819,6 +1819,12 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] simultaneous use>> usage pattern. include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR.asciidoc[] + + {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR_anchor} Device + supports updating command-buffers with a <> usage pattern. + +include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR.asciidoc[] endif::cl_khr_command_buffer_mutable_dispatch[] ifdef::cl_khr_command_buffer_multi_device[] diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index a1417619e..a7d37fad1 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14725,16 +14725,16 @@ usage>>. Simultaneous use is defined using the _prerequisite_ terminology from the <<_execution_model, execution model>>. -ifndef::cl_khr_command_buffer_multi_device[] +ifndef::cl_khr_command_buffer_mutable_dispatch[] A command-buffer exhibits undefined behavior if a simultaneous use pattern occurs. -endif::cl_khr_command_buffer_multi_device[] -ifdef::cl_khr_command_buffer_multi_device[] +endif::cl_khr_command_buffer_mutable_dispatch[] +ifdef::cl_khr_command_buffer_mutable_dispatch[] Simultaneous use is an optional feature for devices to support concurrent -executions of a command-buffer which have been updated between submissions. -A command-buffer must be created with {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} -to avoid undefined behavior if a simultaneous use pattern occurs. -endif::cl_khr_command_buffer_multi_device[] +executions of a command-buffer. A command-buffer must be created with +{CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} to avoid undefined behavior if a +simultaneous use pattern occurs. +endif::cl_khr_command_buffer_mutable_dispatch[] [[simultaneous-use]] Simultaneous Use:: When a command-buffer is submitted for @@ -14750,6 +14750,28 @@ in-order queue, events, or barriers to express dependencies between submissions of the same command-buffer would each be ways to avoid simultaneous use. ==== +ifndef::cl_khr_command_buffer_mutable_dispatch[] +A command-buffer exhibits undefined behavior if a simultaneous update +pattern occurs. +endif::cl_khr_command_buffer_mutable_dispatch[] +ifdef::cl_khr_command_buffer_mutable_dispatch[] +Simultaneous update is an optional feature for devices to support updating a +command-buffer while all the previous submissions of the same command-buffer +have not finished. A command-buffer must be created with +{CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR} to avoid undefined behavior if a +simultaneous update pattern occurs. +endif::cl_khr_command_buffer_mutable_dispatch[] + +[[simultaneous-update]] +Simultaneous Update:: When a command-buffer is updated while any of the previous +submissions of the same command-buffer is not in the {CL_COMPLETE} state. + +[NOTE] +==== +An example of simultaneous update would be calling {clUpdateMutableCommandsKHR} +after submitting a command-buffer without waiting on the submission event. +==== + ifdef::cl_khr_command_buffer_multi_device[] === Command-Buffers and Multiple Devices @@ -14874,6 +14896,14 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR}. include::{generated}/api/version-notes/CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR.asciidoc[] + + {CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR_anchor} - Allow an + instance of the command-buffer to be updated in a usage pattern that + exhibits <>. If set, + devices must support {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR}. + +include::{generated}/api/version-notes/CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR.asciidoc[] + endif::cl_khr_command_buffer_mutable_dispatch[] ifdef::cl_khr_command_buffer_multi_device[] @@ -16757,6 +16787,14 @@ one of the errors below is returned: * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. +If the implementation supports the +{CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR} capability, and the +command-buffer was created with the {CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR} +flag, {clUpdateMutableCommandsKHR} can be called without waiting for previous +submissions of the command-buffer to be completed. If this capability is not +supported, updating the command-buffer in a <> pattern will result in undefined behavior. + [NOTE] ==== Performant usage is to call {clUpdateMutableCommandsKHR} only when the diff --git a/xml/cl.xml b/xml/cl.xml index d6cd517b8..bbfc568fd 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -1451,7 +1451,7 @@ server's OpenCL/api-docs repository. - + @@ -1461,7 +1461,7 @@ server's OpenCL/api-docs repository. - + @@ -7660,7 +7660,7 @@ server's OpenCL/api-docs repository. - + @@ -7675,11 +7675,13 @@ server's OpenCL/api-docs repository. + +