Added instance specification.

KhronosGroup · Sep 13, 2024 · 4ec65bf · 4ec65bf
1 parent 57c65a4
commit 4ec65bf
Show file tree

Hide file tree

Showing 4 changed files with 191 additions and 1 deletion.
diff --git a/api/appendix_f.asciidoc b/api/appendix_f.asciidoc
@@ -435,6 +435,11 @@ ifdef::cl_khr_icd[]
 
 include::{generated}/api/version-notes/CL_PLATFORM_NOT_FOUND_KHR.asciidoc[]
   | Returned by {clGetPlatformIDs} when no platforms are available.
+
+| {CL_INVALID_INSTANCE_KHR_anchor}
+
+include::{generated}/api/version-notes/CL_INVALID_INSTANCE_KHR.asciidoc[]
+  | Returned when the specified instance  is not a <<valid-object-definition,valid instance>>.
 endif::cl_khr_icd[]
 
 ifdef::cl_khr_semaphore[]

diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc
@@ -255,6 +255,23 @@ query dispatchable entry points using {clIcdGetFunctionAddressForPlatformKHR}
 and then set the platform dispatch data using
 {clIcdSetPlatformDispatchDataKHR}.
 
+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*.
+
+Users can create new instances using {clCreateInstanceKHR}. Instances contain
+an instance platforms of all *instance compatible* platforms. These instance
+platforms can be queried using {clGetPlatformIDsForInstanceKHR}. Devices returned
+by {clGetDeviceIDs} used on an instance platform will be instance devices.
+An instance can be destroyed using {clDestroyInstanceKHR}.
+
+When new instances are created the loader will create new instances of these
+platforms using {clIcdCreateInstancePlatformKHR}, and set instance platforms'
+dispatch data using {clIcdSetPlatformDispatchDataKHR}. When an instance is
+destroyed, instance platforms are destroyed with
+{clIcdDestroyInstancePlatformKHR}.
+
 === New Commands
 
   * {clIcdGetPlatformIDsKHR}
@@ -263,6 +280,11 @@ New in version 2.0.0:
 
   * {clIcdGetFunctionAddressForPlatformKHR}
   * {clIcdSetPlatformDispatchDataKHR}
+  * {clIcdCreateInstancePlatformKHR}
+  * {clIcdDestroyInstancePlatformKHR}
+  * {clCreateInstanceKHR}
+  * {clDestroyInstanceKHR}
+  * {clGetPlatformIDsForInstanceKHR}
 
 === New Enums
 
@@ -286,6 +308,15 @@ Loader:
 
   * {CL_PLATFORM_UNLOADABLE_KHR}
 
+Returned by {clDestroyInstanceKHR} or {clGetPlatformIDsForInstanceKHR}
+when an invalid instance is given:
+
+  * {CL_INVALID_INSTANCE_KHR}
+
+Accepted as terminator to the _properties_ list of {clCreateInstanceKHR}.
+
+  * {CL_INSTANCE_PROPERTIES_LIST_END_KHR}
+
 === Issues
 
   . Some OpenCL functions do not take an object argument from which their

diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc
@@ -94,6 +94,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
@@ -121,6 +122,115 @@ executed successfully.
 It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform.
 --
 
+[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}
+
+  * _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_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.
+--
+
+[open,refpage='clCreateInstanceKHR',desc='Create an OpenCL instance',type='protos']
+--
+An instance can be created by the user by using the following function:
+
+include::{generated}/api/protos/clCreateInstanceKHR.txt[]
+include::{generated}/api/version-notes/clCreateInstanceKHR.asciidoc[]
+
+  * _properties_ specifies additional instance properties in a
+    {CL_INSTANCE_PROPERTIES_LIST_END_KHR_anchor} terminated list.
+    Can be `NULL` if no properties are given.
+  * _errcode_ret_ will return an appropriate error code as described below.
+    If _errcode_ret_ is `NULL`, no error code is returned.
+
+{clCreateInstanceKHR} returns a valid non-zero OpenCL instance object
+and _errcode_ret_ is set to {CL_SUCCESS} if the instance object is
+created successfully.
+Otherwise, it returns a `NULL` value with one of the following error values
+returned in _errcode_ret_:
+
+    * {CL_INVALID_VALUE} if _properties_ contains an invalid value
+    * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
+      required by the OpenCL implementation on the host.
+    * {CL_PLATFORM_NOT_FOUND_KHR} if zero instance platforms are available.
+--
+
+[open,refpage='clDestroyInstanceKHR',desc='Destroy an OpenCL instance',type='protos']
+--
+An instance can be destroyed by the user by using the following function:
+
+include::{generated}/api/protos/clDestroyInstanceKHR.txt[]
+include::{generated}/api/version-notes/clDestroyInstanceKHR.asciidoc[]
+
+  * _instance_ refers to the instance object returned by {clCreateInstanceKHR}.
+
+{clDestroyInstanceKHR} returns {CL_SUCCESS} if the function is executed
+successfully.
+It returns {CL_INVALID_INSTANCE_KHR} if _instance_ is not a valid instance
+object.
+--
+
+[open,refpage='clGetPlatformIDsForInstanceKHR',desc='Query list of available platforms in an instance',type='protos']
+--
+The list of platforms available in an instance can be obtained with the
+function:
+
+include::{generated}/api/protos/clGetPlatformIDsForInstanceKHR.txt[]
+include::{generated}/api/version-notes/clGetPlatformIDsForInstanceKHR.asciidoc[]
+
+  * _instance_ refers to the instance object returned by {clCreateInstanceKHR}.
+  * _num_entries_ is the number of {cl_platform_id_TYPE} entries that can
+    be added to _platforms_. If _platforms_ is not `NULL`, then _num_entries_
+    must be greater than zero.
+  * _platforms_ returns a list of OpenCL platforms available for access through
+    the _instance_. The {cl_platform_id_TYPE} values returned in _platforms_
+    can be used to identify a specific instance platform. If the _platforms_
+    argument is `NULL`, then this argument is ignored. The number of OpenCL
+    platforms returned is the minimum of the value specified by _num_entries_
+    or the number of instance platforms available.
+  * _num_platforms_ returns the number of instance platforms available.
+    If _num_platforms_ is `NULL`, then this argument is ignored.
+
+{clGetPlatformIDsForInstanceKHR} returns {CL_SUCCESS} if the function is
+executed successfully.
+It returns {CL_INVALID_INSTANCE_KHR} if _instance_ is not a valid instance object.
+It returns {CL_INVALID_VALUE} if _num_entries_ is equal to zero and
+_platforms_ is not `NULL` or if both _num_platforms_ and _platforms_ are
+`NULL`.
+--
+
 endif::cl_khr_icd[]
 
 [open,refpage='clGetPlatformInfo',desc='Query information about an OpenCL platform',type='protos']

diff --git a/xml/cl.xml b/xml/cl.xml
@@ -156,6 +156,7 @@ server's OpenCL/api-docs repository.
         <type category="define">typedef struct _cl_event *            <name>cl_event</name>;</type>
         <type category="define">typedef struct _cl_sampler *          <name>cl_sampler</name>;</type>
         <type category="define">typedef struct _cl_semaphore_khr *    <name>cl_semaphore_khr</name>;</type>
+        <type category="define">typedef struct _cl_instance_khr *     <name>cl_instance_khr</name>;</type>
         <type category="define" comment="Unlike cl_platform.h types, not guaranteed to be the same size as kernel bool">typedef <type>cl_uint</type>          <name>cl_bool</name>;</type>
         <type category="define">typedef <type>cl_ulong</type>         <name>cl_bitfield</name>;</type>
         <type category="define">typedef <type>cl_ulong</type>         <name>cl_properties</name>;</type>
@@ -255,6 +256,7 @@ server's OpenCL/api-docs repository.
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_platform_command_buffer_capabilities_khr</name>;</type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_mutable_dispatch_asserts_khr</name></type>
         <type category="define">typedef <type>cl_bitfield</type>      <name>cl_device_kernel_clock_capabilities_khr</name>;</type>
+        <type category="define" requires="stdint">typedef <type>intptr_t</type> <name>cl_instance_properties_khr</name>;</type>
 
             <comment>Structure types</comment>
         <type category="struct" name="cl_dx9_surface_info_khr">
@@ -710,7 +712,10 @@ server's OpenCL/api-docs repository.
             <unused start="-1143" end="-1153"/>
     </enums>
 
-    <enums start="-1154" end="-9999" name="ErrorCodes.future" vendor="Khronos" comment="RESERVED FOR FUTURE ALLOCATIONS BY KHRONOS">
+    <enums start="-1154" end="-1154" name="ErrorCodes.1154" vendor="Khronos" comment="For cl_khr_icd">
+        <enum value="-1154"         name="CL_INVALID_INSTANCE_KHR"/>
+    </enums>
+    <enums start="-1155" end="-9999" name="ErrorCodes.future" vendor="Khronos" comment="RESERVED FOR FUTURE ALLOCATIONS BY KHRONOS">
             <unused start="-1154" end="-9999"/>
     </enums>
 
@@ -731,6 +736,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_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.">
@@ -2579,6 +2585,31 @@ 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><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>
+            <proto><type>cl_instance_khr</type>                   <name>clCreateInstanceKHR</name></proto>
+            <param>const <type>cl_instance_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>clDestroyInstanceKHR</name></proto>
+            <param><type>cl_instance_khr</type>            <name>instance</name></param>
+        </command>
+        <command>
+            <proto><type>cl_int</type>                     <name>clGetPlatformIDsForInstanceKHR</name></proto>
+            <param><type>cl_instance_khr</type>            <name>instance</name></param>
+            <param><type>cl_uint</type>                    <name>num_entries</name></param>
+            <param><type>cl_platform_id</type>*            <name>platforms</name></param>
+            <param><type>cl_uint</type>*                   <name>num_platforms</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>
@@ -5628,12 +5659,20 @@ server's OpenCL/api-docs repository.
             <require>
                 <type name="CL/cl.h"/>
             </require>
+            <require>
+                <type name="cl_instance_khr"/>
+                <type name="cl_instance_properties_khr"/>
+            </require>
             <require comment="cl_platform_info">
                 <enum name="CL_PLATFORM_ICD_SUFFIX_KHR"/>
                 <enum name="CL_PLATFORM_UNLOADABLE_KHR"/>
             </require>
+            <require comment="cl_instance_properties_khr">
+                <enum name="CL_INSTANCE_PROPERTIES_LIST_END_KHR"/>
+            </require>
             <require comment="Error codes">
                 <enum name="CL_PLATFORM_NOT_FOUND_KHR"/>
+                <enum name="CL_INVALID_INSTANCE_KHR"/>
             </require>
             <require comment="ICD 2 tag value">
                 <type name="CL_ICD2_TAG_KHR"/>
@@ -5642,6 +5681,11 @@ server's OpenCL/api-docs repository.
                 <command name="clIcdGetPlatformIDsKHR"/>
                 <command name="clIcdGetFunctionAddressForPlatformKHR"/>
                 <command name="clIcdSetPlatformDispatchDataKHR"/>
+                <command name="clIcdCreateInstancePlatformKHR"/>
+                <command name="clIcdDestroyInstancePlatformKHR"/>
+                <command name="clCreateInstanceKHR"/>
+                <command name="clDestroyInstanceKHR"/>
+                <command name="clGetPlatformIDsForInstanceKHR"/>
             </require>
         </extension>
         <extension name="cl_loader_layers" revision="2.0.0" supported="opencl">