libOpenCL(7)
============
Vincent Danjean <Vincent.Danjean@ens-lyon.org>
:Author Initials: VD
:revdate: 2015-06-08
:footer-style: revdate
:toc:
:icons:
:numbered:

NAME
----
libOpenCL, libOpenCL.so - OCL-ICD implementation of OpenCL ICD loader

DESCRIPTION
-----------
`libOpenCL.so` is the library linked by OpenCL programs. It does not contains
any OpenCL implementation itself, but merly 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.


@@OFFICIAL: According to OpenCL specifications from Khronos (see [Khronos]), the
@@CUSTOM: The
ICD Loader looks for files into '`@OCL_ICD_VENDORDIR@`' 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.
@@CUSTOM: According to OpenCL specifications from Khronos (see
@@CUSTOM: [Khronos]), the default path for this purpose is
@@CUSTOM: '`/etc/OpenCL/vendors`', but this OCL-ICD version has been
@@CUSTOM: 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.

ENVIRONMENT
-------------
Some environment variables can be used modify the default behavior of
libOpenCL.

*OPENCL_VENDOR_PATH*::
This variable allows one to modify the defaut '`@OCL_ICD_VENDORDIR@`' 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:

a. if *$OCL_ICD_VENDORS* is a directory path, then this path replaces the
  "@OCL_ICD_VENDORDIR@" path in the standard behavior: the loader will use the
  '`.icd`' files in this directory;
b. 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
  '`@OCL_ICD_VENDORDIR@`'*$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).
c. 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)).

*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 defaut 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.
--

SEE ALSO
--------
\\http://www.khronos.org/registry/cl/[Khronos OpenCL registry website]