Added instance specification.

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[]

api/cl_khr_icd.asciidoc

@@ -254,6 +254,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}
@@ -262,6 +279,11 @@ New in version 2.0.0:
 
  * {clIcdGetFunctionAddressForPlatformKHR}
  * {clIcdSetPlatformDispatchDataKHR}
+ * {clIcdCreateInstancePlatformKHR}
+ * {clIcdDestroyInstancePlatformKHR}
+ * {clCreateInstanceKHR}
+ * {clDestroyInstanceKHR}
+ * {clGetPlatformIDsForInstanceKHR}
 
 === New Enums
 
@@ -285,6 +307,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

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']

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">