Extension of cl_khr_icd to 2.0.0 with loader managed dispatch. (KhronosGroup#1005)

* Extension of cl_khr_icd to 2.0.0 with loader managed dispatch.

* update last modified dates

---------

Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

Author: Kerilk

api/cl_khr_icd.asciidoc

@@ -9,7 +9,7 @@ include::{generated}/meta/{refprefix}cl_khr_icd.txt[]
 === Other Extension Metadata
 
 *Last Modified Date*::
-    2020-04-21
+    2025-04-01
 *IP Status*::
     No known IP claims.
 
@@ -48,6 +48,8 @@ An object is said to be ICD compatible if it is of the following structure:
 struct _cl_<object>
 {
     struct _cl_icd_dispatch *dispatch;
+    // Since version 2.0.0
+    void *dispatch_data;
     // ... remainder of internal data
 };
 ----
@@ -67,6 +69,13 @@ can be appended.
 Functions which do not have an argument from which the vendor implementation
 may be inferred have been deprecated and may be ignored.
 
+New in version 2.0.0, object that are ICD 2 compatible should also contain
+a `dispatch_data` field of type `void *` that the loader is free to modify
+for a platform through the {clIcdSetPlatformDispatchDataKHR} new API entry
+point. In order to distinguish ICD 1 and ICD 2 objects, the pointers to
+`clGetPlatformIDs` and `clUnloadCompiler` in the dispatch structure must be
+set to `CL_ICD2_TAG_KHR`. The vendor driver is responsible for propagating
+the `dispatch_data` value when returning objects to users.
 
 === ICD Data
 
@@ -230,10 +239,31 @@ value {CL_PLATFORM_ICD_SUFFIX_KHR}.
 If any of these steps fail, the ICD Loader will ignore the Vendor ICD and
 continue on to the next.
 
+New in version 2.0.0, the ICD Loader will also query the following functions
+from the library: {clIcdGetFunctionAddressForPlatformKHR} and
+{clIcdSetPlatformDispatchDataKHR}. If these two functions are present and the
+pointers to `clGetPlatformIDs` and `clUnloadCompiler` in the dispatch
+structure of a platform is set to `CL_ICD2_TAG_KHR` the platform will be
+deemed ICD 2 compatible and dispatch will be managed by the ICD Loader. If the
+`CL_ICD2_TAG_KHR` tag is present but one of the two functions above is
+missing or it the tag is present in only one of the pointers, the ICD Loader
+will ignore the Vendor ICD and continue on to the next.
+
+During initialization, after calling {clIcdGetPlatformIDsKHR} to query the
+available platforms, the ICD Loader will, for each ICD 2 compatible platform,
+query dispatchable entry points using {clIcdGetFunctionAddressForPlatformKHR}
+and then set the platform dispatch data using
+{clIcdSetPlatformDispatchDataKHR}.
+
 === New Commands
 
   * {clIcdGetPlatformIDsKHR}
 
+New in version 2.0.0:
+
+  * {clIcdGetFunctionAddressForPlatformKHR}
+  * {clIcdSetPlatformDispatchDataKHR}
+
 === New Enums
 
 Accepted as _param_name_ to the function {clGetPlatformInfo}:
@@ -244,6 +274,11 @@ Returned by {clGetPlatformIDs} when no platforms are found:
 
   * {CL_PLATFORM_NOT_FOUND_KHR}
 
+New in version 2.0.0, used as a value in the pointers to `clGetPlatformIDs`
+and `clUnloadCompiler` in the dispatch structure:
+
+  * `CL_ICD2_TAG_KHR`
+
 === Issues
 
   . Some OpenCL functions do not take an object argument from which their
@@ -286,9 +321,31 @@ obtaining the ICD dispatch table.
 On detecting a `NULL` object it will return one of the an invalid object
 error values (e.g. {CL_INVALID_DEVICE} corresponding to the object in
 question.
+--
+
+  . How will the ICD loader avoid calling entry points outside of the dispatch
+    table of old implementations, potentially causing segfaults?
++
+--
+*RESOLVED*: From versions 2.0.0 and above, the loader will be responsible for
+managing dispatch data information per platform. The content of the dispatch
+table is obtained through a dedicated entry point, and missing entry points are
+replaced by stubs that return {CL_INVALID_OPERATION}.
+--
+
+  . How will the ICD loader set the loader managed dispatch information in new
+    objects? Some of these objects may be created by extension functions that
+    the loader is unaware of.
++
+--
+*RESOLVED*: During initialization, the loader will set the platform dispatch
+information through a new entry point. The implementation will be responsible
+for propagating this information to new objects.
 --
 
 === Version History
 
   * Revision 1.0.0, 2020-04-21
   ** First assigned version.
+  * Revision 2.0.0, 2025-04-01
+  ** Loader managed dispatch.

api/opencl_platform_layer.asciidoc

@@ -84,6 +84,43 @@ Otherwise, it returns one of the following errors:
   * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _platforms_ is
     not `NULL` or if both _num_platforms_ and _platforms_ are `NULL`.
 --
+
+[open,refpage='clIcdGetFunctionAddressForPlatformKHR',desc='Query API entry points for a platform',type='protos']
+--
+The entry point of a given platform that is ICD 2 compatible can be obtained
+using the following function:
+
+include::{generated}/api/protos/clIcdGetFunctionAddressForPlatformKHR.txt[]
+include::{generated}/api/version-notes/clIcdGetFunctionAddressForPlatformKHR.asciidoc[]
+
+  * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
+  * _func_name_ name of an API entry point
+
+{clIcdGetFunctionAddressForPlatformKHR} returns the address of the API entry
+point named by _func_name_. The pointer returned should be cast to a function
+pointer type matching the API entry point as defined in the specification
+header file.
+
+A return value of `NULL` indicates that the specified function does not exist
+for _platform_, or _platform_ is not a valid platform for the implementation.
+--
+
+[open,refpage='clIcdSetPlatformDispatchDataKHR',desc='Set the dispatch data for a platform',type='protos']
+--
+The `dispatch_data` field of a platform can be set using the following function:
+
+include::{generated}/api/protos/clIcdSetPlatformDispatchDataKHR.txt[]
+include::{generated}/api/version-notes/clIcdSetPlatformDispatchDataKHR.asciidoc[]
+
+  * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
+  * _dispatch_data_ is the value to set the `dispatch_data` field of the
+    structure to
+
+{clIcdSetPlatformDispatchDataKHR} returns {CL_SUCCESS} if the function is
+executed successfully.
+It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform.
+--
+
 endif::cl_khr_icd[]
 
 [open,refpage='clGetPlatformInfo',desc='Query information about an OpenCL platform',type='protos']

scripts/gen_dictionaries.py

@@ -249,7 +249,7 @@ def GetFooter():
                 addLink = True
                 name = type.get('name')
             elif category == 'define':
-                if type.text and type.text.startswith("#define"):
+                if type.text and (type.text.startswith("#define") or type.text.strip().startswith("#if")):
                     continue
                 name = type.find('name').text
             else:

xml/cl.xml

@@ -383,6 +383,15 @@ server's OpenCL/api-docs repository.
             <member>const <type>size_t</type>*                             <name>global_work_size</name></member>
             <member>const <type>size_t</type>*                             <name>local_work_size</name></member>
         </type>
+
+        <type category="define" requires="stdint" name="CL_ICD2_TAG_KHR" comment="ICD 2 tag, in cl_ext.h">
+#if INTPTR_MAX == INT32_MAX
+#define CL_ICD2_TAG_KHR ((intptr_t)0x434C3331)
+#else
+#define CL_ICD2_TAG_KHR ((intptr_t)0x4F50454E434C3331)
+#endif
+        </type>
+
     </types>
 
     <!-- SECTION: OpenCL enumerant (token) definitions. -->
@@ -2573,6 +2582,16 @@ server's OpenCL/api-docs repository.
             <param><type>cl_platform_id</type>*            <name>platforms</name></param>
             <param><type>cl_uint</type>*                   <name>num_platforms</name></param>
         </command>
+        <command>
+            <proto><type>void</type>*                      <name>clIcdGetFunctionAddressForPlatformKHR</name></proto>
+            <param><type>cl_platform_id</type>             <name>platform</name></param>
+            <param>const <type>char</type>*                <name>func_name</name></param>
+        </command>
+        <command>
+            <proto><type>cl_int</type>                     <name>clIcdSetPlatformDispatchDataKHR</name></proto>
+            <param><type>cl_platform_id</type>             <name>platform</name></param>
+            <param><type>void</type>*                      <name>dispatch_data</name></param>
+        </command>
         <command suffix="CL_API_SUFFIX__VERSION_1_2">
             <proto><type>cl_program</type>                 <name>clCreateProgramWithILKHR</name></proto>
             <param><type>cl_context</type>                 <name>context</name></param>
@@ -5631,7 +5650,7 @@ server's OpenCL/api-docs repository.
                 <command name="clLogMessagesToStderrAPPLE"/>
             </require>
         </extension>
-        <extension name="cl_khr_icd" revision="1.0.0" supported="opencl" ratified="opencl">
+        <extension name="cl_khr_icd" revision="2.0.0" supported="opencl" ratified="opencl">
             <require>
                 <type name="CL/cl.h"/>
             </require>
@@ -5641,8 +5660,13 @@ server's OpenCL/api-docs repository.
             <require comment="Error codes">
                 <enum name="CL_PLATFORM_NOT_FOUND_KHR"/>
             </require>
+            <require comment="ICD 2 tag value">
+                <type name="CL_ICD2_TAG_KHR"/>
+            </require>
             <require>
                 <command name="clIcdGetPlatformIDsKHR"/>
+                <command name="clIcdGetFunctionAddressForPlatformKHR"/>
+                <command name="clIcdSetPlatformDispatchDataKHR"/>
             </require>
         </extension>
         <extension name="cl_loader_layers" revision="1.0.0" supported="opencl">