Added instance platform specification.

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*::
-    2025-12-15
+    2026-02-09
 *IP Status*::
     No known IP claims.
 
@@ -255,6 +255,21 @@ query dispatchable entry points using {clIcdGetFunctionAddressForPlatformKHR}
 and then set the platform dispatch data using
 {clIcdSetPlatformDispatchDataKHR}.
 
+New in version 2.0.2, the ICD Loader will also query the following functions
+from the library: {clIcdCreateInstancePlatformKHR} and
+{clIcdDestroyInstancePlatformKHR}.  If these two functions are present and the
+library's platforms are ICD 2 compatible, these platforms will be deemed
+*instance compatible*. In this case, rather than using the platform directly,
+the ICD Loader will first create an instance platform and then query
+dispatchable entry points for this instance platform using
+{clIcdGetFunctionAddressForPlatformKHR} and then set the platform dispatch data
+using {clIcdSetPlatformDispatchDataKHR}. Devices returned by {clGetDeviceIDs}
+used on an instance platform will be instance devices.  This created instance
+platform will be destroyed during loader deinitialization unless legacy
+behavior is enabled. Each instance platform (and attached instance devices)
+must support having a different dispatch information set through
+{clIcdSetPlatformDispatchDataKHR}.
+
 === New Commands
 
   * {clIcdGetPlatformIDsKHR}
@@ -264,6 +279,11 @@ New in version 2.0.0:
   * {clIcdGetFunctionAddressForPlatformKHR}
   * {clIcdSetPlatformDispatchDataKHR}
 
+New in version 2.0.2:
+
+  * {clIcdCreateInstancePlatformKHR}
+  * {clIcdDestroyInstancePlatformKHR}
+
 === New Enums
 
 Accepted as _param_name_ to the function {clGetPlatformInfo}:
@@ -279,6 +299,11 @@ and {clUnloadCompiler} in the dispatch structure:
 
   * `CL_ICD2_TAG_KHR`
 
+New in version 2.0.2, accepted as terminator to the _properties_ list of
+{clIcdCreateInstancePlatformKHR}.
+
+  * {CL_INSTANCE_PLATFORM_PROPERTIES_LIST_END_KHR}
+
 === Issues
 
   . Some OpenCL functions do not take an object argument from which their
@@ -365,3 +390,5 @@ for propagating this information to new objects.
   ** Loader managed dispatch.
   * Revision 2.0.1, 2025-12-15
   ** Loader deinitialization.
+  * Revision 2.0.2, 2026-02-09
+  ** Instance platform support.

api/opencl_platform_layer.asciidoc

@@ -102,6 +102,7 @@ include::{generated}/api/protos/clIcdGetFunctionAddressForPlatformKHR.txt[]
 include::{generated}/api/version-notes/clIcdGetFunctionAddressForPlatformKHR.asciidoc[]
 
   * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
+    or by {clIcdCreateInstancePlatformKHR}
   * _func_name_ name of an API entry point
 
 {clIcdGetFunctionAddressForPlatformKHR} returns the address of the API entry
@@ -137,6 +138,57 @@ Otherwise, it returns one of the following errors:
     implementation on the host
 --
 
+[open,refpage='clIcdCreateInstancePlatformKHR',desc='Create an instance of a platform',type='protos']
+--
+An instance platform can be created by the ICD Loader by using the following
+function:
+
+include::{generated}/api/protos/clIcdCreateInstancePlatformKHR.txt[]
+include::{generated}/api/version-notes/clIcdCreateInstancePlatformKHR.asciidoc[]
+
+  * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
+
+  * _properties_ specifies a list of instance platform property names and their
+    corresponding values. Each property name is immediately followed by the
+    corresponding desired value. The list is terminated with
+    {CL_INSTANCE_PLATFORM_PROPERTIES_LIST_END_KHR_anchor}. No properties are
+    supported currently. _properties_ can be NULL, in which case all properties
+    take on their default values.
+
+  * _errcode_ret_ will return an appropriate error code as described below.
+    If _errcode_ret_ is `NULL`, no error code is returned.
+
+{clIcdCreateInstancePlatformKHR} returns a valid non-zero OpenCL platform object
+and _errcode_ret_ is set to {CL_SUCCESS} if the instance platform object is
+created successfully.
+Otherwise, it returns a `NULL` value with one of the following error values
+returned in _errcode_ret_:
+
+    * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform.
+    * {CL_INVALID_PROPERTY} if an instance platform property name in
+      _properties_ is not a supported property name, if the value specified for
+      a supported property name is not valid, or if the same property name is
+      specified more than once.
+    * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
+      required by the OpenCL implementation on the host.
+--
+
+[open,refpage='clIcdDestroyInstancePlatformKHR',desc='Destroy an instance of a platform',type='protos']
+--
+An instance platform can be destroyed by the ICD Loader by using the following
+function:
+
+include::{generated}/api/protos/clIcdDestroyInstancePlatformKHR.txt[]
+include::{generated}/api/version-notes/clIcdDestroyInstancePlatformKHR.asciidoc[]
+
+  * _platform_ refers to the instance platform object returned by
+    {clIcdCreateInstancePlatformKHR}
+
+{clIcdDestroyInstancePlatformKHR} returns {CL_SUCCESS} if the function is
+executed successfully.
+It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid instance platform.
+--
+
 endif::cl_khr_icd[]
 
 [open,refpage='clGetPlatformInfo',desc='Query information about an OpenCL platform',type='protos']

xml/cl.xml

@@ -228,6 +228,7 @@ server's OpenCL/api-docs repository.
         <type category="define">typedef <type>cl_properties</type>    <name>cl_layer_properties</name>;</type>
         <type category="define">typedef <type>cl_uint</type>          <name>cl_icdl_info</name>;</type>
         <type category="define">typedef struct _cl_icd_dispatch       <name>cl_icd_dispatch</name>;</type>
+        <type category="define">typedef <type>cl_properties</type>    <name>cl_instance_platform_properties_khr</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_scheduling_controls_capabilities_img</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_scheduling_controls_capabilities_arm</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_controlled_termination_capabilities_arm</name>;</type>
@@ -815,6 +816,7 @@ server's OpenCL/api-docs repository.
         <enum value="0"             name="CL_MEM_DEVICE_HANDLE_LIST_END_KHR"/>
         <enum value="0"             name="CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR"/>
         <enum value="0"             name="CL_SEMAPHORE_EXPORT_HANDLE_TYPES_LIST_END_KHR"/>
+        <enum value="0"             name="CL_INSTANCE_PLATFORM_PROPERTIES_LIST_END_KHR"/>
     </enums>
 
     <enums name="cl_affinity_domain_ext" vendor="IBM" comment="Property names for CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN_EXT. This is not a bitfield.">
@@ -2778,6 +2780,16 @@ server's OpenCL/api-docs repository.
             <param><type>cl_platform_id</type>             <name>platform</name></param>
             <param><type>void</type>*                      <name>dispatch_data</name></param>
         </command>
+        <command>
+            <proto><type>cl_platform_id</type>             <name>clIcdCreateInstancePlatformKHR</name></proto>
+            <param><type>cl_platform_id</type>                             <name>platform</name></param>
+            <param>const <type>cl_instance_platform_properties_khr</type>* <name>properties</name></param>
+            <param><type>cl_int</type>*                                    <name>errcode_ret</name></param>
+        </command>
+        <command>
+            <proto><type>cl_int</type>                     <name>clIcdDestroyInstancePlatformKHR</name></proto>
+            <param><type>cl_platform_id</type>             <name>platform</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>
@@ -5925,13 +5937,19 @@ server's OpenCL/api-docs repository.
                 <command name="clLogMessagesToStderrAPPLE"/>
             </require>
         </extension>
-        <extension name="cl_khr_icd" revision="2.0.1" supported="opencl" ratified="opencl">
+        <extension name="cl_khr_icd" revision="2.0.2" supported="opencl" ratified="opencl">
             <require>
                 <type name="CL/cl.h"/>
             </require>
+            <require>
+                <type name="cl_instance_platform_properties_khr"/>
+            </require>
             <require comment="cl_platform_info">
                 <enum name="CL_PLATFORM_ICD_SUFFIX_KHR"/>
             </require>
+            <require comment="cl_instance_platform_properties_khr">
+                <enum name="CL_INSTANCE_PLATFORM_PROPERTIES_LIST_END_KHR"/>
+            </require>
             <require comment="Error codes">
                 <enum name="CL_PLATFORM_NOT_FOUND_KHR"/>
             </require>
@@ -5942,6 +5960,8 @@ server's OpenCL/api-docs repository.
                 <command name="clIcdGetPlatformIDsKHR"/>
                 <command name="clIcdGetFunctionAddressForPlatformKHR"/>
                 <command name="clIcdSetPlatformDispatchDataKHR"/>
+                <command name="clIcdCreateInstancePlatformKHR"/>
+                <command name="clIcdDestroyInstancePlatformKHR"/>
             </require>
         </extension>
         <extension name="cl_khr_icd_unloadable" revision="1.0.0" supported="opencl">