Extension of cl_khr_icd to 2.0.0 with loader managed dispatch.

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
+    2024-09-04
 *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,18 @@ 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`
+
+Used as a parameter name to query if a platform can be unlaoded by the ICD
+Loader:
+
+  * {CL_PLATFORM_UNLOADABLE_KHR}
+
 === Issues
 
   . Some OpenCL functions do not take an object argument from which their
@@ -286,9 +328,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, 2024-09-04
+  ** 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']
@@ -300,6 +337,11 @@ include::{generated}/api/version-notes/CL_PLATFORM_ICD_SUFFIX_KHR.asciidoc[]
   | {char_TYPE}[]
     | The function name suffix used to identify extension functions to be
       directed to this platform by the ICD Loader.
+| {CL_PLATFORM_UNLOADABLE_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_PLATFORM_UNLOADABLE_KHR.asciidoc[]
+  | {cl_bool_TYPE}
+    | The platform can be unloaded by the ICD Loader.
 endif::cl_khr_icd[]
 |====
 

extensions/cl_loader_layers.asciidoc

@@ -21,6 +21,7 @@ interception layers (Layer ICDs) for OpenCL.
 |====
 | *Date*     | *Version* | *Description*
 | 2020-11-04 | 1.0.0     | First assigned version.
+| 2024-09-04 | 2.0.0     | Deinitialization support.
 |====
 
 ==== Contributors
@@ -45,6 +46,8 @@ cl_int clInitLayer(cl_uint                 num_entries,
                    const cl_icd_dispatch  *target_dispatch,
                    cl_uint                *num_entries_ret,
                    const cl_icd_dispatch **layer_dispatch_ret);
+
+cl_int clDeinitLayer(void);
 ----
 
 [[cl_loader_layers-new-api-types]]
@@ -72,12 +75,13 @@ Accepted as _param_name_ to the function *clGetLayerInfo*:
 === New API Tokens
 
 Returned by *clGetLayerInfo* when supplied *CL_LAYER_API_VERSION*
-and the corresponding layer implements version 1.0.0 of the layer
-API:
+and the corresponding layer implements version 1.0.0 or 2.0.0 of
+the layer API:
 
 [source,opencl]
 ----
 #define CL_LAYER_API_VERSION_100 100
+#define CL_LAYER_API_VERSION_200 200
 ----
 
 [[cl_loader_layers-new-environment-variables]]
@@ -173,6 +177,18 @@ Otherwise, it returns one of the following errors.
     _target_dispatch_ is a `NULL` value, or _num_entries_ret_ is a `NULL`
     value, or _layer_dispatch_ret_ is a `NULL` value.
 
+==== Layer Deinitialization
+
+[open,refpage='clDeinitLayer',desc='Deinitialize an OpenCL layer',type='protos']
+Deinitilization of a layer can be achieved with the function:
+[source,opencl]
+
+----
+cl_int clInitLayer(void);
+----
+
+*clDeinitLayer* returns *CL_SUCCESS* if the function is executed successfully.
+
 [[cl_loader_layers-source-code]]
 === Source Code
 

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

@@ -382,6 +382,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. -->
@@ -513,6 +522,7 @@ server's OpenCL/api-docs repository.
 
     <enums name="Constants.cl_loader_layers" vendor="Khronos" comment="Defined Layer API version, in cl_layer.h">
         <enum value="100"           name="CL_LAYER_API_VERSION_100"/>
+        <enum value="200"           name="CL_LAYER_API_VERSION_200"/>
     </enums>
 
     <enums start="0" end="-999" name="ErrorCodes.0" vendor="Khronos" comment="Error codes start at 0 and decrease">
@@ -1413,7 +1423,8 @@ server's OpenCL/api-docs repository.
         <enum value="0x0908"        name="CL_PLATFORM_COMMAND_BUFFER_CAPABILITIES_KHR"/>
             <unused start="0x0909" end="0x091F" comment="Reserved to Khronos"/>
         <enum value="0x0920"        name="CL_PLATFORM_ICD_SUFFIX_KHR"/>
-            <unused start="0x0921" end="0x09FF" comment="Vendor extensions"/>
+        <enum value="0x0921"        name="CL_PLATFORM_UNLOADABLE_KHR"/>
+            <unused start="0x0922" end="0x09FF" comment="Vendor extensions"/>
     </enums>
 
     <enums start="0x1000" end="0x107F" name="cl_device_info" vendor="Khronos">
@@ -2558,6 +2569,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>
@@ -4227,6 +4248,9 @@ server's OpenCL/api-docs repository.
             <param><type>cl_uint</type>*                                <name>num_entries_ret</name></param>
             <param>const <type>cl_icd_dispatch</type>**                 <name>layer_dispatch_ret</name></param>
         </command>
+        <command>
+            <proto><type>cl_int</type>                                  <name>clDeinitLayer</name></proto>
+        </command>
         <command>
             <proto><type>cl_int</type>                                  <name>clGetICDLoaderInfoOCLICD</name></proto>
             <param><type>cl_icdl_info</type>                            <name>param_name</name></param>
@@ -5600,21 +5624,27 @@ 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>
             <require comment="cl_platform_info">
                 <enum name="CL_PLATFORM_ICD_SUFFIX_KHR"/>
+                <enum name="CL_PLATFORM_UNLOADABLE_KHR"/>
             </require>
             <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">
+        <extension name="cl_loader_layers" revision="2.0.0" supported="opencl">
             <require>
                 <type name="CL/cl_icd.h"/>
             </require>
@@ -5628,10 +5658,12 @@ server's OpenCL/api-docs repository.
             </require>
             <require comment="Misc API enums">
                 <enum name="CL_LAYER_API_VERSION_100"/>
+                <enum name="CL_LAYER_API_VERSION_200"/>
             </require>
             <require>
                 <command name="clGetLayerInfo"/>
                 <command name="clInitLayer"/>
+                <command name="clDeinitLayer"/>
             </require>
         </extension>
         <extension name="cl_loader_info" revision="1.0.0" supported="opencl">