Skip to content

Latest commit

 

History

History
116 lines (75 loc) · 6.04 KB

cl_khr_icd.adoc

File metadata and controls

116 lines (75 loc) · 6.04 KB
Raw

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.

#pragma OPENCL EXTENSION cl_khr_icd : enable

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