Skip to content

Commit

Permalink
Reference layered extensions in command-buffer intro (#1090)
Browse files Browse the repository at this point in the history
The "Interaction With Other Extensions" introductory section
of `cl_khr_command_buffer` references future layered extensions
as part of the design rationale.

Two of these layered extensions currently exist, so we can
update this section to reference them directly as opposed to
the existing speculative language.
  • Loading branch information
EwanC committed Mar 26, 2024
1 parent ce502ec commit 484432c
Showing 1 changed file with 23 additions and 16 deletions.
39 changes: 23 additions & 16 deletions api/cl_khr_command_buffer.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -123,9 +123,12 @@ the capability is optional to enable optimizations on command-buffer recording.
The introduction of the command-buffer abstraction enables functionality
beyond what the `cl_khr_command_buffer` extension currently provides, i.e.
the recording of immutable commands to a single queue which can then be
executed without commands synchronizing outside the command-buffer. It is
intended that extra functionality expanding on this will be provided as layered
extensions on top of `cl_khr_command_buffer`.
executed without commands synchronizing outside the command-buffer. Extra
functionality expanding on this is provided as layered extensions on top of
`cl_khr_command_buffer`. The layered extensions that currently exist are:

* `<<cl_khr_command_buffer_multi_device>>`
* `<<cl_khr_command_buffer_mutable_dispatch>>`

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,
Expand All @@ -138,29 +141,33 @@ support their intended use cases.

The {clCommandNDRangeKernelKHR} entry-point defines a `properties` parameter of
new type {cl_ndrange_kernel_command_properties_khr_TYPE}. No properties are defined
in `cl_khr_command_buffer`, but the parameter is intended to enable future
functionality that would change the characteristics of the kernel command.
in `cl_khr_command_buffer`, but the parameter enables layered extensions like
`<<cl_khr_command_buffer_mutable_dispatch>>` to define properties that inform
the characteristics of the kernel command.

==== Command Handles

All command recording entry-points define a {cl_mutable_command_khr_TYPE} output
parameter which provides a handle to the specific command being recorded. Use of
these output handles is not enabled by the `cl_khr_command_buffer` extension,
but the handles will allow individual commands in a command-buffer to be
referenced by the user. In particular, the capability for an application to use
these handles to modify commands between enqueues of a command-buffer is
envisaged.
but the handles allow individual commands in a command-buffer to be
referenced by the user.

Use of these handles is enabled in `<<cl_khr_command_buffer_mutable_dispatch>>`
to give the capability for an application to use the handles to modify commands
between enqueues of a command-buffer.

==== List of Queues

Only a single command-queue can be associated with a command-buffer in the
`cl_khr_command_buffer` extension, but the API is designed with the intention
that a future extension will allow commands to be recorded across multiple
queues in the same command-buffer, providing replay of heterogeneous task
graphs.

Using multiple queue functionality will result in an error without any layered
extensions to relax usage of the following API features:
`cl_khr_command_buffer` extension, but the API is designed so that the layered
`<<cl_khr_command_buffer_multi_device>>` extension can relax this constraint
to allow commands to be recorded across multiple queues in the same
command-buffer, providing replay of heterogeneous task graphs.

Using multiple queue functionality will result in an error without
`<<cl_khr_command_buffer_multi_device>>` to relax usage of the following API
features:

* When a command-buffer is created the API enables passing a list of queues
that the command-buffer will record commands to. Only a single queue is
Expand Down

0 comments on commit 484432c

Please sign in to comment.