Skip to content

Add simultaneous update capability #1466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joselopeqti wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add simultaneous update capability #1466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
399c3de
Add simultaneous update capability
joselopeqti Sep 30, 2025
1d444a6
Merge remote-tracking branch 'upstream/main' into simultaneous_update
joselopeqti Sep 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions api/cl_khr_command_buffer_mutable_dispatch.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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*::
Expand Down Expand Up @@ -45,10 +45,15 @@ in a new command-buffer.

The optional <<simultaneous-use, simultaneous use>> 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 <<simultaneous-update, simultaneous update>> 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

Expand Down Expand Up @@ -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}
Expand All @@ -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}
Expand Down Expand Up @@ -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).
6 changes: 6 additions & 0 deletions api/opencl_platform_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<simultaneous-update,
simultaneous update>> 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[]
Expand Down
52 changes: 45 additions & 7 deletions api/opencl_runtime_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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 <<simultaneous-update, simultaneous update>>. 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[]
Expand Down Expand Up @@ -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 <<simultaneous-update, simultaneous-
update>> pattern will result in undefined behavior.

[NOTE]
====
Performant usage is to call {clUpdateMutableCommandsKHR} only when the
Expand Down
8 changes: 5 additions & 3 deletions xml/cl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1451,7 +1451,7 @@ server's OpenCL/api-docs repository.
<enum bitpos="0" name="CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR"/>
<enum bitpos="1" name="CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR"/>
<enum bitpos="2" name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
<unused start="3" end="3" comment="Available for future use"/>
<enum bitpos="3" name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR"/>
<enum bitpos="4" name="CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR"/>
<unused start="5" end="6" comment="Used by future command-buffer extensions"/>
<unused start="6" end="31"/>
Expand All @@ -1461,7 +1461,7 @@ server's OpenCL/api-docs repository.
<enum bitpos="0" name="CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR"/>
<enum bitpos="1" name="CL_COMMAND_BUFFER_MUTABLE_KHR"/>
<enum bitpos="2" name="CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR"/>
<unused start="3" end="4" comment="Used by future command-buffer extensions"/>
<enum bitpos="3" name="CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR"/>
<unused start="4" end="31"/>
</enums>

Expand Down Expand Up @@ -7660,7 +7660,7 @@ server's OpenCL/api-docs repository.
<enum name="CL_QUEUE_JOB_SLOT_ARM"/>
</require>
</extension>
<extension name="cl_khr_command_buffer_mutable_dispatch" revision="0.9.5" supported="opencl" depends="cl_khr_command_buffer" ratified="opencl" experimental="true" comment="requires cl_khr_command_buffer 0.9.8 or later">
<extension name="cl_khr_command_buffer_mutable_dispatch" revision="0.9.6" supported="opencl" depends="cl_khr_command_buffer" ratified="opencl" experimental="true" comment="requires cl_khr_command_buffer 0.9.8 or later">
<require>
<type name="CL/cl.h"/>
</require>
Expand All @@ -7675,11 +7675,13 @@ server's OpenCL/api-docs repository.
</require>
<require comment="cl_command_buffer_flags_khr - bitfield">
<enum name="CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR"/>
<enum name="CL_COMMAND_BUFFER_SIMULTANEOUS_UPDATE_KHR"/>
<enum name="CL_COMMAND_BUFFER_MUTABLE_KHR"/>
</require>

<require comment="cl_device_command_buffer_capabilities_khr - bitfield">
<enum name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
<enum name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_UPDATE_KHR"/>
</require>

<require comment="Error codes">
Expand Down