Skip to content

Commit

Permalink
Added instance specification.
Browse files Browse the repository at this point in the history
  • Loading branch information
Kerilk committed Sep 13, 2024
1 parent 57c65a4 commit 4ec65bf
Show file tree
Hide file tree
Showing 4 changed files with 191 additions and 1 deletion.
5 changes: 5 additions & 0 deletions api/appendix_f.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
31 changes: 31 additions & 0 deletions api/cl_khr_icd.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -263,6 +280,11 @@ New in version 2.0.0:

* {clIcdGetFunctionAddressForPlatformKHR}
* {clIcdSetPlatformDispatchDataKHR}
* {clIcdCreateInstancePlatformKHR}
* {clIcdDestroyInstancePlatformKHR}
* {clCreateInstanceKHR}
* {clDestroyInstanceKHR}
* {clGetPlatformIDsForInstanceKHR}

=== New Enums

Expand All @@ -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
Expand Down
110 changes: 110 additions & 0 deletions api/opencl_platform_layer.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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']
Expand Down
46 changes: 45 additions & 1 deletion xml/cl.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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">
Expand Down Expand Up @@ -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>

Expand All @@ -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.">
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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"/>
Expand All @@ -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">
Expand Down

0 comments on commit 4ec65bf

Please sign in to comment.