Ratification Status

Ratified

Extension and Version Dependencies

None

Other Extension Metadata

Last Modified Date

2025-04-01

IP Status

No known IP claims.

Description

cl_khr_icd describes a platform extension which defines a simple mechanism through which the Khronos OpenCL installable client driver loader (ICD Loader) may expose multiple separate vendor installable client drivers (Vendor ICDs) for OpenCL. An application written against the ICD Loader will be able to access all cl_platform_ids exposed by all vendor implementations with the ICD Loader acting as a demultiplexor.

This is a platform extension, so if this extension is supported by an implementation, the string "cl_khr_icd" will be present in the CL_PLATFORM_EXTENSIONS string.

Source Code

The official source for the ICD Loader is available on github, at:

https://github.com/KhronosGroup/OpenCL-ICD-Loader

The complete _cl_icd_dispatch structure is defined in the header cl_icd.h, which is available as a part of the OpenCL headers.

Inferring Vendors From Function Call Arguments

At every OpenCL function call, the ICD Loader infers the vendor ICD function to call from the arguments to the function. An object is said to be ICD compatible if it is of the following structure:

struct _cl_<object>
{
    struct _cl_icd_dispatch *dispatch;
    // Since version 2.0.0
    void *dispatch_data;
    // ... remainder of internal data
};

<object> is one of platform_id, device_id, context, command_queue, mem, program, kernel, event, or sampler.

The structure _cl_icd_dispatch is a function pointer dispatch table which is used to direct calls to a particular vendor implementation. All objects created from ICD compatible objects must be ICD compatible.

The definition for _cl_icd_dispatch is provided along with the OpenCL headers. Existing members can never be removed from that structure but new members can be appended.

Functions which do not have an argument from which the vendor implementation may be inferred have been deprecated and may be ignored.

New in version 2.0.0, object that are ICD 2 compatible should also contain a dispatch_data field of type void * that the loader is free to modify for a platform through the clIcdSetPlatformDispatchDataKHR new API entry point. In order to distinguish ICD 1 and ICD 2 objects, the pointers to clGetPlatformIDs and clUnloadCompiler in the dispatch structure must be set to CL_ICD2_TAG_KHR. The vendor driver is responsible for propagating the dispatch_data value when returning objects to users.

ICD Data

A Vendor ICD is defined by two pieces of data:

  • The Vendor ICD library specifies a library which contains the OpenCL entry points for the vendor’s OpenCL implementation. The vendor ICD’s library file name should include the vendor name, or a vendor-specific implementation identifier.

  • The Vendor ICD extension suffix is a short string which specifies the default suffix for extensions implemented only by that vendor. The vendor suffix string is optional.

ICD Loader Vendor Enumeration on Windows

To enumerate Vendor ICDs on Windows, the ICD Loader will first scan for REG_SZ string values in the "Display Adapter" and "Software Components" HKR registry keys. The exact registry keys to scan should be obtained via PnP Configuration Manager APIs, but will look like:

For 64-bit ICDs:

HKLM\SYSTEM\CurrentControlSet\Control\Class\
{Display Adapter GUID}\{Instance ID}\OpenCLDriverName, or

HKLM\SYSTEM\CurrentControlSet\Control\Class\
{Software Component GUID}\{Instance ID}\OpenCLDriverName

For 32-bit ICDs:

HKLM\SYSTEM\CurrentControlSet\Control\Class\
{Display Adapter GUID}\{Instance ID}\OpenCLDriverNameWoW, or

HKLM\SYSTEM\CurrentControlSet\Control\Class\
{Software Component GUID}\{Instance ID}\OpenCLDriverNameWoW

These registry values contain the path to the Vendor ICD library. For example, if the registry contains the value:

[HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}\{Instance}]
"OpenCLDriverName"="c:\\vendor a\\vndra_ocl.dll"

Then the ICD Loader will open the Vendor ICD library:

c:\vendor a\vndra_ocl.dll

The ICD Loader will also scan for REG_DWORD values in the registry key:

HKLM\SOFTWARE\Khronos\OpenCL\Vendors

For each registry value in this key which has data set to 0, the ICD Loader will open the Vendor ICD library specified by the name of the registry value.

For example, if the registry contains the value:

[HKLM\SOFTWARE\Khronos\OpenCL\Vendors]
"c:\\vendor a\\vndra_ocl.dll"=dword:00000000

Then the ICD Loader will open the Vendor ICD library:

c:\vendor a\vndra_ocl.dll

ICD Loader Vendor Enumeration on Linux

To enumerate vendor ICDs on Linux, the ICD Loader scans the files in the path /etc/OpenCL/vendors. For each file in this path, the ICD Loader opens the file as a text file. The expected format for the file is a single line of text which specifies the Vendor ICD’s library. The ICD Loader will attempt to open that file as a shared object using dlopen(). Note that the library specified may be an absolute path or just a file name.

For example, if the following file exists

/etc/OpenCL/vendors/VendorA.icd

and contains the text

libVendorAOpenCL.so

then the ICD Loader will load the library libVendorAOpenCL.so.

ICD Loader Vendor Enumeration on Android

To enumerate vendor ICDs on Android, the ICD Loader scans the files in the path /system/vendor/Khronos/OpenCL/vendors. For each file in this path, the ICD Loader opens the file as a text file. The expected format for the file is a single line of text which specifies the Vendor ICD’s library. The ICD Loader will attempt to open that file as a shared object using dlopen(). Note that the library specified may be an absolute path or just a file name.

For example, if the following file exists

/system/vendor/Khronos/OpenCL/vendors/VendorA.icd

and contains the text

libVendorAOpenCL.so

then the ICD Loader will load the library libVendorAOpenCL.so.

Adding a Vendor Library

Upon successfully loading a Vendor ICD’s library, the ICD Loader queries the following functions from the library: clIcdGetPlatformIDsKHR, clGetPlatformInfo, and clGetExtensionFunctionAddress (note: clGetExtensionFunctionAddress has been deprecated, but is still required for the ICD Loader). If any of these functions are not present then the ICD Loader will close and ignore the library.

Next the ICD Loader queries available ICD-enabled platforms in the library using clIcdGetPlatformIDsKHR. For each of these platforms, the ICD Loader queries the platform’s extension string to verify that cl_khr_icd is supported, then queries the platform’s Vendor ICD extension suffix using clGetPlatformInfo with the value CL_PLATFORM_ICD_SUFFIX_KHR.

If any of these steps fail, the ICD Loader will ignore the Vendor ICD and continue on to the next.

New in version 2.0.0, the ICD Loader will also query the following functions from the library: clIcdGetFunctionAddressForPlatformKHR and clIcdSetPlatformDispatchDataKHR. If these two functions are present and the pointers to clGetPlatformIDs and clUnloadCompiler in the dispatch structure of a platform is set to CL_ICD2_TAG_KHR the platform will be deemed ICD 2 compatible and dispatch will be managed by the ICD Loader. If the CL_ICD2_TAG_KHR tag is present but one of the two functions above is missing or it the tag is present in only one of the pointers, the ICD Loader will ignore the Vendor ICD and continue on to the next.

During initialization, after calling clIcdGetPlatformIDsKHR to query the available platforms, the ICD Loader will, for each ICD 2 compatible platform, query dispatchable entry points using clIcdGetFunctionAddressForPlatformKHR and then set the platform dispatch data using clIcdSetPlatformDispatchDataKHR.

New Commands

  • clIcdGetPlatformIDsKHR

New in version 2.0.0:

  • clIcdGetFunctionAddressForPlatformKHR

  • clIcdSetPlatformDispatchDataKHR

New Enums

Accepted as param_name to the function clGetPlatformInfo:

  • CL_PLATFORM_ICD_SUFFIX_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 pointers to clGetPlatformIDs and clUnloadCompiler in the dispatch structure:

  • CL_ICD2_TAG_KHR

Issues

  1. Some OpenCL functions do not take an object argument from which their vendor library may be identified (e.g, clUnloadCompiler), how will they be handled?

    RESOLVED: Such functions will be a noop for all calls through the ICD Loader.

  2. How are OpenCL extension to be handled?

    RESOLVED: Extension APIs must be queried using clGetExtensionFunctionAddressForPlatform.

  3. How will the ICD Loader handle a NULL cl_platform_id?

    RESOLVED: The ICD will by default choose the first enumerated platform as the NULL platform.

  4. There exists no mechanism to unload the ICD Loader, should there be one?

    RESOLVED: As there is no standard mechanism for unloading a vendor implementation, do not add one for the ICD Loader.

  5. How will the ICD Loader handle NULL objects passed to the OpenCL functions?

    RESOLVED: The ICD Loader will check for NULL objects passed to the OpenCL functions without trying to dereference the NULL objects for obtaining the ICD dispatch table. On detecting a NULL object it will return one of the an invalid object error values (e.g. CL_INVALID_DEVICE corresponding to the object in question.

  6. How will the ICD loader avoid calling entry points outside of the dispatch table of old implementations, potentially causing segfaults?

    RESOLVED: From versions 2.0.0 and above, the loader will be responsible for managing dispatch data information per platform. The content of the dispatch table is obtained through a dedicated entry point, and missing entry points are replaced by stubs that return CL_INVALID_OPERATION.

  7. How will the ICD loader set the loader managed dispatch information in new objects? Some of these objects may be created by extension functions that the loader is unaware of.

    RESOLVED: During initialization, the loader will set the platform dispatch information through a new entry point. The implementation will be responsible for propagating this information to new objects.

Version History

  • Revision 1.0.0, 2020-04-21

    • First assigned version.

  • Revision 2.0.0, 2025-04-01

    • Loader managed dispatch.

See Also

No cross-references are available

Document Notes

For more information, see the OpenCL Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0