cl_loader_layers.asciidoc

Installable OpenCL Loader Layers

Overview

This section describes cl_loader_layers loader extension which defines a simple mechanism through which the Khronos OpenCL installable client driver loader (ICD Loader) may expose load multiple separate installable interception layers (Layer ICDs) for OpenCL.

General information

Version history

Date	Version	Description
2023-08-23	1.1.0	Deinitialization
2020-11-04	1.0.0	First assigned version.

Contributors

Brice Videau, Argonne National Laboratory

New Procedures and Functions

A layer needs to implement and expose clGetLayerInfo and clInitLayer in a shared library. If one or both of those are missing, the loader will discard the layer. From version 1.1.0 of the API the layer must also implement and expose clDeinitLayer.

cl_int clGetLayerInfo(cl_layer_info  param_name,
                      size_t         param_value_size,
                      void          *param_value,
                      size_t        *param_value_size_ret);

cl_int clInitLayer(cl_uint                 num_entries,
                   const cl_icd_dispatch  *target_dispatch,
                   cl_uint                *num_entries_ret,
                   const cl_icd_dispatch **layer_dispatch_ret);

cl_int clDeinitLayer(void);

New API Types

typedef cl_uint cl_layer_info;
typedef cl_uint cl_layer_api_version;

New API Enums

Accepted as param_name to the function clGetLayerInfo:

#define CL_LAYER_API_VERSION        0x4240
#define CL_LAYER_NAME               0x4241

New API Tokens

Returned by clGetLayerInfo when supplied CL_LAYER_API_VERSION and the corresponding layer implements version 1.0.0 or 1.1.0 of the layer API respectively:

#define CL_LAYER_API_VERSION_100 100
#define CL_LAYER_API_VERSION_110 110

New Environment Variables

A colon separated list of layer libraries that the Loader must try to load. The layers are loaded in the specified order. The most recently loaded layer will be first in the dispatch chain.

OPENCL_LAYERS

OpenCL Layer Documentation

Querying Layer Info

Information concerning a Layer can be obtained with the function:

cl_int clGetLayerInfo(cl_layer_info  param_name,
                      size_t         param_value_size,
                      void          *param_value,
                      size_t        *param_value_size_ret);

• param_name is an enumeration constant that identifies the platform information being queried. It can be one of the following values as specified in the Layer Queries table.

• param_value_size specifies the size in bytes of memory pointed to by param_value. This size in bytes must be ≥ to the size of return type specified in the Layer Queries table.

• param_value is a pointer to memory location where appropriate values for a given param_name, as specified in the Layer Queries table, will be returned. If param_value is NULL, it is ignored.

• param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

The information that can be queried using clGetLayerInfo is specified in the Layer Queries table.

Table 1. List of supported param_names by [clGetLayerInfo]

Layer Info	Return Type	Description
CL_LAYER_API_VERSION	cl_layer_api_version	OpenCL Layer API version
CL_LAYER_NAME	char[]	OpenCL Layer Name

clGetLayerInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors.

• CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is < size of return type as specified in the Layer Queries table, and param_value is not a NULL value.

Layer Initialization

Initialization of a Layer can be achieved with the function:

cl_int clInitLayer(cl_uint                 num_entries,
                   const cl_icd_dispatch  *target_dispatch,
                   cl_uint                *num_entries_ret,
                   const cl_icd_dispatch **layer_dispatch_ret);

• num_entries is the number of entry provided by the Loader to the layer.

• target_dispatch is the dispatch table, provided by the loader, that the layer must redirect it’s call to.

• num_entries_ret returns the number of entries in the dispatch table the layer will be returning.

• layer_dispatch_ret return the address of the layer dispatch table. The table can contain NULL value entries, and the loader is responsible for providing the missing entries using the entries from the target dispatch.

clInitLayer returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors.

• CL_INVALID_VALUE if num_entries is insufficient for the layer or if target_dispatch is a NULL value, or num_entries_ret is a NULL value, or layer_dispatch_ret is a NULL value.

Layer Deinitialization

Deinitialization of a Layer, which should allow subsequent reinitialization through clInitLayer, can be achieved with the function:

cl_int clDeinitLayer(void);

Note	clDeinitLayer is new in API version 1.1.0

clDeinitLayer returns CL_SUCCESS if the function is executed successfully.

Source Code

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

https://github.com/KhronosGroup/OpenCL-ICD-Loader The official API headers are available on github, at:

https://github.com/KhronosGroup/OpenCL-Headers The header file CL/cl_icd.h defines the OpenCL dispatch table. The header file CL/cl_layer.h defines the necessary types and API entry points.