From 3042bc1f48c3485024dd435a15e0a9f91dd5dbf4 Mon Sep 17 00:00:00 2001
From: Nikhil Joshi <nikhilj@nvidia.com>
Date: Tue, 21 May 2024 21:43:39 +0530
Subject: [PATCH] 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
---
 api/cl_khr_external_memory_win32.asciidoc |  1 +
 api/opencl_runtime_layer.asciidoc         | 19 +++++++++++++++++++
 xml/cl.xml                                |  4 +++-
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc
index 005c9278..57d01246 100644
--- a/api/cl_khr_external_memory_win32.asciidoc
+++ b/api/cl_khr_external_memory_win32.asciidoc
@@ -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
 
diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
index bfa16ffd..0c499514 100644
--- a/api/opencl_runtime_layer.asciidoc
+++ b/api/opencl_runtime_layer.asciidoc
@@ -5619,6 +5619,14 @@ buffer or an image memory object from an external handle:
     represented by its memory object, and will therefore become invalid when
     all memory objects associated with it are destroyed.
 endif::cl_khr_external_memory_win32[]
+  * {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.
+    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.
 
 For these extensions, importing memory object payloads from Windows handles
 does not transfer ownership of the handle to the OpenCL implementation.
@@ -13127,6 +13135,13 @@ 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.
+    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[]
 
@@ -13146,6 +13161,10 @@ 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
     | Temporary, Permanent
+
+include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_NAME_KHR.asciidoc[]
+  | Reference
+    | Temporary, Permanent
 endif::cl_khr_external_semaphore_win32[]
 |====
 
diff --git a/xml/cl.xml b/xml/cl.xml
index 7700355a..61dac57d 100644
--- a/xml/cl.xml
+++ b/xml/cl.xml
@@ -1894,7 +1894,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.">