setting kernel arguments before recording it in command buffer by aharon-abramson · Pull Request #1382 · KhronosGroup/OpenCL-Docs

aharon-abramson · 2025-06-03T11:48:30Z

Add an image for the life cycle in mutable command buffers and specify that there is no need to set all the kernel arguments before recording it.

Add type cl_mutable_dispatch_promises_khr and its possible values

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

Co-authored-by: Sun Serega <sunserega2@gmail.com>

replace error with undefined behavior

Co-authored-by: Sun Serega <sunserega2@gmail.com>

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

Co-authored-by: Sun Serega <sunserega2@gmail.com>

Delete obsolete comment in cl_khr_semaphore. Issue

…#991) * Use hexapdf instead of ghostscript for PDF optimization Resulting PDFs tend to be considerably smaller, and also runs about 15% faster when doing a full PDF build (2:39 vs. 3:06 on my machine). The hexapdf tool does need to be installed in the build environment - it is in the khronosgroup/docker-images:asciidoctor-spec Docker image. * Add hexapdf to Travis environment.

…hronosGroup#996) * cl_khr_semaphore: Enforce one device semaphores (KhronosGroup#973) Only permit semaphores to be associated with a single device. Add an error code for invalid use. * Changes wording according to review comments * Change error code to CL_INVALID_PROPERTY if a context is multi-device, and no device is specified.

Since the layers spec is not published in the OpenCL extension spec and is instead published on the OpenCL registry similar to EXT and vendor extensions, it makes more sense to put it in the extensions directory.

* cl_semaphore_khr: Query if semaphore is exportable Add query to clGetSemaphoreInfoKHR that returns CL_TRUE if a semaphore is exportable. * Change extension version to 0.9.1 * Add missing brackets around return types.

The default behavior when the device handle list is not specified is now properly described, so the TODO comment can be removed.

…es (KhronosGroup#1010)

Change-Id: I942c3ce47284e7aea93edc02cf0f327af95e4ed9

…ffer error handling and state requirements

…L-Docs into issue_1329

joselopeqti · 2025-07-22T10:14:25Z

We are ok with allowing applications to call clFinalizeCommandBufferKHR when all of the kernel arguments are not said. However we do have concerns about what the implementation must track and report regarding the state of the command buffer. Some of these concerns overlap with issue #1311. The concerns are -

Is the implementation expected to simply track whether or not all arguments have been set in a command buffer but not worry about which kernels have missing arguments?
Distinguishing Pending vs either Finalized or Executable state will be expensive to implement. We would prefer not to have the Finalized
Is the application expected to take responsibility for tracking command buffer state. Therefore neither the returned error message nor a direct query will be available to clearly detect finalized state

aharon-abramson · 2025-07-22T10:33:46Z

Yes, the implementation doesn't need to track which kernels have missing arguments.
Tracking if all kernels have all their arguments set is already required today when calling clFinalizeCommandBufferKHR, so I don't think adding the extra state adds more work.
I don't quite understand this point; is it a question?

EwanC · 2025-08-26T16:53:49Z

Now that #1411 is merged, this PR can be rebased. Let me know if you have any questions about how to resolve the conflicts, since there will definitely be some.

EwanC

Comments are all minor editorial points

images/commandbuffer_lifecycle.png

xml/cl.xml

api/opencl_runtime_layer.asciidoc

…utable_dispatch

EwanC

Spotted a couple other trivial things, but otherwise LGTM

api/opencl_runtime_layer.asciidoc

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

kpet

LGTM, thanks!

joselopeqti · 2025-09-04T17:45:21Z

Can we confirm that the only queryable command buffer states are recording, finalized and executable?

EwanC · 2025-09-05T08:16:02Z

Can we confirm that the only queryable command buffer states are recording, finalized and executable?

Yup that's the case. After #1411 merged the only queryable states became finalized or executable, then this PR adds the finalized state to that.

bashbaug · 2025-09-05T17:56:03Z

I think there's a small typo / copy paste error, and this should be:

After #1411 merged the only queryable states became >>>recording<<< or executable, then this PR adds the finalized state to that.

bashbaug · 2025-09-09T16:43:30Z

Merging as discussed in the September 9th teleconference.

KhronosGroup#1382 added support for deferring setting arguments on a kernel command which is updatable. To achieve this we added an extra command-buffer state, "Finalized" which is entered when a command-buffer has been finalized but doesn't yet have all it's arguments set. However, if a user tries to enqueue a command-buffer in this state it shouldn't be valid. Therefore update our current wording about when an command-buffer can be enqueued to say the specifically the executable state, rather than just after the finalization operation, which could result in the command-buffer being in either the finalization or executable state.

KhronosGroup#1382 added support for deferring setting arguments on a kernel command which is updatable. To achieve this we added an extra command-buffer state, "finalized" which is entered when a command-buffer has been finalized but doesn't yet have all it's arguments set. However, if a user tries to enqueue a command-buffer in this state it shouldn't be valid. Therefore update our current wording about when an command-buffer can be enqueued to say the specifically the executable state, when all arguments are available. Rather than defined as after the finalization operation, which could result in the command-buffer being in either the finalization or executable state. We already have a NOTE above to this effect, which I've removed as it felt like it didn't add any extra value above the error definition, but can added back if folks think it's worthwhile.

Tests the scenario outlined in KhronosGroup#2520 (comment) to verify the functionality added in OpenCL-Docs PR KhronosGroup/OpenCL-Docs#1382. Note that this bumps the required cl_khr_command_buffer_mutable_dispatch minor version by 2 because KhronosGroup#2477 is not yet merged which test the intermediate version. This also assumes the proposed OpenCL-Docs change in KhronosGroup/OpenCL-Docs#1471 is merged, as the PR does a negative test for command-buffer enqueue while the command-buffer is in the finalized state. Closes KhronosGroup#2520

#1382 added support for deferring setting arguments on a kernel command which is updatable. To achieve this we added an extra command-buffer state, "finalized" which is entered when a command-buffer has been finalized but doesn't yet have all it's arguments set. However, if a user tries to enqueue a command-buffer in this state it shouldn't be valid. Therefore update our current wording about when an command-buffer can be enqueued to say the specifically the executable state, when all arguments are available. Rather than defined as after the finalization operation, which could result in the command-buffer being in either the finalization or executable state. We already have a NOTE above to this effect, which I've removed as it felt like it didn't add any extra value above the error definition, but can added back if folks think it's worthwhile.

Tests the scenario outlined in KhronosGroup#2520 (comment) to verify the functionality added in OpenCL-Docs PR KhronosGroup/OpenCL-Docs#1382. Note that this bumps the required cl_khr_command_buffer_mutable_dispatch minor version by 2 because KhronosGroup#2477 is not yet merged which test the intermediate version. This also assumes the proposed OpenCL-Docs change in KhronosGroup/OpenCL-Docs#1471 is merged, as the PR does a negative test for command-buffer enqueue while the command-buffer is in the finalized state. Closes KhronosGroup#2520

Tests the scenario outlined in #2520 (comment) to verify the functionality added in OpenCL-Docs PR KhronosGroup/OpenCL-Docs#1382. Closes #2520 --------- Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

aharon-abramson and others added 30 commits November 6, 2023 14:53

Update cl_khr_command_buffer_mutable_dispatch.asciidoc

75c680a

Add type cl_mutable_dispatch_promises_khr and its possible values

Update cl_khr_command_buffer_mutable_dispatch.asciidoc

c37e00f

Update ext/cl_khr_command_buffer_mutable_dispatch.asciidoc

ed629a9

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

changes to cl.xml

e7d3343

update extension's version

392d97b

rename "promise" to "assert"

995886a

Update xml/cl.xml

38080d3

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

Update xml/cl.xml

cbf85b6

Co-authored-by: Sun Serega <sunserega2@gmail.com>

Update xml/cl.xml

711fcda

Co-authored-by: Sun Serega <sunserega2@gmail.com>

remove changes to files made by mistake

2264ad6

rename more occurances of "promise" to "assert"

3855094

Update cl_khr_command_buffer_mutable_dispatch.asciidoc

50bfadb

Update cl_khr_command_buffer_mutable_dispatch.asciidoc

2eb8460

replace error with undefined behavior

add CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR

39bdaeb

fixing mix-up in enum values

df6029f

return errors in non-update APIs

65b173e

spaces

980a2dc

Co-authored-by: Sun Serega <sunserega2@gmail.com>

Update ext/cl_khr_command_buffer_mutable_dispatch.asciidoc

23777a3

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

update the formula for number of WGs

df7f849

Update xml/cl.xml

e89bf7f

Co-authored-by: Sun Serega <sunserega2@gmail.com>

Remove minor TODO comment (KhronosGroup#957) (KhronosGroup#988)

f648659

Delete obsolete comment in cl_khr_semaphore. Issue

move the layers spec to the extensions directory (KhronosGroup#999)

981ba95

Since the layers spec is not published in the OpenCL extension spec and is instead published on the OpenCL registry similar to EXT and vendor extensions, it makes more sense to put it in the extensions directory.

remove TODO comment in semaphore spec (KhronosGroup#1012)

a164c7f

The default behavior when the device handle list is not specified is now properly described, so the TODO comment can be removed.

document USM error conditions for clSetKernelExecInfo (KhronosGroup#974)

92e08ba

add description metadata (KhronosGroup#1000)

0cd45cb

consistently put newer versions at the bottom of version history tabl…

6134e8d

…es (KhronosGroup#1010)

Reserve enum for cl_ext_yuv_images (KhronosGroup#1022)

a40434d

Change-Id: I942c3ce47284e7aea93edc02cf0f327af95e4ed9

aharon-abramson added 2 commits July 16, 2025 13:32

Update opencl_runtime_layer.asciidoc and cl.xml to enhance command bu…

0d1a89c

…ffer error handling and state requirements

Merge branch 'issue_1329' of https://github.com/aharon-abramson/OpenC…

6b562be

…L-Docs into issue_1329

EwanC self-requested a review August 26, 2025 16:54

aharon-abramson added 3 commits August 27, 2025 13:54

Merge branch 'main' into issue_1329

35da0fd

remove Pending state form command buffer lifecycle

242c1f8

Merge remote-tracking branch 'upstream/main' into issue_1329

5545a13

EwanC reviewed Aug 28, 2025

View reviewed changes

images/commandbuffer_lifecycle.png Show resolved Hide resolved

xml/cl.xml Outdated Show resolved Hide resolved

api/opencl_runtime_layer.asciidoc Show resolved Hide resolved

move CL_COMMAND_BUFFER_STATE_FINALIZED_KHR to cl_khr_command_buffer_m…

76c535f

…utable_dispatch

EwanC approved these changes Aug 29, 2025

View reviewed changes

api/opencl_runtime_layer.asciidoc Outdated Show resolved Hide resolved

api/opencl_runtime_layer.asciidoc Outdated Show resolved Hide resolved

aharon-abramson and others added 2 commits August 31, 2025 08:59

Update api/opencl_runtime_layer.asciidoc

dbb800d

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

Update api/opencl_runtime_layer.asciidoc

f9ae37e

Co-authored-by: Ewan Crawford <ewan.cr@gmail.com>

kpet approved these changes Sep 2, 2025

View reviewed changes

bashbaug merged commit 4648526 into KhronosGroup:main Sep 9, 2025
2 checks passed

aharon-abramson mentioned this pull request Sep 11, 2025

add a test case for setting kernel arguments before recording it in command buffer KhronosGroup/OpenCL-CTS#2520

Closed

bashbaug mentioned this pull request Sep 11, 2025

regenerate headers with the latest XML file KhronosGroup/OpenCL-Headers#292

Merged

EwanC mentioned this pull request Oct 7, 2025

Fixup command-buffer enqueue error after PR-1382 #1471

Merged

EwanC mentioned this pull request Oct 7, 2025

Test mutable command-buffer deferred kernel arguments KhronosGroup/OpenCL-CTS#2538

Merged

Conversation

aharon-abramson commented Jun 3, 2025

Uh oh!

joselopeqti commented Jul 22, 2025

Uh oh!

aharon-abramson commented Jul 22, 2025

Uh oh!

EwanC commented Aug 26, 2025

Uh oh!

EwanC left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EwanC left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kpet left a comment

Choose a reason for hiding this comment

Uh oh!

joselopeqti commented Sep 4, 2025

Uh oh!

EwanC commented Sep 5, 2025

Uh oh!

bashbaug commented Sep 5, 2025

Uh oh!

bashbaug commented Sep 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants