From 8a3b4c7c2e930c5dae2493fb39fc412d77a7e44a Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Thu, 21 Nov 2024 11:44:58 +0000 Subject: [PATCH] cl_khr_command_buffer sync-point capacity Document the behaviour when command-buffer command capacity is reached, and track under "Issues" the possible future use-cases for being able to optimize based on the capacity of a command-buffer. Closes https://github.com/KhronosGroup/OpenCL-Docs/issues/844 --- api/cl_khr_command_buffer.asciidoc | 45 +++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index a97e067d..27caada7 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -43,16 +43,6 @@ Command-buffers enable a reduction in overhead when enqueuing the same workload multiple times. By separating the command-queue setup from dispatch, the ability to replay a set of previously created commands is introduced. -Device-side _cl_sync_point_khr_ synchronization-points can be used within -command-buffers to define command dependencies. This allows the commands of a -command-buffer to execute out-of-order on a single <> -command-queue. The command-buffer itself has no inherent in-order/out-of-order -property, this ordering is inferred from the command-queue used on command -recording. Out-of-order enqueues without event dependencies of both regular -commands, such as {clEnqueueFillBuffer}, and command-buffers are allowed to -execute concurrently, and it is up to the user to express any dependencies using -events. - The command-queues a command-buffer will be executed on can be set on replay via parameters to {clEnqueueCommandBufferKHR}, provided they are <> with the command-queues used on command-buffer @@ -110,6 +100,28 @@ following reasons: other extensions layered on top to take advantage of them to provide additional mutable functionality. +==== Command Synchronization + +Device-side {cl_sync_point_khr_TYPE} synchronization-points can be used within +command-buffers to define command dependencies. This allows the commands of a +command-buffer to execute out-of-order on a single <> +command-queue. The command-buffer itself has no inherent in-order/out-of-order +property, this ordering is inferred from the command-queue used on command +recording. Out-of-order enqueues without event dependencies of both regular +commands, such as {clEnqueueFillBuffer}, and command-buffers are allowed to +execute concurrently, and it is up to the user to express any dependencies using +events. + +The {cl_sync_point_khr_TYPE} type is defined as a `cl_uint`, giving a hard +upper limit on the number of commands a command-buffer can hold as +{CL_UINT_MAX}, at which point {CL_OUT_OF_RESOURCES} will be returned. However, +it is likely an implementation will reach capacity before this threshold is +hit. + +There are no gurantees made around the values of sync-points returned from +adding commands to a command-buffer. Any semantics that a could be inferred +from the sync-point values returned is implementation defined. + ==== Simultaneous Use The optional simultaneous use capability was added to the extension so that @@ -420,6 +432,19 @@ features: -- *UNRESOLVED* -- +. Give users more control over command-buffer command capacity via some or all + of the following mechanisms. + ** Provide a way for a user to query a command-buffer for the maximum number + of commands it can hold. + ** Guarantee a minimum command capacity that an implementation must support. + ** Provide a mechanism for users to reserve command-buffer capacity on + command-buffer creation. + ++ +-- +*RESOLVED* - Mechanisms to achieve this could be provided as a layered extension. +-- + === Version History