Clarify Acquire/Release behavior for external memory (#1176)

* Clarify Acquire/Release behavior for external memory

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

* Updates to Acquire/Release clarifications (#1183)

Address review comments on PR#1176

Fixes #1078, #1086

* Address left-over comments (#1194)

Address some of the comments that were
left out in earlier update.

* Fix the typo for "acquired"

Fix the typo suggested by Kevin to replace aquired to acquired.

Co-authored-by: Kévin Petit <kevin.petit@arm.com>

---------

Co-authored-by: Kévin Petit <kevin.petit@arm.com>

api/opencl_runtime_layer.asciidoc

@@ -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 a memory object 
+    multiple times without releasing it results 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 for 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 acquired for 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.
 
@@ -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 a memory object 
+    multiple times without acquiring it results 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 release can be performed on a command-queue associated with
+    any device in the context.
+  * The memory object will be released for 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 for 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.