From e5ce3983b81e8531cd5f189ae21dd41b7dae9a2f Mon Sep 17 00:00:00 2001
From: Kevin Petit <kevin.petit@arm.com>
Date: Tue, 3 Sep 2024 18:55:28 +0100
Subject: [PATCH] Add error when memory objects or semaphores are created with
 more than one external handle

Also link the description of external semaphore handles to the spec
for clCreateSemaphoreWithPropertiesKHR.

Fixes #1246

Signed-off-by: Kevin Petit <kevin.petit@arm.com>
Change-Id: Ifb4c02795c6d4db8aee9b5f14b10fecd26992fd5
---
 api/cl_khr_external_memory.asciidoc    |  5 ++++-
 api/cl_khr_external_semaphore.asciidoc |  5 ++++-
 api/opencl_runtime_layer.asciidoc      | 11 +++++++++++
 xml/cl.xml                             |  4 ++--
 4 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc
index 3d61b564a..27a9c160f 100644
--- a/api/cl_khr_external_memory.asciidoc
+++ b/api/cl_khr_external_memory.asciidoc
@@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory.txt[]
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2024-03-15
+    2024-09-03
 *IP Status*::
     No known IP claims.
 *Contributors*::
@@ -290,3 +290,6 @@ while (true) {
      (provisional).
   * Revision 1.0.0, 2024-03-15
   ** First non-provisional version.
+  * Revision 1.1.0, 2024-09-03
+  ** Return {CL_INVALID_PROPERTY} when multiple external handles are provided
+     when creating a memory object.
diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc
index 1bbf56796..f95d4fcee 100644
--- a/api/cl_khr_external_semaphore.asciidoc
+++ b/api/cl_khr_external_semaphore.asciidoc
@@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore.txt[]
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2024-03-15
+    2024-09-03
 *Interactions and External Dependencies*::
   * This extension requires OpenCL 1.2.
   * The {cl_khr_semaphore_EXT} extension is required as it defines semaphore
@@ -283,3 +283,6 @@ while (true) {
   ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT}
   * Revision 1.0.0, 2024-03-15
   ** First non-provisional version.
+  * Revision 1.1.0, 2024-09-03
+  ** Return {CL_INVALID_PROPERTY} when multiple external handles are provided
+     when creating a semaphore.
diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc
index feb7c88cc..8739ccee8 100644
--- a/api/opencl_runtime_layer.asciidoc
+++ b/api/opencl_runtime_layer.asciidoc
@@ -659,6 +659,7 @@ ifdef::cl_khr_external_memory[]
   * {CL_INVALID_PROPERTY}
   ** if _properties_ does not include a supported external memory handle and
      {CL_MEM_DEVICE_HANDLE_LIST_KHR} is specified as part of _properties_.
+  ** if _properties_ includes more than one external memory handle.
 endif::cl_khr_external_memory[]
 
 [[memory-flags-table]]
@@ -2118,6 +2119,7 @@ ifdef::cl_khr_external_memory[]
   * {CL_INVALID_PROPERTY}
   ** if _properties_ does not include a supported external memory handle and
      {CL_MEM_DEVICE_HANDLE_LIST_KHR} is specified as part of _properties_.
+  ** if _properties_ includes more than one external memory handle.
 endif::cl_khr_external_memory[]
 
 [[host-ptr-buffer-size-table]]
@@ -12881,6 +12883,12 @@ in the _context_.
 For a multi-device context {CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR} must be
 specified in _sema_props_.
 
+ifdef::cl_khr_external_semaphore[]
+The properties used to create a semaphore from an external semaphore handle are
+<<external-semaphore-handle-types, described for the corresponding
+extensions>>.
+endif::cl_khr_external_semaphore[]
+
 // refError
 
 _errcode_ret_ returns an appropriate error code.
@@ -12926,6 +12934,8 @@ ifdef::cl_khr_external_semaphore[]
     well as {CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR}. Exporting a semaphore
     handle from a semaphore that was created by importing an external
     semaphore handle is not permitted.
+  * {CL_INVALID_PROPERTY} if _sema_props_ includes more than one external
+    semaphore handle.
 endif::cl_khr_external_semaphore[]
 --
 
@@ -13007,6 +13017,7 @@ Please refer to handle specific documentation for more details on transference r
 handle type.
 
 
+[[external-semaphore-handle-types]]
 === Descriptions of External Semaphore Handle Types
 
 This section describes the external semaphore handle types that are added by
diff --git a/xml/cl.xml b/xml/cl.xml
index 8dc46339c..ec1f537c2 100644
--- a/xml/cl.xml
+++ b/xml/cl.xml
@@ -7027,7 +7027,7 @@ server's OpenCL/api-docs repository.
                 <command name="clRetainSemaphoreKHR"/>
             </require>
         </extension>
-        <extension name="cl_khr_external_semaphore" revision="1.0.0" supported="opencl" depends="CL_VERSION_1_2+cl_khr_semaphore" ratified="opencl">
+        <extension name="cl_khr_external_semaphore" revision="1.1.0" supported="opencl" depends="CL_VERSION_1_2+cl_khr_semaphore" ratified="opencl">
             <require>
                 <type name="CL/cl.h"/>
             </require>
@@ -7086,7 +7086,7 @@ server's OpenCL/api-docs repository.
                 <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">
+        <extension name="cl_khr_external_memory" revision="1.1.0" supported="opencl" depends="CL_VERSION_3_0" ratified="opencl">
             <require>
                 <type name="CL/cl.h"/>
             </require>