Skip to content

Commit

Permalink
Added instance specification.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kerilk
Kerilk committed Sep 3, 2024
1 parent e1d0b28 commit 44dc10e
Show file tree
Hide file tree
Showing 2 changed files with 207 additions and 8 deletions.
173 changes: 168 additions & 5 deletions ext/cl_khr_icd.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,23 @@ will, for each platform, 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 funcions are present and the library's platforms are ICD 2
compatible, these platformes will be deemed instance compatible.

Users can create new instances using {clCreateInstanceKHR}. Instances contain
all instance platforms of all instance compatible platforms. These instance
platforms can be queied 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}.

[[cl_khr_icd-new-procedures-and-functions]]
=== New Procedures and Functions

Expand All @@ -266,6 +283,36 @@ void *clIcdGetFunctionAddressForPlatformKHR(cl_platform_id platform,
/* New in version 2.0.0 */
cl_int clIcdSetPlatformDispatchDataKHR(cl_platform_id platform,
void *dispatch_data);
/* New in version 2.0.0 */
cl_platform_id clIcdCreateInstancePlatformKHR(cl_platform_id platform,
cl_int *errcode_ret);
/* New in version 2.0.0 */
cl_int clIcdDestroyInstancePlatformKHR(cl_platform_id platform);
/* New in version 2.0.0 */
cl_instance_khr clCreateInstanceKHR(const cl_instance_properties_khr *properties,
cl_int *errcode_ret);
/* New in version 2.0.0 */
cl_int clDestroyInstanceKHR(cl_instance_khr instance);
/* New in version 2.0.0 */
cl_int clGetPlatformIDsForInstanceKHR(cl_instance_khr instance,
cl_uint num_entries,
cl_platform_id *platforms,
cl_uint *num_platforms);
----

[[cl_khr_icd-new-api-types]]
=== New API Types

*New in version 2.0.0*
[source,opencl]
----
typedef struct _cl_instance_khr *cl_instance_khr;
typedef intptr_t cl_instance_properties_khr;
----

[[cl_khr_icd-new-tokens]]
Expand All @@ -277,19 +324,38 @@ Accepted as _param_name_ to the function {clGetPlatformInfo}:
CL_PLATFORM_ICD_SUFFIX_KHR
----

*New in version 2.0.0*
----
CL_PLATFORM_UNLOADABLE_KHR
----

Returned by {clGetPlatformIDs} when no platforms are found:

----
CL_PLATFORM_NOT_FOUND_KHR
----

*New in version 2.0.0*, Used as a value in the pointer to
*New in version 2.0.0*, returned by {clDestroyInstanceKHR} or
{clGetPlatformIDsForInstanceKHR} when an invalid instance is given:

----
CL_INVALID_INSTANCE_KHR
----

*New in version 2.0.0*, used as a value in the pointer to
`clGetPlatformIDs` in the dispatch structure.

----
CL_ICD2_TAG_KHR
----

*New in version 2.0.0*, accepted as terminator to the _properties_
list of {clCreateInstanceKHR}.

----
CL_INSTANCE_PROPERTIES_LIST_END_KHR
----

[[cl_khr_icd-additions-to-chapter-4]]
=== Additions to Chapter 4 of the OpenCL 2.2 Specification

Expand Down Expand Up @@ -336,7 +402,8 @@ _platforms_ is not `NULL` or if both _num_platforms_ and _platforms_ are
*New in cl_khr_icd version 2.0.0*

The entry point of a given platform that is ICD 2 compatible can be obtained
using the following function:
by the ICD Loader by using the following function:

include::{generated}/api/protos/clIcdGetFunctionAddressForPlatformKHR.txt[]

_platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
Expand All @@ -350,16 +417,112 @@ header file.
A return value of `NULL` indicates that the specified function does not exist
for _platform_, or _platform_ is not a valid platform for the implementation.

The `dispatch_data` field of a platform can be set using the following function:
The `dispatch_data` field of a platform can be set by the ICD loader by using
the following function:

include::{generated}/api/protos/clIcdSetPlatformDispatchDataKHR.txt[]

_platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR}
_platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR} or by
{clIcdCreateInstancePlatformKHR}

_dispatch_data_ is the value to set the `dispatch_data` field of the structure
to

{clIcdSetPlatformDispatchDataKHR} returns {CL_SUCCESS} if the function is
executed successfully.
It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform."
It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform.

An instance can be created by the user by using the following function:

include::{generated}/api/protos/clCreateInstanceKHR.txt[]

_properties_ specifies additional instance properties in a
{CL_INSTANCE_PROPERTIES_LIST_END_KHR} 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.

An instance can be destroyed by the user by using the following function:

include::{generated}/api/protos/clDestroyInstanceKHR.txt[]

_instance_ refers to the instance object returned by {clCreateInstanceKHR}.

{clDestroyInstanceKHR} returns {CL_SUCCESS} if the function is executed
successfully.
It returns {CL_INVALID_INSTANCE} if _instance_ is not a valid instance object.

Instance platforms can be queried by the user using the following function:

include::{generated}/api/protos/clGetPlatformIDsForInstanceKHR.txt[]

_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} 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`.

An instance platform can be created by the ICD Loader by using the following
function:

include::{generated}/api/protos/clIcdCreateInstancePlatformKHR.txt[]

_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.

An instance platform can be destroyed by the ICD Loader by using the following
function:

include::{generated}/api/protos/clIcdDestroyInstancePlatformKHRtxt[]

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

Add the following to _table 4.1_:

Expand Down
42 changes: 39 additions & 3 deletions xml/cl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,7 @@ server's OpenCL/api-docs repository.
<type category="define">typedef <type>cl_bitfield</type> <name>cl_device_fp_atomic_capabilities_ext</name>;</type>
<type category="define">typedef <type>cl_uint</type> <name>cl_image_requirements_info_ext</name>;</type>
<type category="define">typedef <type>cl_bitfield</type> <name>cl_platform_command_buffer_capabilities_khr</name>;</type>
<type category="define">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">
Expand Down Expand Up @@ -507,7 +508,7 @@ server's OpenCL/api-docs repository.
</enums>

<enums name="Constants.cl_khr_icd" vendor="Khronos" comment="ICD 2 tag, in cl_ext.h">
<enum value="((size_t) 0x4F50454E434C3331ULL)" name="CL_ICD2_TAG_KHR"/>
<enum value="((intptr_t) 0x4F50454E434C3331ULL)" name="CL_ICD2_TAG_KHR"/>
</enums>

<enums start="0" end="-999" name="ErrorCodes.0" vendor="Khronos" comment="Error codes start at 0 and decrease">
Expand Down Expand Up @@ -715,6 +716,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.">
Expand Down Expand Up @@ -2549,6 +2551,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>
Expand Down Expand Up @@ -5577,16 +5604,25 @@ server's OpenCL/api-docs repository.
<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">
<enum name="CL_ICD2_TAG_KHR"/>
</require>
<require>
<command name="clIcdGetPlatformIDsKHR"/>
<command name="clGetFunctionAddressForPlatformKHR"/>
<command name="clSetPlatformDispatchDataKHR"/>
<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" supported="opencl">
Expand Down

0 comments on commit 44dc10e

Please sign in to comment.