Skip to content

Added instance platform specification. #1527

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Kerilk wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added instance platform specification. #1527

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion api/cl_khr_icd.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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}
Expand All @@ -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}:
Expand All @@ -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
Expand Down Expand Up @@ -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.
52 changes: 52 additions & 0 deletions api/opencl_platform_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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']
Expand Down
22 changes: 21 additions & 1 deletion xml/cl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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.">
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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">
Expand Down