Copyright 2008-2018 The Khronos Group.
This specification is protected by copyright laws and contains material proprietary to the Khronos Group, Inc. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos Group.
Khronos Group grants a conditional copyright license to use and reproduce the unmodified specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms. Parties desiring to implement the specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos IP Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this specification; see https://www.khronos.org/adopters.
Khronos Group makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will the Khronos Group, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.
Vulkan is a registered trademark and Khronos, OpenXR, SPIR, SPIR-V, SYCL, WebGL, WebCL, OpenVX, OpenVG, EGL, COLLADA, glTF, NNEF, OpenKODE, OpenKCAM, StreamInput, OpenWF, OpenSL ES, OpenMAX, OpenMAX AL, OpenMAX IL, OpenMAX DL, OpenML and DevU are trademarks of the Khronos Group Inc. ASTC is a trademark of ARM Holdings PLC, OpenCL is a trademark of Apple Inc. and OpenGL and OpenML are registered trademarks and the OpenGL ES and OpenGL SC logos are trademarks of Silicon Graphics International used under license by Khronos. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.
The OpenCL Installable Client Driver (ICD) is a mechanism to allow OpenCL implementations from multiple vendors to coexist on a system. A vendor OpenCL implementation is an OpenCL Installable Client Driver if it implements the extension
cl_khr_icd, which is described in the OpenCL extension registry:
The ICD loader library is a shared resource that discovers and enumerates all OpenCL ICDs. It will typically be installed by an installer from one of the vendors.
In order to prevent conflicts between vendor installers it is necessary to have strict guidelines for installation and uninstallation of the ICD loader library and associated system configuration.
2. General Guidelines
Vendor installers MUST install and uninstall their ICD-compliant implementations in such a way that the installer:
Installs its own ICD loader library if and only if the existing ICD loader library is older than the one being installed.
Does not remove ICD loader library at uninstall if other implementations exist.
Does not cause existing installations to become inoperable or unusable in any way. This includes, but is not limited to, WHQL and similar signed package certification check failures.
Does not manipulate the vendor enumeration order within the ICD loader library except to add (or remove) the new vendor implementation.
2.1. Compatibility With Non-ICD implementations
Because the ICD loader library and a non-ICD OpenCL implementation are likely to share the same library file name, behavior is undefined if the ICD loader library is installed on a system with an existing non-ICD OpenCL implementation, or if a non-ICD OpenCL implementation is installed on a system with an existing ICD loader library. In particular, in this scenario the non-ICD OpenCL implementation, or the ICD OpenCL implementation, or both, may cease to function correctly.
3. Windows ICD Installation and Uninstallation
On Windows, the ICD loader library is
In general, Windows Vendor installers MUST follow the guidelines described here:
If the Windows Vendor installer is using the Windows Installer then many of the steps below will happen automatically.
3.1. Windows ICD Installation
Vendor MAY include
OpenCL.dllfile in its vendor package.
IF Vendor includes
OpenCL.dllin the manifest of the signed vendor package, then Vendor MUST NOT include
OpenCL.dllin the manifest of the signed vendor package to map to either of the following paths:
Vendor MAY include
OpenCL.dllin the manifest of a signed package provided that a vendor specific directory is used, such as
Vendor MUST check for existing OpenCL installations before installing
Vendor SHALL check the version of
OpenCL.dllis not present, install ICD in 3.a.i and/or 3.a.ii as appropriate.
IF version of installed
OpenCL.dllversion, then replace the installed
OpenCL.dllin 3.a.i and/or 3.a.ii as appropriate.
IF version of installed
OpenCL.dllversion, then vendor MUST NOT modify the installed
OpenCL.dllis described in a later section.
Vendor MUST accurately increment the reference count for
IF Vendor does not use the Windows Installer, the Vendor installer MUST increment the reference count under the registry key:
3.2. Windows ICD Uninstallation
OpenCL.dll should be straightforward since it is reference counted as a shared component.
Vendor MUST accurately decrement the reference count for
OpenCL.dlland delete it when the reference count reaches zero.
Note that older installers that do not comply with these guidelines may not check the reference count when uninstalling and hence may erroneously uninstall
OpenCL.dll while it is still in use by another OpenCL implementation. If this occurs, reinstalling the other OpenCL implementation will usually fix the issue.
3.3. OpenCL.dll Versioning
OpenCL.dll has a FileVersion string of the form “x.y.z.0”. The parts x and y denote the OpenCL major and minor version (2.2 at the time of writing this document). The third part z is a revision number which will be incremented for every change made to the ICD loader sources.
For same version of OpenCL, higher z value means a later revision. For different versions of OpenCL a higher OpenCL version means a later revision, irrespective of the value of z.
If a given OpenCL.dll file does not have a valid FileVersion string or if the FileVersion string is absent then the version should be considered to be "0.0.0.0".
4. Android ICD Installation
On Android, the ICD loader library is
4.1. Target Device Filesystem
Vendor MUST install
libOpenCL.soto reside directly within the directory
/vendor/lib/which is one of the paths searched by the dynamic loader on an Android system.
Usually an Android system will have a single-vendor OpenCL installation, so the need to overwrite
libOpenCL.so should not arise.
4.2. Android SDK/NDK
Vendors should package the
libOpenCL.so stub for linking to user applications in their Android SDK/NDK and either configure the default environment, or provide instructions for configuring the build environment, or both.
Typically a vendor should put
libOpenCL.so inside a directory within the Android SDK/NDK package provided by the vendor for application development on the vendor’s device. The path to this directory should be added to LIBPATH in the default environment of the IDE (e.g. Eclipse) and other build configurations (e.g. Makefiles) in the SDK/NDK. The path should also be mentioned in the vendor documentation to allow application developers to write their own Makefiles or other build systems.