Skip to content

Please document EGL vendor ICD search path

Created by: smcv

I'm currently working on some code that needs to mirror EGL vendor ICDs from the host system into a container, so I need to be able to enumerate EGL vendor ICDs on the host system in the same way that GLVND would.

The current documentation in README is:

In order to find the available vendor libraries, each vendor provides a JSON file in a well-known directory, similar to how Vulkan ICD's are loaded.

Here is what I've been able to piece together from the implementation, which can perhaps be a basis for more formal documentation:

ICD discovery

  • If the environment variable __EGL_VENDOR_LIBRARY_FILENAMES is set, it is a colon-separated list of JSON filenames. The ICDs described in those files are loaded, in the order given. No other ICDs are loaded.

  • Otherwise, if the environment variable __EGL_VENDOR_LIBRARY_DIRS is set, it is a colon-separated list of directories. Each directory in turn is scanned for files named *.json and the ICDs that they describe are loaded. Files in the same directory are loaded in arbitrary order.

  • If neither environment variable is set, GLVND behaves as though __EGL_VENDOR_LIBRARY_DIRS had been set to ${sysconfdir}/glvnd/egl_vendor.d:${datadir}/glvnd/egl_vendor.d, replacing ${sysconfdir} and ${datadir} with the values that were set when GLVND was compiled.

  • Each JSON file describing an ICD must have a JSON object at top level.

    • The key file_format_version must have a string value giving the file format major.minor.micro version number. This specification describes version 1.0.0. Versions 1.0.x are required to be compatible with this specification, in the sense that an EGL loader that only implements file format version 1.0.0 will load all version 1.0.x JSON files successfully. Different major and minor versions might require loader changes.
    • The key ICD must have an object value.
      • In the ICD object, the key library_path must have a string value.
        • If the library path is a bare filename with no directory separators, for example libEGL_mesa.so.0, the loader is expected to search for it in the system's default runtime library directories.
        • If the library path is an absolute path, for example /opt/myvendor/libEGL_myvendor.so, the loader is expected to load the ICD from that absolute path.
        • If the library path is a relative path, for example ../lib/libEGL_myvendor.so, [...TBD...]

ICD installation

OS vendors should install JSON files into ${datadir}/glvnd/egl_vendor.d where ${datadir} is the data directory with which they configured GLVND, normally /usr/share.

Third-party vendors and sysadmins should usually install JSON files into /etc/glvnd/egl_vendor.d, on the assumption that GLVND was configured with ${sysconfdir} set to /etc.

If a vendor installs ICD libraries into one of the system's default runtime library directories, they must install a JSON file referencing the ICD library by either its absolute path or its bare filename.

If a vendor installs ICD libraries into a non-standard directory, they must install a JSON file referencing the ICD library by its absolute path.

If a vendor installs matching ICD libraries for more than one ABI (for example 32- and 64-bit versions), each library has the same name, and each library is in a directory searched by default by the runtime linker and referenced by its bare filename, then they may install a single JSON file to describe all of those ICD libraries. For example, Mesa on Debian installs /usr/lib/x86_64-linux-gnu/libEGL_mesa.so.0 and /usr/lib/i386-linux-gnu/libEGL_mesa.so.0, which can both be described by a JSON file with "library_path": "libEGL_mesa.so.0". Similarly, Mesa on Arch Linux installs 64-bit /usr/lib/libEGL_mesa.so.0 and 32-bit /usr/lib32/libEGL_mesa.so.0, with a similar JSON file, while some other distributions use lib64 for 64-bit libraries.

Questions

  • If the library_path is a relative path containing /, for example ../libEGL_myvendor.so, what is it relative to? At the moment it gets passed directly to dlopen(), so the answer is the current working directory of the process that loaded libEGL, which I suspect is not what anyone wants. The Vulkan loader interprets relative paths as relative to the JSON file, which I think is probably more useful, but perhaps it's too late to change this in EGL?

  • Should the search path include more directories? Some obvious candidates include:

    • /etc/glvnd/egl_vendor.d, even if GLVND was installed with a different ${sysconfdir}
    • /usr/share/glvnd/egl_vendor.d, even if GLVND was installed with a different ${datadir}
    • the ${libdir} (which is very platform-dependent, and might include things like lib64 or lib/x86_64-linux-gnu)
    • the XDG base directories (some of which are used in the reference Vulkan loader, although it seems to be searching them in a weird order and not entirely following the spec)

  • Is it correct to say that third-party vendors should install to /etc/glvnd/egl_vendor.d? That effectively means they're assuming that GLVND's ${sysconfdir} is /etc (which seems likely to be correct in practice).