cl_khr_icd
Extension through which the Khronos OpenCL installable client driver loader (ICD Loader) may expose multiple separate vendor installable client drivers (Vendor ICDs) for OpenCL.
Description
This is 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. If this extension is supported by an
implementation, the string cl_khr_icd will be present
in the CL_PLATFORM_EXTENSIONS string described in
the table of allowed values for param_name for
clGetDeviceInfo.
If the cl_khr_icd extension is supported, then the
clIcdGetPlatformIDsKHR
function is enabled.
The official source for the ICD loader is available at the
Khronos website. The complete _cl_icd_dispatch
structure is defined in the header icd_dispatch.h
which is available as a part of the source code.
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;
// ... 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.
A link to source code which defines the entries
in the function table structure
_cl_icd_dispatch is available in the
Sample Code section of the OpenCL specification. The order of
the functions in _cl_icd_dispatch is
determined by the ICD Loader's source. The ICD
Loader's source's _cl_icd_dispatch
table is to be appended to only.
Functions which do not have an argument from which the vendor implementation may be
inferred are ignored, with the exception of
clGetExtensionFunctionAddress
which is described below.
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. See Additions to Chapter 9 for details on the mechanism through which this is accomplished. The vendor suffix string is optional.
ICD Loader Vendor Enumeration on Windows
To enumerate Vendor ICDs on Windows, the ICD
Loader scans the values in the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors.
For each value in
this key which has DWORD data set to 0, the
ICD Loader opens the dynamic link library
specified by the name of the value using
LoadLibraryA.
For example, if the registry contains the following value
[HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors]
"c:\\vendor a\\vndra_ocl.dll"=dword:00000000
then the ICD will open the 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/vendors/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/vendors/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.
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.
Copyright © 2007-2013 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.