This is a specification for how the Vulkan loader should identify Vulkan | |
installable client drivers (ICDs) and layers on Linux systems. This is | |
designed for production installation of Vulkan ICDs and layers. The design is | |
shown first for ICDs, and then the variation for layers will be discussed. | |
1. Installable Client Drivers: | |
1.1. Properly-Installed ICDs | |
In order to find properly-installed ICDs, the Vulkan loader will scan the files | |
in the following Linux directories: | |
/usr/share/vulkan/icd.d | |
/etc/vulkan/icd.d | |
These directories will contain text information files (a.k.a. "manifest | |
files"), that use a JSON format (NOTE: The JSON in this version of the | |
specification is for illustration purposes, and isn’t completely valid yet). | |
The Vulkan loader will open each info file to obtain the name or pathname of an | |
ICD shared library (“.so”) file. For example: | |
{ | |
"file_format_version": "1.0.0", | |
"ICD": { | |
"library_path": "path to ICD library", | |
"abi_versions": "1.0.0" | |
} | |
} | |
The “library_path” specifies either a filename, a relative pathname or a full | |
pathname to an ICD shared library file, which the loader will attempt to load | |
using dlopen(). If the layer is specified via a relative pathname, it is | |
relative to the path of the info file. If the ICD is specified via a filename, | |
the shared library lives in the following system directory: | |
/$libdir/vulkan/icd | |
where $libdir specifies where libraries reside on the given Linux distribution | |
(e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or | |
“/usr/lib64” on 64-bit Red Hat-based systems). | |
The “file_format_version” provides a major.minor.patch version number in case | |
the format of the text information file changes in the future. If the same ICD | |
shared library supports multiple, incompatible versions of text info file | |
format versions, it must have multiple text info files (all of which may point | |
to the same shared library). | |
The “abi_versions” specifies a colon-separated list of major.minor.patch | |
version numbers of the Vulkan ABI that the shared library (referenced by | |
“library_path”) support. | |
The “/usr/share/vulkan/icd.d” directory is for ICDs that are installed from | |
Linux-distribution-provided packages. The “/etc/vulkan/icd.d” directory is for | |
ICDs that are installed from non-Linux-distribution-provided packages. | |
There are no rules about the name of the text files (except the .json suffix). | |
There are no rules about the name of the ICD shared library files. For | |
example, if the “/usr/share/vulkan/icd.d” directory contain the following | |
files, with the specified contents: | |
Text File Name Text File Contents | |
-------------------------------------------------------------------------- | |
vk_vendora.json { "ICD": { "library_path": "vendora.so" }} | |
vendorb_vk.json { "ICD": { "library_path": "vendorb_vulkan_icd.so" }} | |
vendorc_icd.json { "ICD": { "library_path": "/usr/lib/VENDORC/icd.so" }} | |
then the loader will open the three files mentioned in the “Text File Contents” | |
column, and then try to load and use the three shared libraries mentioned | |
indicated by the ICD.library_path value. | |
1.2. Using Pre-Production ICDs | |
IHV developers (and sometimes other developers) need to use special, | |
pre-production ICDs. In some cases, a pre-production ICD may be in an | |
installable package. In other cases, a pre-production ICD may simply be a | |
shared library in the developer’s build tree. In this latter case, we want to | |
allow developers to point to such an ICD without modifying the | |
properly-installed ICD(s) on their system. | |
This need is met with the use of the “VK_ICD_FILENAMES” environment variable, | |
which will override the mechanism used for finding properly-installed ICDs. In | |
other words, only the ICDs listed in “VK_ICD_FILENAMES” will be used. | |
The “VK_ICD_FILENAMES” environment variable is a colon-separated list of ICD | |
text information files, containing the following: | |
- A filename (e.g. “libvkicd.json”) in the “/usr/share/vulkan/icd.d“ or | |
“/etc/vulkan/icd.d“ system directories | |
- A full pathname (e.g. “/my_build/my_icd.json”) | |
Typically, “VK_ICD_FILENAMES” will only contain a full pathname to one info | |
file for a developer-built ICD. A colon is only used if more than one ICD is | |
listed. | |
For example, if a developer wants to refer to one ICD that they built, they | |
could set the “VK_ICD_FILENAMES” environment variable to: | |
/my_build/my_icd.json | |
If a developer wants to refer to two ICDs, one of which is a properly-installed | |
ICD, they can use the name of the text file in the system directory: | |
vendorc_vulkan.json:/my_build/my_icd.json | |
Notice the colon between “vendorc_vulkan.json” and “/my_build/my_icd.json”. | |
NOTE: this environment variable will be ignored for suid programs. | |
2. Layers: | |
2.1. Properly-Installed Layers | |
In order to find properly-installed layers, the Vulkan loader will use a | |
similar mechanism as used for ICDs. Text information files, that use a JSON | |
format, are read in order to identify the names and attributes of layers and | |
their extensions. The use of text info files allows the loader to avoid | |
loading any shared library files when the application does not query nor | |
request any extensions. Layers and extensions have additional complexity, and | |
so their info files contain more information than ICD info files. For example, | |
a layer shared library file may contain multiple layers/extensions (perhaps | |
even an ICD). | |
The Vulkan loader will scan the files in the following Linux directories: | |
/usr/share/vulkan/explicit_layer.d | |
/usr/share/vulkan/implicit_layer.d | |
/etc/vulkan/explicit_layer.d | |
/etc/vulkan/implicit_layer.d | |
Explicit layers are those which are enabled by an application (e.g. with the | |
vkCreateInstance function), or by an environment variable (see below). | |
Implicit layers are those which are enabled by their existence. For example, | |
certain application environments (e.g. Steam or an automotive infotainment | |
system) may have layers which they always want enabled for all applications | |
that they start. Other implicit layers may be for all applications started | |
on a given system (e.g. layers that overlay frames-per-second). Implicit | |
layers are enabled automatically, whereas explicit | |
layers must be enabled explicitly. What distinguishes a layer as implicit or | |
explicit is by which directory its layer information file exists in. | |
The “/usr/share/vulkan/*_layer.d” directories are for ICDs that are installed | |
from Linux-distribution-provided packages. The “/etc/vulkan/*_layer.d” | |
directories are for ICDs that are installed from | |
non-Linux-distribution-provided packages. | |
The information file is in the JSON format and contains the following | |
information: | |
- (required) “file_format_version” – same as for ICDs, except that the format | |
version can vary independently for ICDs and layers. | |
- (required) "name" - layer name | |
- (required) "type" - which layer chains should the layer be activated on. | |
Allowable values are "INSTANCE", "DEVICE", "GLOBAL". Global means activate | |
on both device and instance chains. | |
- (required) “library_path” - filename / full path / relative path to the text | |
file | |
- (required) “abi_versions” – same as for ICDs. | |
- (required) “implementation_version” – layer code version. | |
- (required) “description” – informative decription of the layer. | |
- (optional) extension and it's “name” - e.g."instance_extensions”{ DEBUG_REPORT } | |
- (optional) extension “version” - extension version (formatted as | |
major.minor.patch). | |
- (sometimes required) “functions” - mapping list of function entry points. If | |
multiple layers exist within the same shared library (or if a layer is in the | |
same shared library as an ICD), this must be specified to allow each layer to | |
have its own vkGet*ProcAddr entrypoints that can be found by the loader. At | |
this time, only the following two functions are required: | |
- “vkGetInstanceProcAddr” name | |
- “vkGetDeviceProcAddr” name | |
- (optional for implicit layers) “enable_environment” requirement(s) - | |
environment variable and value required to enable an implicit layer. This | |
environment variable (which should vary with each "version" of the layer, as | |
in "ENABLE_LAYER_FOO_1_0_0") must be set to the given value or else the | |
implicit layer is not loaded. This is for application environments | |
(e.g. Steam) which want to enable a layer(s) only for applications that they | |
launch, and allows for applications run outside of an application environment | |
to not get that implicit layer(s). | |
- (required for implicit layers) “disable_environment” requirement(s) - | |
environment variable and value required to disable an implicit layer. Note: | |
in rare cases of an application not working with an implicit layer, the | |
application can set this environment variable (before calling Vulkan | |
functions) in order to "blacklist" the layer. This environment variable | |
(which should vary with each "version" of the layer, as in | |
"DISABLE_LAYER_FOO_1_0_0") must be set (not particularly to any value). If | |
both the "enable_environment" and "disable_environment" variables are set, | |
the implicit layer is disabled. | |
For example: | |
{ | |
“file_format_version” : “1.0.0”, | |
“layer”: { | |
"name": "OverlayLayer", | |
"type": "DEVICE", | |
"library_path": "libvkOverlayLayer.so", | |
“abi_versions” : “1.0.0:1.1.0”, | |
“implementation_version” : “0.9.3”, | |
“description” : “LunarG HUD layer”, | |
“functions”: { | |
“vkGetInstanceProcAddr”: “Overlaylayer_GetInstanceProcAddr”, | |
“vkGetDeviceProcAddr”: “OverlayLayer_GetDeviceProcAddr” | |
}, | |
"instance_extensions”: [ | |
{ | |
“name”: “DEBUG_REPORT”, | |
“version”: “1.0.0” | |
}, | |
{ | |
“name”: “DEBUG_X”, | |
“version”: “1.0.0” | |
} | |
], | |
"device_extensions”: [ | |
{ | |
“name”: “DEBUG_MARKER”, | |
“version”: “1.0.0” | |
} | |
], | |
“disable_environment”: { | |
“DISABLE_LAYER_OVERLAY_1_0_0”: “” | |
} | |
} | |
} | |
The “library_path” specifies either a filename, a relative pathname, or a full | |
pathname to a layer shared library (“.so”) file, which the loader will attempt | |
to load using dlopen(). If the layer is specified via a relative pathname, it | |
is relative to the path of the info file (e.g. for cases when an application | |
provides a layer that is in the same directory hierarchy as the rest of the | |
application files). If the layer is specified via a filename, the shared | |
library lives in the following system directory: | |
/$libdir/vulkan/layer | |
where $libdir specifies where libraries reside on the given Linux distribution | |
(e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or | |
“/usr/lib64” on 64-bit Red Hat-based systems). | |
There are no rules about the name of the text files (except the .json suffix). | |
There are no rules about the name of the layer shared library files. | |
2.2. Using Pre-Production Layers | |
As with ICDs, developers may need to use special, pre-production layers, | |
without modifying the properly-installed layers. | |
This need is met with the use of the “VK_LAYER_DIRS” environment variable, | |
which will override the mechanism using for finding properly-installed layers. | |
Because many layers may exist on a system, this environment variable is a | |
colon-separated list of directories that contain layer info files. Only the | |
directories listed in “VK_LAYER_DIRS” will be scanned for info files. Each | |
colon-separated entry is: | |
- The full pathname of a directory containing layer info files | |
In addition to overriding the mechanism for finding layers, the following | |
environment variables are used to select one or more layers/extensions | |
(respectively) to explicitly enable: | |
- “VK_INSTANCE_LAYERS” for instance/global layers/extensions, enabled at | |
vkCreateInstance time | |
- “VK_DEVICE_LAYERS” for device layers/extensions, enabled at vkCreateDevice | |
time | |
These are colon-separated lists of extension names, as listed in the “name” | |
field of the info file. The loader will load all layers/extensions that match | |
the given extension name(s), ignoring the “version” fields. | |
NOTE: these environment variables will be ignored for suid programs. |