Skip to content

Commit

Permalink
cl_khr_command_buffer_mutable_memory_commands extension
Browse files Browse the repository at this point in the history
Draft of `cl_khr_command_buffer_mutable_memory_commands` based
ontop of #1045
which updates `clUpdateMutableCommandsKHR` to pass configs
by an array rather than linked list.

The goal of this extension is to be able to update the parameters to memory
operation commands in a command-buffer after the command-buffer has been
finalized using the `clUpdateMutableCommandsKHR` entry-point defined by
`cl_khr_command_buffer_mutable_dispatch`.
  • Loading branch information
EwanC committed Mar 29, 2024
1 parent 2673582 commit 088995d
Show file tree
Hide file tree
Showing 7 changed files with 688 additions and 34 deletions.
1 change: 1 addition & 0 deletions api/cl_khr_command_buffer.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ functionality expanding on this is provided as layered extensions on top of

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

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 Down
8 changes: 6 additions & 2 deletions api/cl_khr_command_buffer_mutable_dispatch.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,19 @@ 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
{cl_command_buffer_update_type_khr_TYPE} value. This new structure type can
then be passed to {clUpdateMutableCommandsKHR} where it is reinterpreted from a
void pointer using {cl_command_buffer_update_type_khr_TYPE}.

<<cl_khr_command_buffer_mutable_memory_commands>> 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}
Expand Down
177 changes: 177 additions & 0 deletions api/cl_khr_command_buffer_mutable_memory_commands.asciidoc
Original file line number Diff line number Diff line change
@@ -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 <<cl_khr_command_buffer>> 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,
<<cl_khr_command_buffer_mutable_dispatch>> 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
<<cl_khr_command_buffer_mutable_dispatch>> 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,
&copy_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).
9 changes: 9 additions & 0 deletions api/opencl_platform_layer.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
Loading

0 comments on commit 088995d

Please sign in to comment.