minor semaphore external sharing fixes (#712)

bashbaug · web-flow · commit 8cf694a7377b · 2021-11-16T17:04:07.000Z
* use common wording for enqueue commands
fix a few missing asciidoctor attributes

* add a footnote clarifying usage of the semaphore reference count

* add the semaphore and external sharing extensions to the quick reference table

* fix italics in the error conditions for clGetSemaphoreInfoKHR

* fix the API suffix macros for all semaphore APIs

* re-alphabetize footnotes

* try to clarify when semaphore waits and signals are complete

* remove duplicated word
diff --git a/OpenCL_Ext.txt b/OpenCL_Ext.txt
@@ -29,8 +29,17 @@ include::config/opencl.asciidoc[]
 // Formatting and links for API functions and enums.
 include::ext/dictionary.asciidoc[]
 
+// External Footnotes
+// The extension spec will have access to all API and C footnotes.
+include::api/footnotes.asciidoc[]
+include::c/footnotes.asciidoc[]
+
+<<<<
+
 include::copyrights.txt[]
 
+<<<
+
 include::ext/introduction.asciidoc[]
 
 include::ext/cl_khr_icd.asciidoc[]
diff --git a/api/footnotes.asciidoc b/api/footnotes.asciidoc
@@ -138,6 +138,10 @@ It is unsuitable for general use in applications. \
 This feature is provided for identifying memory leaks. \
 ]
 
+:fn-setkernelarg-prefer-unset-on-error: pass:n[ \
+Implementations are encouraged to favor this option as it makes it more likely that errors will be managed by applications. \
+]
+
 :fn-srgb-image-requirements: pass:n[ \
 Support for reading from the {CL_sRGBA} image channel order is optional for 1D image buffers. \
 Support for writing to the {CL_sRGBA} image channel order is optional for all image types. \
@@ -162,7 +166,3 @@ Only once the ID has been allotted may it be exposed to OpenCL by proposing a me
 The merge must define a new enumerant by adding an `<enum>` tag to the {cl_khronos_vendor_id_TYPE} `<enums>` tag, with the `<value>` attribute set as the acquired Khronos vendor ID. \
 The `<name>` attribute must identify the vendor/adopter, and be of the form `CL_KHRONOS_VENDOR_ID_<vendor>`. \
 ]
-
-:fn-setkernelarg-prefer-unset-on-error: pass:n[ \
-Implementations are encouraged to favor this option as it makes it more likely that errors will be managed by applications. \
-]
diff --git a/ext/cl_khr_external_memory.asciidoc b/ext/cl_khr_external_memory.asciidoc
@@ -249,7 +249,7 @@ The following new APIs are added as part of this spec. The details of each are d
 
 ==== Acquiring and Releasing External Memory Objects
 
-To acquire OpenCL memory objects created from external memory handles, call the function
+To enqueue a command to acquire OpenCL memory objects created from external memory handles, call the function
 
 include::{generated}/api/protos/clEnqueueAcquireExternalMemObjectsKHR.txt[]
 
@@ -296,7 +296,7 @@ Otherwise, it returns one of the following errors:
 * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device.
 * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
 
-To release OpenCL memory objects created from external memory handles, call the function
+To enqueue a command to release OpenCL memory objects created from external memory handles, call the function
 
 include::{generated}/api/protos/clEnqueueReleaseExternalMemObjectsKHR.txt[]
 
diff --git a/ext/cl_khr_external_semaphore.asciidoc b/ext/cl_khr_external_semaphore.asciidoc
@@ -420,11 +420,11 @@ The `cl_khr_external_semaphore_dx_fence` extension extends {cl_external_semaphor
 When waiting on semaphores using {clEnqueueWaitSemaphoresKHR} or signaling semaphores using {clEnqueueSignalSemaphoresKHR}, the semaphore payload must be provided for semaphores created from {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR}.
 
 
-* If _sema_objects_ list has a mix of cl_semaphore obtained from *CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR* and other handle types,
+* If _sema_objects_ list has a mix of cl_semaphore obtained from {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} and other handle types,
 then the _sema_payload_list_ should point to a list of _num_sema_objects_ payload values for each cl_semaphore in _sema_objects_. 
-However, the payload values corresponding to semaphores with type CL_SEMAPHORE_TYPE_BINARY_KHR can be set to 0 or will be ignored.
+However, the payload values corresponding to semaphores with type {CL_SEMAPHORE_TYPE_BINARY_KHR} can be set to 0 or will be ignored.
 
-*clEnqueueWaitSemaphoresKHR* and *clEnqueueSignalSemaphoresKHR* may return *CL_INVALID_VALUE* if _sema_objects_ list has one or more cl_semaphore obtained from *CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR* and _sema_payload_list_ is NULL.
+{clEnqueueWaitSemaphoresKHR} and {clEnqueueSignalSemaphoresKHR} may return {CL_INVALID_VALUE} if _sema_objects_ list has one or more cl_semaphore obtained from {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} and _sema_payload_list_ is NULL.
 
 
 
diff --git a/ext/cl_khr_semaphore.asciidoc b/ext/cl_khr_semaphore.asciidoc
@@ -281,7 +281,7 @@ Otherwise, it returns a `NULL` value with one of the following error values retu
 
 ==== Waiting on and signaling semaphores
 
-To wait on a set of semaphores, call the function
+To enqueue a command to wait on a set of semaphores, call the function
 
 include::{generated}/api/protos/clEnqueueWaitSemaphoresKHR.txt[]
 
@@ -307,6 +307,8 @@ The context associated with events in _event_wait_list_ and that associated with
 _event_ returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete.
 _event_ can be `NULL` in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
 
+The semaphore wait command waits for a list of events to complete and a list of semaphore objects to become signaled.
+The semaphore wait command returns an _event_ which can be waited on to ensure that all events in the _event_wait_list_ have completed and all semaphores in _sema_objects_ have been signaled.
 The successful completion of the event generated by {clEnqueueWaitSemaphoresKHR} called on one or more semaphore objects of type {CL_SEMAPHORE_TYPE_BINARY_KHR} leads to un-signaling the corresponding semaphore objects and the state of these semaphore objects will be reset. Any subsequent {clEnqueueWaitSemaphoresKHR} operation on these semaphores without a pending {clEnqueueSignalSemaphoresKHR} may lead to implementation-defined behavior.
 
 {clEnqueueWaitSemaphoresKHR} returns {CL_SUCCESS} if the function is executed successfully.
@@ -329,7 +331,7 @@ Otherwise, it returns one of the following errors:
 * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device.
 * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
 
-To signal a set of semaphores, call the function
+To enqueue a command to signal a set of semaphores, call the function
 
 include::{generated}/api/protos/clEnqueueSignalSemaphoresKHR.txt[]
 
@@ -357,7 +359,9 @@ _event_ returns an event object that identifies this particular command and can
 _event_ can be `NULL` in which case it will not be possible for the application to query the status of this command
 or queue a wait for this command to complete.
 
-The successful completion of event generated by {clEnqueueSignalSemaphoresKHR} called on one or more semaphore objects of type {CL_SEMAPHORE_TYPE_BINARY_KHR} changes the state of the corresponding semaphore objects to signaled. Any subsequent {clEnqueueSignalSemaphoresKHR} operation on these semaphores without a pending {clEnqueueWaitSemaphoresKHR} may lead to implementation-defined behavior.
+The semaphore signal command waits for a list of events to complete and then signals a list of semaphore objects.
+The semaphore signal command returns an _event_ which can be waited on to ensure that all events in the _event_wait_list_ have completed and all semaphores in _sema_objects_ have been signaled.
+The successful completion of the event generated by {clEnqueueSignalSemaphoresKHR} called on one or more semaphore objects of type {CL_SEMAPHORE_TYPE_BINARY_KHR} changes the state of the corresponding semaphore objects to signaled. Any subsequent {clEnqueueSignalSemaphoresKHR} operation on these semaphores without a pending {clEnqueueWaitSemaphoresKHR} may lead to implementation-defined behavior.
 
 {clEnqueueSignalSemaphoresKHR} returns {CL_SUCCESS} if the function is executed successfully.
 Otherwise, it returns one of the following errors:
@@ -405,7 +409,7 @@ being queried by _param_value_. If _param_value_size_ret_ is `NULL`, it is ignor
   | {cl_context_TYPE}
       | Returns the context specified when the semaphore is created.
 
-| {CL_SEMAPHORE_REFERENCE_COUNT_KHR}
+| {CL_SEMAPHORE_REFERENCE_COUNT_KHR} footnote:[{fn-reference-count-usage}]
   | {cl_uint_TYPE}
       | Returns the semaphore reference count.
 
@@ -440,7 +444,7 @@ Otherwise, it returns one of the following errors:
 ** if _sema_object_ is not a valid semaphore
 * {CL_INVALID_VALUE}
 ** if _param_name_ is not one of the attribute defined in table <<cl_khr_semaphore_info-table>> or
-** if _param_value_size is less than the size of Return Type of the corresponding _param_name_ attribute as defined in table <<cl_khr_semaphore_info-table>>.
+** if _param_value_size_ is less than the size of Return Type of the corresponding _param_name_ attribute as defined in table <<cl_khr_semaphore_info-table>>.
 * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device.
 * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
 
diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc
@@ -73,6 +73,46 @@
 | Extend versioning of platform, devices, extensions, etc.
 | Extension
 
+| <<cl_khr_external_memory,cl_khr_external_memory>>
+| Common Functionality for External Memory Sharing
+| Provisional Extension
+
+| <<cl_khr_external_memory,cl_khr_external_memory_dma_buf>>
+| dma_buf External Memory Handles
+| Provisional Extension
+
+| <<cl_khr_external_memory,cl_khr_external_memory_dx>>
+| Direct3D 11 and 12 External Memory Handles
+| Provisional Extension
+
+| <<cl_khr_external_memory,cl_khr_external_memory_opaque_fd>>
+| Opaque File Descriptor External Memory Handles
+| Provisional Extension
+
+| <<cl_khr_external_memory,cl_khr_external_memory_win32>>
+| NT Handle External Memory Handles
+| Provisional Extension
+
+| <<cl_khr_external_semaphore,cl_khr_external_semaphore>>
+| Common Functionality for External Semaphore Sharing
+| Provisional Extension
+
+| <<cl_khr_external_semaphore,cl_khr_external_semaphore_dx_fence>>
+| Direct3D 12 External Semaphore Handles
+| Provisional Extension
+
+| <<cl_khr_external_semaphore,cl_khr_external_semaphore_opaque_fd>>
+| Opaque File Descriptor External Semaphore Handles
+| Provisional Extension
+
+| <<cl_khr_external_semaphore,cl_khr_external_semaphore_sync_fd>>
+| Sync FD External Semaphore Handles
+| Provisional Extension
+
+| <<cl_khr_external_semaphore,cl_khr_external_memory_win32>>
+| NT Handle External Semaphore Handles
+| Provisional Extension
+
 | <<cl_khr_fp16,cl_khr_fp16>>
 | Operations on 16-bit Floating-Point Values
 | Extension
@@ -161,6 +201,10 @@
 | Set the Current Kernel Rounding Mode
 | DEPRECATED
 
+| <<cl_khr_semaphore,cl_khr_semaphore>>
+| Semaphore Synchronization Primitives
+| Provisional Extension
+
 | <<cl_khr_spir,cl_khr_spir>>
 | Standard Portable Intermediate Representation Programs
 | Extension, Superseded by IL Programs / SPIR-V
diff --git a/xml/cl.xml b/xml/cl.xml
@@ -2439,13 +2439,13 @@ server's OpenCL/api-docs repository.
             <param>const <type>size_t</type>*              <name>global_work_size</name></param>
             <param><type>size_t</type>*                    <name>suggested_local_work_size</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_semaphore_khr</type>           <name>clCreateSemaphoreWithPropertiesKHR</name></proto>
             <param><type>cl_context</type>                 <name>context</name></param>
             <param>const <type>cl_semaphore_properties_khr</type>* <name>sema_props</name></param>
             <param><type>cl_int</type>*                    <name>errcode_ret</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clEnqueueWaitSemaphoresKHR</name></proto>
             <param><type>cl_command_queue</type>           <name>command_queue</name></param>
             <param><type>cl_uint</type>                    <name>num_sema_objects</name></param>
@@ -2455,7 +2455,7 @@ server's OpenCL/api-docs repository.
             <param>const <type>cl_event</type>*            <name>event_wait_list</name></param>
             <param><type>cl_event</type>*                  <name>event</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clEnqueueSignalSemaphoresKHR</name></proto>
             <param><type>cl_command_queue</type>           <name>command_queue</name></param>
             <param><type>cl_uint</type>                    <name>num_sema_objects</name></param>
@@ -2465,23 +2465,23 @@ server's OpenCL/api-docs repository.
             <param>const <type>cl_event</type>*            <name>event_wait_list</name></param>
             <param><type>cl_event</type>*                  <name>event</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clGetSemaphoreInfoKHR</name></proto>
             <param><type>cl_semaphore_khr</type>           <name>sema_object</name></param>
             <param><type>cl_semaphore_info_khr</type>      <name>param_name</name></param>
             <param><type>size_t</type>                     <name>param_value_size</name></param>
             <param><type>void</type>*                      <name>param_value</name></param>
             <param><type>size_t</type>*                    <name>param_value_size_ret</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clReleaseSemaphoreKHR</name></proto>
             <param><type>cl_semaphore_khr</type>           <name>sema_object</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clRetainSemaphoreKHR</name></proto>
             <param><type>cl_semaphore_khr</type>           <name>sema_object</name></param>
         </command>
-        <command suffix="CL_API_SUFFIX__VERSION_3_0">
+        <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_int</type>                     <name>clGetSemaphoreHandleForTypeKHR</name></proto>
             <param><type>cl_semaphore_khr</type>           <name>sema_object</name></param>
             <param><type>cl_device_id</type>               <name>device</name></param>
