Add mechanism to specify named win32 NT handles (#1177)

* Add mechanism to specify named win32 NT handles Currently, cl_khr_external_semaphore and cl_khr_external_memory define properties to specify external win32 NT handle via pointer. Win32 NT handles can also be specified via named strings. Add properties to specify external Win32 NT handles via named strings too. Fixes #943 * Updates to win32 named handle type changes. (#1180) Address review comments. Fixes #943 * Drop NULL from named win32 handle description (#1187) * Updates to win32 named handle type changes. Address review comments. Fixes #943 * Drop NULL from named win32 handle description. Address review comments from Ben to remove NULL from named win32 handle description. Fixes #943 * Bump up spec versions for win32 (#1193) Bump up spec versions for cl_khr_external_memory_win32 from 1.0.0 to 1.1.0 and cl_khr_external_semaphore_win32 from 0.9.0 to 0.9.1 * fix typo and add OPAQUE_WIN32_NAME_KHR to semaphore enums list * Update opencl_runtime_layer.asciidoc Fix typo during conflict resolution opencl_runtime_layer.asciidoc. --------- Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>
KhronosGroup · Sep 3, 2024 · d83f47b · d83f47b
1 parent 76bb598
commit d83f47b
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 5 deletions.
diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc
@@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_win32.txt[]
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2024-03-15
+    2024-06-11
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -40,6 +40,7 @@ image memory object.
   * {cl_external_memory_handle_type_khr_TYPE}
   ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR}
   ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR}
+  ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_NAME_KHR}
 
 === Version History
 
@@ -57,3 +58,6 @@ image memory object.
      (provisional).
   * Revision 1.0.0, 2024-03-15
   ** First non-provisional version.
+  * Revision 1.1.0, 2024-06-11
+  ** Added {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_NAME_KHR}.
+
diff --git a/api/cl_khr_external_semaphore_win32.asciidoc b/api/cl_khr_external_semaphore_win32.asciidoc
@@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_win32.txt[]
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2021-09-10
+    2024-06-11
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -39,8 +39,11 @@ introduced by {cl_khr_external_semaphore_EXT}.
   * {cl_external_semaphore_handle_type_khr_TYPE}
   ** {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR}
   ** {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR}
+  ** {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR}
 
 === Version History
 
   * Revision 0.9.0, 2021-09-10
   ** Initial version (provisional).
+  * Revision 0.9.1, 2024-06-11
+  ** Added {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR}.
diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
@@ -5666,6 +5666,16 @@ buffer or an image memory object from an external handle:
     It does not own a reference to the underlying memory resource
     represented by its memory object, and will therefore become invalid when
     all memory objects associated with it are destroyed.
+  * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_NAME_KHR_anchor} specifies an NT handle name that
+    has only limited valid usage outside of OpenCL and other compatible
+    APIs.
+    NT handle name is a null-terminated UTF-16 string naming the payload to import.
+    It must be compatible with the functions `DuplicateHandle`,
+    `CloseHandle`, `CompareObjectHandles`, `GetHandleInformation`, and
+    `SetHandleInformation`.
+    It owns a reference to the underlying memory resource represented by its
+    memory object.
+
 endif::cl_khr_external_memory_win32[]
 
 For these extensions, importing memory object payloads from Windows handles
@@ -13157,6 +13167,14 @@ a semaphore from an external handle:
     It does not own a reference to the underlying synchronization primitive
     represented by its semaphore object, and will therefore become invalid
     when all semaphore objects associated with it are destroyed.
+  * {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR} specifies an NT handle name that has
+    only limited valid usage outside of OpenCL and other compatible APIs.
+    NT handle name is a null-terminated UTF-16 string naming the payload to import.
+    It must be compatible with the functions `DuplicateHandle`,
+    `CloseHandle`, `CompareObjectHandles`, `GetHandleInformation`, and
+    `SetHandleInformation`.
+    It owns a reference to the underlying synchronization primitive
+    represented by its semaphore object.
 
 endif::cl_khr_external_semaphore_win32[]
 
@@ -13174,6 +13192,12 @@ include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR.asci
 
 include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR.asciidoc[]
   | Reference
+
+| {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR.asciidoc[]
+  | Reference
+
 endif::cl_khr_external_semaphore_win32[]
 |====
 

diff --git a/xml/cl.xml b/xml/cl.xml
@@ -1885,7 +1885,9 @@ server's OpenCL/api-docs repository.
         <enum value="0x2062"        name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR"/>
             <unused start="0x2063" end="0x2066" comment="Reserved to Khronos for interop"/>
         <enum value="0x2067"        name="CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR"/>
-            <unused start="0x2068" end="0x2FFF" comment="Reserved to Khronos for interop"/>
+        <enum value="0x2068"        name="CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR"/>
+        <enum value="0x2069"        name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_NAME_KHR"/>
+            <unused start="0x206A" end="0x2FFF" comment="Reserved to Khronos for interop"/>
     </enums>
 
     <enums start="0x3000" end="0x3FFF" name="enums.3000" vendor="Khronos" comment="Platform IDs. Allocate individually.">
@@ -7074,13 +7076,14 @@ server's OpenCL/api-docs repository.
                 <command name="clReImportSemaphoreSyncFdKHR"/>
             </require>
         </extension>
-        <extension name="cl_khr_external_semaphore_win32" revision="0.9.0" supported="opencl" depends="CL_VERSION_1_2+cl_khr_semaphore+cl_khr_external_semaphore" ratified="opencl" provisional="true">
+        <extension name="cl_khr_external_semaphore_win32" revision="0.9.1" supported="opencl" depends="CL_VERSION_1_2+cl_khr_semaphore+cl_khr_external_semaphore" ratified="opencl" provisional="true">
             <require>
                 <type name="CL/cl.h"/>
             </require>
             <require comment="cl_external_semaphore_handle_type_khr">
                 <enum name="CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR"/>
                 <enum name="CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR"/>
+                <enum name="CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR"/>
             </require>
         </extension>
         <extension name="cl_khr_external_memory" revision="1.0.0" supported="opencl" depends="CL_VERSION_3_0" ratified="opencl">
@@ -7126,13 +7129,14 @@ server's OpenCL/api-docs repository.
                 <enum name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_FD_KHR"/>
             </require>
         </extension>
-        <extension name="cl_khr_external_memory_win32" revision="1.0.0" supported="opencl" depends="CL_VERSION_3_0+cl_khr_external_memory" ratified="opencl">
+        <extension name="cl_khr_external_memory_win32" revision="1.1.0" supported="opencl" depends="CL_VERSION_3_0+cl_khr_external_memory" ratified="opencl">
             <require>
                 <type name="CL/cl.h"/>
             </require>
             <require comment="cl_external_memory_handle_type_khr">
                 <enum name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR"/>
                 <enum name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR"/>
+                <enum name="CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_NAME_KHR"/>
             </require>
         </extension>
         <extension name="cl_intel_sharing_format_query" revision="0.0.0" supported="opencl">