Skip to content

Commit

Permalink
Clarify Acquire/Release behavior for external memory
Browse files Browse the repository at this point in the history
Clarify Acquire/Release behavior for external memory specs
to call out the scope of operations as well as
the behavior in case of multiple acquire/release calls.

Fixes #1078, #1086
  • Loading branch information
nikhiljnv committed May 21, 2024
1 parent 0483627 commit 7304cf6
Showing 1 changed file with 34 additions and 0 deletions.
34 changes: 34 additions & 0 deletions api/opencl_runtime_layer.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -5427,6 +5427,23 @@ handle is used by an OpenCL command queued to a command-queue without being
acquired.
This is to guarantee that the state of the memory objects is up-to-date and
they are accessible to OpenCL.

The following restrictions shall apply -
* Each memory object must be acquired only once. Acquiring memory object
multiple times without releasing it may result in implementation defined
behavior.
* The acquire must be performed on a command-queue associated with a device
that was one of the devices specified via {CL_MEM_DEVICE_HANDLE_LIST_KHR}
when the memory object was imported using {clCreateBufferWithProperties} or
{clCreateImageWithProperties}. If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not
specified, the acquire can be performed on a command-queue associated with
any device in the context.
* The memory object will be acquired on all devices specified
via {CL_MEM_DEVICE_HANDLE_LIST_KHR} when the memory object was imported
using {clCreateBufferWithProperties} or {clCreateImageWithProperties}.
If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not specified, the memory objects
will be aquired on all devices in the context.

See <<cl_khr_external_memory-Sample-Code, "`Example with Acquire /
Release`">> for more details on how to use this API.

Expand Down Expand Up @@ -5503,6 +5520,23 @@ Applications must release the memory objects that are acquired using
commands in the other API.
This is to guarantee that the state of memory objects is up-to-date and they
are accessible to the other API.

The following restrictions shall apply -
* Each memory object must be released only once. Releasing memory object
multiple times without acquiring it may result in implementation defined
behavior.
* The release must be performed on a command-queue associated with a device
that was one of the devices specified via {CL_MEM_DEVICE_HANDLE_LIST_KHR}
when the memory object was imported using {clCreateBufferWithProperties} or
{clCreateImageWithProperties}. If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not
specified, the acquire can be performed on a command-queue associated with
any device in the context.
* The memory object will be released on all devices specified via
{CL_MEM_DEVICE_HANDLE_LIST_KHR} when the memory object was imported
using {clCreateBufferWithProperties} or {clCreateImageWithProperties}.
If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not specified, the memory object
will be released on all devices in the context.

See "`Example with Acquire / Release`" provided in
<<cl_khr_external_memory-Sample-Code>> for more details on how to use this
API.
Expand Down

0 comments on commit 7304cf6

Please sign in to comment.