diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc index 23423c7c..7afe679a 100644 --- a/api/cl_khr_icd.asciidoc +++ b/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. diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 21286361..72dfb4e1 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/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'] diff --git a/xml/cl.xml b/xml/cl.xml index 786ccf14..bacb1268 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -228,6 +228,7 @@ server's OpenCL/api-docs repository. typedef cl_properties cl_layer_properties; typedef cl_uint cl_icdl_info; typedef struct _cl_icd_dispatch cl_icd_dispatch; + typedef cl_properties cl_instance_platform_properties_khr; typedef cl_bitfield cl_device_scheduling_controls_capabilities_img; typedef cl_bitfield cl_device_scheduling_controls_capabilities_arm; typedef cl_bitfield cl_device_controlled_termination_capabilities_arm; @@ -815,6 +816,7 @@ server's OpenCL/api-docs repository. + @@ -2778,6 +2780,16 @@ server's OpenCL/api-docs repository. cl_platform_id platform void* dispatch_data + + cl_platform_id clIcdCreateInstancePlatformKHR + cl_platform_id platform + const cl_instance_platform_properties_khr* properties + cl_int* errcode_ret + + + cl_int clIcdDestroyInstancePlatformKHR + cl_platform_id platform + cl_program clCreateProgramWithILKHR cl_context context @@ -5925,13 +5937,19 @@ server's OpenCL/api-docs repository. - + + + + + + + @@ -5942,6 +5960,8 @@ server's OpenCL/api-docs repository. + +