LIBOPENCL(7)

💖 LIBOPENCL(7): libOpenCL, libOpenCL.so — the ICD loader bestie 💖

OCL-ICD implementation of OpenCL ICD loader, but make it a group chat. Every detail stays, no cap. 💅

🌸 NAME 🌸

• libOpenCL, libOpenCL.so — OCL-ICD implementation of OpenCL ICD loader.

✨ DESCRIPTION ✨

libOpenCL.so is the library linked by OpenCL programs. It does not contain any OpenCL implementation itself, but merely acts 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.

According to OpenCL specifications from Khronos (see [Khronos]), the ICD Loader looks for files in the /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.

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 in the standard dynamic library loader paths.

🦋 ENVIRONMENT 🦋

Some environment variables can be used to modify the default behavior of libOpenCL. Bestie, this is where the customization lives. 🫶

• OPENCL_VENDOR_PATH — lets you modify the default /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 — lets you change the way ICDs are searched on the system. Several cases are considered:
  1. If $OCL_ICD_VENDORS is a directory path, then this path replaces the /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 written into the specified .icd file.

If there are no slashes in $OCL_ICD_VENDORS, libOpenCL.so will first try to use /etc/OpenCL/vendors/$OCL_ICD_VENDORS (or $OPENCL_VENDOR_PATH/$OCL_ICD_VENDORS if OPENCL_VENDOR_PATH is defined). If this fails or if there are slashes, 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)).

• OCL_ICD_FILENAMES — lets you specify a colon-separated list of ICDs to load, specifying their path.
• OPENCL_LAYERS — lets you specify a colon-separated list of layers to load, specifying their path.
• OPENCL_LAYER_PATH — lets you override the default system layer search path (/etc/OpenCL/layers).
• OCL_ICD_ASSUME_ICD_EXTENSION — if set to a non-empty value, contrary to 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 a not (fully) compliant ICD, or if you are using the Intel ICD together with optirun(1). In the latter case, a bug in 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 — lets you 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_FORCE_LEGACY_TERMINATION — prevents the new deinitialization scheme from taking place. Allows loading legacy layers that do not export clInitLayerWithProperties. Accepts True, true, T, or 1.
• OCL_ICD_DISABLE_DYNAMIC_LIBRARY_UNLOADING — prevents dynamic libraries from being unloaded once successfully loaded. For debugging purposes. Accepts True, true, T, or 1.
• OCL_ICD_DEBUG — if ocl-icd has been compiled with debug support, you can set this environment variable to a value where each bit displays some kind of information. 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 🔥

Khronos OpenCL registry website

👑 AUTHOR 👑

Vincent Danjean <Vincent.Danjean@ens-lyon.org> — Author.

---

💌 cute sign-off: this page is LIBOPENCL(7), dated 2015-06-08 — mwah, bestie 💋