git.oblomov.eu Git - ocl-icd/blob - doc/libOpenCL.7.txt

   1 libOpenCL(7)
   2 ============
   3 Vincent Danjean <Vincent.Danjean@ens-lyon.org>
   4 :Author Initials: VD
   5 :toc:
   6 :icons:
   7 :numbered:
   8
   9 NAME
  10 ----
  11 libOpenCL, libOpenCL.so - OCL-ICD implementation of OpenCL ICD loader
  12
  13 DESCRIPTION
  14 -----------
  15 `libOpenCL.so` is the library linked by OpenCL programs. It does not contains
  16 any OpenCL implementation itself, but merly act as a dispatcher to real OpenCL
  17 implementations provided as OpenCL Installable Client Driver (ICD).
  18 An ICD loader should be able to load ICDs provided by any vendors.
  19
  20 According to OpenCL specifications from Khronos (see [Kronos]), the ICD Loader
  21 looks for files into '`/etc/OpenCL/vendors/`' directory and, for each file
  22 whose name ends with '`.icd`', the ICD Loader loads with **dlopen**(3) the
  23 shared library whose name is on the first line of the '`.icd`' file.
  24
  25 Shared library name in ".icd" files can have its path, or it can be a plain
  26 filename. In the latter case, the ICD shared library will be look for into the
  27 standard dynamic loader paths.
  28
  29 ENVIRONNEMENT
  30 -------------
  31 Some environment variables can be used modify the default behavior of
  32 libOpenCL.
  33
  34 *OCL_ICD_VENDORS*::
  35 This variable allows one to change the way ICD are searched on the system.
  36 Several cases are considerated:
  37
  38 a. if *$OCL_ICD_VENDORS* is a directory path, then this path replaces the
  39   "/etc/OpenCL/vendors" path in the standard behavior: the loader will use the
  40   '`.icd`' files in this directory;
  41 b. else, if *$OCL_ICD_VENDORS* ends with '`.icd`', libOpenCL.so will only load
  42   the ICD whose shared library name is wrote into the specified ".icd"
  43   file;
  44   +
  45   If there is no slash into
  46   *$OCL_ICD_VENDORS*, libOpenCL.so will first try to use
  47   '`/etc/OpenCL/vendors/`'*$OCL_ICD_VENDORS*. If this fail, it uses
  48   *$OCL_ICD_VENDORS* (as a relative or absolute file name path).
  49 c. else libOpenCL.so will try to load *$OCL_ICD_VENDORS* as the ICD shared
  50   library itself (i.e. to load it directly with **dlopen**(3)).
  51
  52 *OCL_ICD_ASSUME_ICD_EXTENSION*::
  53   If set, contrary the the Kronos specification, the loader will not check that
  54   the loaded ICDs declare the `cl_khr_icd` extension. You may need to define
  55   this environment variable if you are using the Intel ICD toguether with
  56   *optirun*(1). Else, a bug into the Intel ICD will make the application crash.
  57
  58 *OCL_ICD_DEBUG*::
  59 +
  60 --
  61 If ocl-icd has been compiled with debug support, you can set this environment
  62 variable to a value where each bit display some kind of informations. Defined
  63 values are:
  64
  65 * *1*: warnings (enabled by default if debug support is present and
  66   *OCL_ICD_DEBUG* is not set)
  67 * *2*: informative messages
  68 * *4*: entering/exiting for some OpenCL functions
  69 * *8*: dump of the internal structure of loaded ICDs
  70
  71 *OCL_ICD_DEBUG* is mainly useful for ocl-icd development itself and/or for ICD
  72 development.
  73 --
  74
  75 SEE ALSO
  76 --------
  77 http://www.khronos.org/registry/cl/[Kronos OpenCL registry website]