Name Strings

    cl_khr_icd

Contributors

    Ben Ashbaugh
    Christopher Cameron
    Benedict Gaster
    Michael Houston
    John Kessenich
    Christopher Lamb
    Laurent Morichetti
    Aftab Munshi
    Ofer Rosenberg

IP Status

    No known claims.

Version

    Version 8, August 8, 2017

Number

    OpenCL Extension #5

Status

    Ratified by the Khronos Promoters, January 29, 2010

Extension Type

    OpenCL platform extension

Dependencies

    OpenCL 1.0 is required.

Overview

    This extension defines a simple mechanism through which the Khronos
    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.

Inferring Vendors From Function Calls from 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 this document.  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 entrypoints 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 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 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 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"

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.

New Procedures and Functions

    cl_int clIcdGetPlatformIDsKHR(
        cl_uint num_entries,
        cl_platform_id *platforms,
        cl_uint *num_platforms);

New Tokens

    Accepted as <param_name> to the function clGetPlatformInfo

        CL_PLATFORM_ICD_SUFFIX_KHR          0x0920

    Returned by clGetPlatformIDs when no platforms are found

        CL_PLATFORM_NOT_FOUND_KHR            -1001


Additions to Chapter 4 of the OpenCL 1.0.48 Specification

    In section 4.1, replace the description of the return values of
    clGetPlatformIDs with:

   "clGetPlatformIDs returns CL_SUCCESS if the function is executed
    successfully and there are a non zero number of platforms available.
    It returns CL_PLATFORM_NOT_FOUND_KHR if zero platforms are 
    available.  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."

    In section 4.1, add the following after the description of
    clGetPlatforms:

   "The list of platforms accessible through the Khronos ICD Loader
    can be obtained using the following function

    cl_int clIcdGetPlatformIDsKHR(
        cl_uint num_entries,
        cl_platform_id *platforms,
        cl_uint *num_platforms);

    <num_entries> is the number of cl_platform_id 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 Khronos ICD Loader.  The cl_platform_id values returned in
    <platform> are ICD compatible and can be used to identify a 
    specific OpenCL 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 OpenCL platforms available.

    <num_platforms> returns the number of OpenCL platforms available.
    If <num_platforms> is NULL, then this argument is ignored.

    clIcdGetPlatformIDsKHR returns CL_SUCCESS if the function is executed
    successfully and there are a non zero number of platforms available.
    It returns CL_PLATFORM_NOT_FOUND_KHR if zero platforms are 
    available.  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."

    Add the following to table 4.1:

   "--------------------------------------------------------------------
    cl_platform_info            Return Type Description
    ----------------            ----------- ----------------------------
    CL_PLATFORM_ICD_SUFFIX_KHR  char[]      Then function name suffix 
                                            used to identify extension 
                                            functions to be directed to
                                            this platform by the ICD
                                            Loader."

Additions to Chapter 9 of the OpenCL 1.0.48 Specification

    Add the following paragraph to the end of Section 9.2:

   "For functions supported by the ICD Loader,
    clGetExtensionFunctionAddress will return the function pointer of
    the ICD Loader implementation. For extension functions which the ICD
    Loader is unaware of, the function clGetExtensionFunctionAddress
    will determine the vendor implementation to return based on the
    string passed in. The ICD Loader will return the result from
    querying clGetExtensionFunctionAddress on the vendor ICD enumerated
    by the ICD Loader whose ICD suffix is a suffix of the function name
    being queried. If no such vendor exists or the suffix of the
    function is KHR or EXT then clGetExtensionFunctionAddress will
    return NULL."

Interactions with other extensions

    None.

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.

    2. How are OpenCL extension to be handled?

    RESOLVED: OpenCL extension functions may be added to the ICD as 
    soon as they are implemented by any vendor.  The suffix mechanism 
    provides access for vendor extensions which are not yet added to 
    the ICD.

    3: How will the ICD handle a NULL cl_platform_id?

    RESOLVED: The NULL platform is not supported by the ICD.

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

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

Sample Code
    
    The official source for the ICD loader is available on github, here:
        https://github.com/KhronosGroup/OpenCL-ICD-Loader

    An abbreviated version of the _cl_icd_dispatch structure is
    as follows.

    struct _cl_icd_dispatch
    {
        CL_API_ENTRY cl_int (CL_API_CALL *clGetPlatformIDs)(
            cl_uint          num_entries,
            cl_platform_id * platforms,
            cl_uint *        num_platforms) CL_API_SUFFIX__VERSION_1_0;

        CL_API_ENTRY cl_int (CL_API_CALL *clGetPlatformInfo)(
            cl_platform_id   platform, 
            cl_platform_info param_name,
            size_t           param_value_size, 
            void *           param_value,
            size_t *         param_value_size_ret) CL_API_SUFFIX__VERSION_1_0;

        /* ...continues... */
    }

    As an example of this mechanism in action, consider the function
    clCreateCommandQueue.  The implementation of this function in the
    ICD Loader is as follows

    cl_command_queue clCreateCommandQueue(
        cl_context                     context, 
        cl_device_id                   device, 
        cl_command_queue_properties    properties,
        cl_int *                       errcode_ret) 
    {
        return context->dispatch->clCreateCommandQueue(
            context, 
            device, 
            properties,
            errcode_ret);
    }

Conformance Tests

    A vendor supports cl_khr_icd if conformance may be run successfully
    on their platform through the ICD Loader.

Revision History

    Version 8, 2017/08/08 (Ben Ashbaugh) - updated to include HKR
    as a scanned registry key for Windows, added github link for ICD
    loader source code.

    Version 7, 2010/03/02 (Jon Leech) - fix typos for
    clGetExtensionFunctionAddress (public bug 258), reflow a paragraph
    with very long lines.

    Version 6, 2010/02/17 (Jon Leech) - remove URLs pointing to
    resources available only to Khronos members, since this
    was causing confusion to outside readers of the extension
    spec.

    Version 5, 2009/12/08 (Christopher Cameron) - Clarify language
    of ICD Loader versus Vendor ICD, update Linux enumeration to
    reflect bug and email discussion.

    Version 4, 2009/11/10 (Christopher Cameron) - Fix typos.

    Version 3, 2009/11/05 (Christopher Cameron) - update Linux and
    Windows enumeration to use directories and registry values.
    Change suffix information to come from platform query.  Add 
    error code for clGetPlatformIDs when there are no platforms.

    Version 2, 2009/11/02 (Christopher Cameron) - update Linux 
    enumeration to use INI file format.  Some cleanup of sections.
    Update on ICD unload function.

    Version 1, 2009/09/20 (Christopher Cameron) - initial extension
    specification (see also Khronos bug 5391)