libOpenCL, libOpenCL.so - OCL-ICD implementation of OpenCL ICD loader
libOpenCL.so is the library linked by OpenCL programs. It does not contains any
OpenCL implementation itself, but merely act as a dispatcher to real OpenCL
implementations provided as OpenCL Installable Client Driver (ICD). An ICD
loader should be able to load ICDs provided by any vendors.
The ICD Loader looks for files into
/usr/local/etc/OpenCL/vendors directory and, for each file whose name
ends with .icd, the ICD Loader loads with dlopen(3) the shared
library whose name is on the first line of the .icd file. According
to OpenCL specifications from Khronos (see [Khronos]), the default path for
this purpose is /usr/local/etc/OpenCL/vendors, but this OCL-ICD
version has been configurated otherwise.
Each shared library name in ".icd" files can have its
path, or it can be a plain filename. In the latter case, the ICD shared
library will be looked for into the standard dynamic library loader
paths.
Some environment variables can be used modify the default behavior of libOpenCL.
OPENCL_VENDOR_PATH
This variable allows one to modify the default
/usr/local/etc/OpenCL/vendors path. It is compatible with some other
ICD loaders (but not all of them, as the variable is not part of the
standard). Note that $OCL_ICD_VENDORS (see below) is used in priority
if defined and not empty.
OCL_ICD_VENDORS
This variable allows one to change the way ICD are
searched on the system. Several cases are considered:
1.if $OCL_ICD_VENDORS is a directory path, then
this path replaces the "/usr/local/etc/OpenCL/vendors" path in the
standard behavior: the loader will use the .icd files in this
directory;
2.else, if
$OCL_ICD_VENDORS ends with
.icd, libOpenCL.so will only load the ICD whose shared library name is
wrote into the specified ".icd" file;
If there is no slashes into $OCL_ICD_VENDORS, libOpenCL.so
will first try to use
/usr/local/etc/OpenCL/vendors/$OCL_ICD_VENDORS (or
$OPENCL_VENDOR_PATH/$OCL_ICD_VENDORS if
OPENCL_VENDOR_PATH is defined). If this fail or if there are shashes,
it uses $OCL_ICD_VENDORS (as a relative or absolute file name
path).
3.else libOpenCL.so will try to load
$OCL_ICD_VENDORS as the ICD shared library itself (i.e. to load it
directly with dlopen(3)).
OPENCL_LAYERS
This variable allows one to specify a colon separated
list of layers to load, specifying their path. This support is
experimental.
OCL_ICD_ASSUME_ICD_EXTENSION
If set to an non-empty value, contrary the Khronos
specification, the loader will not check that the loaded ICDs declare the
cl_khr_icd extension. It will also use the clGetPlatformInfo from the dispatch
table if no such function is globally available. You may need to define this
environment variable if you are using not (fully) compliant ICD, or if you are
using the Intel ICD together with optirun(1). In the latter case, a bug
into the Intel ICD will make the application crash.
If set to the debug value, some additional messages will be
printed in debug mode (see OCL_ICD_DEBUG below).
OCL_ICD_PLATFORM_SORT
Allows one to choose the way platforms are sorted when
presented to programs through
clGetPlatformIDs(3). Current provided
algorithms are:
•devices: first, list platforms that
support most GPU, then most CPU then most accelerators. If
OCL_ICD_PLATFORM_SORT is not set or set to an unknown value, this
algorithm is used.
•none: no sort is done and the order can
change at each run.
OCL_ICD_DEFAULT_PLATFORM
Number of the platform to choose as default platform.
Note that using this environment variable without ensuring the use of a sort
algorithm for platforms is not really useful.
OCL_ICD_DEBUG
If ocl-icd has been compiled with debug support, you can
set this environment variable to a value where each bit display some kind of
informations. Defined values are:
•1: warnings (enabled by default if debug
support is present and OCL_ICD_DEBUG is not set)
•2: informative messages
•4: entering/exiting for some OpenCL
functions
•8: dump of the internal structure of
loaded ICDs
OCL_ICD_DEBUG is mainly useful for ocl-icd development
itself and/or for ICD development.
Author.
Visit the GSP FreeBSD Man Page Interface.