Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit c2e3f79

Browse files
EwanCEwanC
committedMar 28, 2024·
cl_khr_command_buffer_mutable_memory_commands extension
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`.
1 parent 2673582 commit c2e3f79

7 files changed

+522
-8
lines changed
 

‎api/cl_khr_command_buffer.asciidoc

+1
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ functionality expanding on this is provided as layered extensions on top of
129129

130130
* `<<cl_khr_command_buffer_multi_device>>`
131131
* `<<cl_khr_command_buffer_mutable_dispatch>>`
132+
* `<<cl_khr_command_buffer_mutable_memory_commands>>`
132133

133134
Having `cl_khr_command_buffer` as a minimal base specification means that the
134135
API defines mechanisms for functionality that is not enabled by this extension,

‎api/cl_khr_command_buffer_mutable_dispatch.asciidoc

+6-2
Original file line numberDiff line numberDiff line change
@@ -44,15 +44,19 @@ in a new command-buffer.
4444
=== Interactions With Other Extensions
4545

4646
The {clUpdateMutableCommandsKHR} entry-point has been designed for the purpose
47-
of allowing expansion of mutable functionality in future extensions layered on
48-
top of `cl_khr_command_buffer_mutable_dispatch`.
47+
of allowing expansion of mutable functionality in extensions layered on top of
48+
`cl_khr_command_buffer_mutable_dispatch`.
4949

5050
A new extension can define its own structure type to specify the update
5151
configuration it requires, with a matching
5252
{cl_command_buffer_update_type_khr_TYPE} value. This new structure type can
5353
then be passed to {clUpdateMutableCommandsKHR} where it is reinterpreted from a
5454
void pointer using {cl_command_buffer_update_type_khr_TYPE}.
5555

56+
<<cl_khr_command_buffer_mutable_memory_commands>> is one such extension that
57+
takes advantage of this mechanism to enable updating arguments to command-buffer
58+
memory commands.
59+
5660
=== New Types
5761

5862
* {cl_mutable_dispatch_fields_khr_TYPE}

‎api/cl_khr_command_buffer_mutable_memory_commands.asciidoc

+209
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
// Copyright 2018-2024 The Khronos Group Inc.
2+
// SPDX-License-Identifier: CC-BY-4.0
3+
4+
include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_memory_commands.txt[]
5+
6+
=== Other Extension Metadata
7+
8+
*Last Modified Date*::
9+
2024-03-28
10+
*IP Status*::
11+
No known IP claims.
12+
*Contributors*::
13+
- Ewan Crawford, Codeplay Software Ltd.
14+
- Kenneth Benzie, Codeplay Software Ltd.
15+
- Jack Frankland, Codeplay Software Ltd.
16+
- Ben Ashbaugh, Intel.
17+
- Balaji Calidas, Qualcomm Technologies Inc.
18+
- Sreelakshmi Haridas Maruthur, Qualcomm Technologies Inc.
19+
- Kevin Petit, Arm Ltd.
20+
21+
=== Description
22+
23+
The <<cl_khr_command_buffer>> extension separates command construction from
24+
enqueue by providing a mechanism to record an immutable set of commands which
25+
can then be repeatedly enqueued. Another extension layered on top,
26+
<<cl_khr_command_buffer_mutable_dispatch>> allows ND-Range kernel execution
27+
commands recorded to a command-buffer to be modified between command-buffer
28+
enqueues by providing a command-buffer update API {clUpdateMutableCommandsKHR}.
29+
30+
`cl_khr_command_buffer_mutable_memory_commands` builds on
31+
<<cl_khr_command_buffer_mutable_dispatch>> to use the {clUpdateMutableCommandsKHR}
32+
entry-point for enabling mutability of _memory-commands_ recorded to a
33+
command-buffer, those commands taking a {cl_mem_TYPE} or SVM pointer argument.
34+
35+
=== New Structures
36+
37+
* {cl_mutable_copy_buffer_command_config_khr_TYPE}
38+
* {cl_mutable_copy_buffer_rect_command_config_khr_TYPE}
39+
* {cl_mutable_copy_buffer_to_image_command_config_khr_TYPE}
40+
* {cl_mutable_copy_image_command_config_khr_TYPE}
41+
* {cl_mutable_copy_image_to_buffer_command_config_khr_TYPE}
42+
* {cl_mutable_fill_buffer_command_config_khr_TYPE}
43+
* {cl_mutable_fill_image_command_config_khr_TYPE}
44+
* {cl_mutable_svm_memcpy_command_config_khr_TYPE}
45+
* {cl_mutable_svm_memfill_command_config_khr_TYPE}
46+
47+
=== New Enums
48+
49+
* {cl_device_command_buffer_capabilities_khr_TYPE}
50+
** {CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR}
51+
* {cl_command_buffer_flags_khr_TYPE}
52+
** {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}
53+
* {cl_command_buffer_update_type_khr_TYPE}
54+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_COMMAND_CONFIG_KHR}
55+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_COMMAND_CONFIG_KHR}
56+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_RECT_COMMAND_CONFIG_KHR}
57+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_TO_IMAGE_COMMAND_CONFIG_KHR}
58+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_TO_IMAGE_COMMAND_CONFIG_KHR}
59+
** {CL_STRUCTURE_TYPE_MUTABLE_COPY_IMAGE_TO_BUFFER_COMMAND_CONFIG_KHR}
60+
** {CL_STRUCTURE_TYPE_MUTABLE_FILL_BUFFER_COMMAND_CONFIG_KHR}
61+
** {CL_STRUCTURE_TYPE_MUTABLE_FILL_IMAGE_COMMAND_CONFIG_KHR}
62+
** {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMCPY_COMMAND_CONFIG_KHR}
63+
** {CL_STRUCTURE_TYPE_MUTABLE_SVM_MEMFILL_COMMAND_CONFIG_KHR}
64+
65+
=== Sample Code
66+
67+
==== Sample Application Updating the Arguments to a Copy Buffer Command Between Command-buffer Submissions
68+
69+
[source,cpp]
70+
----
71+
#define CL_CHECK(ERROR) \
72+
if (ERROR) { \
73+
std::cerr << "OpenCL error: " << ERROR << "\n"; \
74+
return ERROR; \
75+
}
76+
77+
int main() {
78+
cl_platform_id platform;
79+
CL_CHECK(clGetPlatformIDs(1, &platform, nullptr));
80+
cl_device_id device;
81+
CL_CHECK(clGetDeviceIDs(platform, CL_DEVICE_TYPE_ALL, 1, &device, nullptr));
82+
83+
cl_int error;
84+
cl_context context =
85+
clCreateContext(nullptr, 1, &device, nullptr, nullptr, &error);
86+
CL_CHECK(error);
87+
88+
cl_command_queue command_queue =
89+
clCreateCommandQueue(context, device, 0, &error);
90+
CL_CHECK(error);
91+
92+
size_t num_bytes = 128;
93+
cl_mem bufferA =
94+
clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
95+
CL_CHECK(error);
96+
97+
// Populate bufferA with data
98+
99+
cl_mem bufferB =
100+
clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
101+
CL_CHECK(error);
102+
103+
// Populate bufferB with data
104+
105+
cl_mem bufferC =
106+
clCreateBuffer(context, CL_MEM_READ_WRITE, num_bytes, nullptr, &error);
107+
CL_CHECK(eror);
108+
109+
cl_command_buffer_properties_khr properties[3] = {
110+
CL_COMMAND_BUFFER_FLAGS_KHR,
111+
CL_COMMAND_BUFFER_MUTABLE_KHR | CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR,
112+
0
113+
};
114+
115+
cl_command_buffer_khr command_buffer =
116+
clCreateCommandBufferKHR(1, &command_queue, properties, &error);
117+
CL_CHECK(error)
118+
119+
cl_mutable_command_khr copy_command_handle;
120+
CL_CHECK(clCommandCopyBufferKHR(
121+
command_buffer,
122+
command_queue,
123+
bufferA,
124+
bufferC,
125+
0,
126+
0,
127+
num_bytes,
128+
0,
129+
nullptr,
130+
nullptr,
131+
&copy_command_handle);
132+
133+
CL_CHECK(clFinalizeCommandBufferKHR(command_buffer));
134+
CL_CHECK(clEnqueueCommandBufferKHR(0, nullptr, command_buffer, 0, nullptr,
135+
nullptr));
136+
137+
cl_mutable_copy_buffer_command_config_khr buffer_copy_config = {
138+
copy_command_handle, // command
139+
bufferB, // src_buffer
140+
bufferC, // dst_buffer
141+
0, // src_offset
142+
0, // dst_offset
143+
num_bytes // size
144+
};
145+
146+
cl_uint num_configs = 1;
147+
cl_update_config_type_khr config_types[1] = {
148+
CL_STRUCTURE_TYPE_MUTABLE_COPY_BUFFER_COMMAND_CONFIG_KHR
149+
};
150+
void* configs[1] = {&buffer_copy_config};
151+
CL_CHECK(clUpdateMutableCommandsKHR(command_buffer, num_configs,
152+
config_types, configs));
153+
CL_CHECK(clEnqueueCommandBufferKHR(command_buffer, 0, nullptr, nullptr));
154+
CL_CHECK(clFinish(command_queue));
155+
156+
CL_CHECK(clReleaseCommandBufferKHR(command_buffer));
157+
CL_CHECK(clReleaseCommandQueue(command_queue));
158+
CL_CHECK(clReleaseContext(context));
159+
160+
CL_CHECK(clReleaseMemObject(bufferA));
161+
CL_CHECK(clReleaseMemObject(bufferB));
162+
CL_CHECK(clReleaseMemObject(bufferC));
163+
164+
return 0;
165+
}
166+
----
167+
168+
=== Conformance tests
169+
170+
TODO - OpenCL-CTS Github issue with CTS plan once API design has been agreed.
171+
172+
=== Modifications to Section 5.X - Command Buffers of OpenCL API specification
173+
174+
==== Memory-Command Modifications
175+
176+
The descriptions of command recording entry-points that operate on {cl_mem_TYPE}
177+
or SVM pointer arguments are modified as described in this section. These
178+
changes apply to all of {clCommandCopyBufferKHR}, {clCommandCopyBufferRectKHR},
179+
{clCommandCopyBufferToImageKHR}, {clCommandCopyImageKHR},
180+
{clCommandCopyImageToBufferKHR}, {clCommandFillBufferKHR},
181+
{clCommandFillImageKHR}, {clCommandSVMMemcpyKHR}, and {clCommandSVMMemFillKHR}.
182+
183+
===== Parameter Update
184+
185+
Parameter description of _mutable_handle_ is changed to:
186+
187+
_mutable_handle_ Returns a handle to the command that can be used to modify the
188+
command between enqueues of _command_buffer_. _mutable_handle_ may be `NULL`. The
189+
lifetime of this handle is tied to the parent command-buffer, such that freeing
190+
the command-buffer will also free this handle.
191+
192+
===== Error Updates
193+
194+
The error condition
195+
196+
* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`.
197+
198+
Is replaced with
199+
200+
* {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL` and _command_buffer_
201+
was not created with property {CL_MUTABLE_MEM_COMMANDS_ENABLE_KHR}.
202+
203+
204+
include::provisional_notice.asciidoc[]
205+
206+
=== Version History
207+
208+
* Revision 0.9.0, 2024-03-28
209+
** First assigned version (provisional).

‎api/opencl_platform_layer.asciidoc

+9
Original file line numberDiff line numberDiff line change
@@ -1729,6 +1729,15 @@ ifdef::cl_khr_command_buffer_multi_device[]
17291729
include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR.asciidoc[]
17301730
endif::cl_khr_command_buffer_multi_device[]
17311731

1732+
ifdef::cl_khr_command_buffer_mutable_memory_commands[]
1733+
{CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR_anchor} Device
1734+
supports the ability to modify the {cl_mem_TYPE} arguments and SVM
1735+
pointers to commands operating on memory objects between command-buffer
1736+
invocations.
1737+
1738+
include::{generated}/api/version-notes/CL_COMMAND_BUFFER_CAPABILITY_MUTABLE_MEM_COMMANDS_KHR.asciidoc[]
1739+
endif::cl_khr_command_buffer_mutabl_memory_commands[]
1740+
17321741
| {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR_anchor}
17331742

17341743
include::{generated}/api/version-notes/CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR.asciidoc[]

0 commit comments

Comments
 (0)
Please sign in to comment.