Jon Ashburn | 6121daf | 2015-07-24 09:20:11 -0600 | [diff] [blame] | 1 | This is a specification for how the Vulkan loader should identify Vulkan
|
| 2 | installable client drivers (ICDs) and layers on Linux systems. This is
|
| 3 | designed for production installation of Vulkan ICDs and layers. The design is
|
| 4 | shown first for ICDs, and then the variation for layers will be discussed.
|
Jon Ashburn | 4a511f1 | 2015-07-16 10:54:55 -0600 | [diff] [blame] | 5 |
|
| 6 |
|
| 7 | 1. Installable Client Drivers:
|
| 8 |
|
| 9 |
|
| 10 | 1.1. Properly-Installed ICDs
|
| 11 |
|
| 12 | In order to find properly-installed ICDs, the Vulkan loader will scan the files
|
| 13 | in the following Linux directories:
|
| 14 |
|
| 15 | /usr/share/vulkan/icd.d
|
| 16 | /etc/vulkan/icd.d
|
| 17 |
|
| 18 | These directories will contain text information files (a.k.a. "manifest
|
Jon Ashburn | 6121daf | 2015-07-24 09:20:11 -0600 | [diff] [blame] | 19 | files"), that use a JSON format (NOTE: The JSON in this version of the
|
| 20 | specification is for illustration purposes, and isn’t completely valid yet).
|
| 21 | The Vulkan loader will open each info file to obtain the name or pathname of an
|
| 22 | ICD shared library (“.so”) file. For example:
|
Jon Ashburn | 4a511f1 | 2015-07-16 10:54:55 -0600 | [diff] [blame] | 23 |
|
| 24 | {
|
| 25 | "file_format_version": "1.0.0",
|
| 26 | "ICD": {
|
| 27 | "library_path": "path to ICD library",
|
| 28 | "abi_versions": "1.0.0"
|
| 29 | }
|
| 30 | }
|
| 31 |
|
| 32 | The “library_path” specifies either a filename, a relative pathname or a full
|
| 33 | pathname to an ICD shared library file, which the loader will attempt to load
|
| 34 | using dlopen(). If the layer is specified via a relative pathname, it is
|
| 35 | relative to the path of the info file. If the ICD is specified via a filename,
|
| 36 | the shared library lives in the following system directory:
|
| 37 |
|
| 38 | /$libdir/vulkan/icd
|
| 39 |
|
| 40 | where $libdir specifies where libraries reside on the given Linux distribution
|
| 41 | (e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or
|
| 42 | “/usr/lib64” on 64-bit Red Hat-based systems).
|
| 43 |
|
| 44 | The “file_format_version” provides a major.minor.patch version number in case
|
| 45 | the format of the text information file changes in the future. If the same ICD
|
| 46 | shared library supports multiple, incompatible versions of text info file
|
| 47 | format versions, it must have multiple text info files (all of which may point
|
| 48 | to the same shared library).
|
| 49 |
|
| 50 | The “abi_versions” specifies a colon-separated list of major.minor.patch
|
| 51 | version numbers of the Vulkan ABI that the shared library (referenced by
|
| 52 | “library_path”) support.
|
| 53 |
|
| 54 | The “/usr/share/vulkan/icd.d” directory is for ICDs that are installed from
|
| 55 | Linux-distribution-provided packages. The “/etc/vulkan/icd.d” directory is for
|
| 56 | ICDs that are installed from non-Linux-distribution-provided packages.
|
| 57 |
|
| 58 | There are no rules about the name of the text files (except the .json suffix).
|
| 59 | There are no rules about the name of the ICD shared library files. For
|
| 60 | example, if the “/usr/share/vulkan/icd.d” directory contain the following
|
| 61 | files, with the specified contents:
|
| 62 |
|
| 63 | Text File Name Text File Contents
|
| 64 | --------------------------------------------------------------------------
|
| 65 | vk_vendora.json { "ICD": { "library_path": "vendora.so" }}
|
| 66 | vendorb_vk.json { "ICD": { "library_path": "vendorb_vulkan_icd.so" }}
|
| 67 | vendorc_icd.json { "ICD": { "library_path": "/usr/lib/VENDORC/icd.so" }}
|
| 68 |
|
Jon Ashburn | 6121daf | 2015-07-24 09:20:11 -0600 | [diff] [blame] | 69 | then the loader will open the three files mentioned in the “Text File Contents”
|
| 70 | column, and then try to load and use the three shared libraries mentioned
|
Jon Ashburn | 4a511f1 | 2015-07-16 10:54:55 -0600 | [diff] [blame] | 71 | indicated by the ICD.library_path value.
|
| 72 |
|
| 73 |
|
| 74 | 1.2. Using Pre-Production ICDs
|
| 75 |
|
| 76 | IHV developers (and sometimes other developers) need to use special,
|
| 77 | pre-production ICDs. In some cases, a pre-production ICD may be in an
|
| 78 | installable package. In other cases, a pre-production ICD may simply be a
|
| 79 | shared library in the developer’s build tree. In this latter case, we want to
|
| 80 | allow developers to point to such an ICD without modifying the
|
| 81 | properly-installed ICD(s) on their system.
|
| 82 |
|
| 83 | This need is met with the use of the “VK_ICD_FILENAMES” environment variable,
|
| 84 | which will override the mechanism used for finding properly-installed ICDs. In
|
| 85 | other words, only the ICDs listed in “VK_ICD_FILENAMES” will be used.
|
| 86 |
|
| 87 | The “VK_ICD_FILENAMES” environment variable is a colon-separated list of ICD
|
| 88 | text information files, containing the following:
|
| 89 |
|
| 90 | - A filename (e.g. “libvkicd.json”) in the “/usr/share/vulkan/icd.d“ or
|
| 91 | “/etc/vulkan/icd.d“ system directories
|
| 92 | - A full pathname (e.g. “/my_build/my_icd.json”)
|
| 93 |
|
| 94 | Typically, “VK_ICD_FILENAMES” will only contain a full pathname to one info
|
| 95 | file for a developer-built ICD. A colon is only used if more than one ICD is
|
| 96 | listed.
|
| 97 |
|
| 98 | For example, if a developer wants to refer to one ICD that they built, they
|
| 99 | could set the “VK_ICD_FILENAMES” environment variable to:
|
| 100 |
|
| 101 | /my_build/my_icd.json
|
| 102 |
|
| 103 | If a developer wants to refer to two ICDs, one of which is a properly-installed
|
| 104 | ICD, they can use the name of the text file in the system directory:
|
| 105 |
|
| 106 | vendorc_vulkan.json:/my_build/my_icd.json
|
| 107 |
|
| 108 | Notice the colon between “vendorc_vulkan.json” and “/my_build/my_icd.json”.
|
| 109 |
|
| 110 | NOTE: this environment variable will be ignored for suid programs.
|
| 111 |
|
| 112 |
|
| 113 | 2. Layers:
|
| 114 |
|
| 115 |
|
| 116 | 2.1. Properly-Installed Layers
|
| 117 |
|
| 118 | In order to find properly-installed layers, the Vulkan loader will use a
|
| 119 | similar mechanism as used for ICDs. Text information files, that use a JSON
|
| 120 | format, are read in order to identify the names and attributes of layers and
|
| 121 | their extensions. The use of text info files allows the loader to avoid
|
| 122 | loading any shared library files when the application does not query nor
|
| 123 | request any extensions. Layers and extensions have additional complexity, and
|
| 124 | so their info files contain more information than ICD info files. For example,
|
| 125 | a layer shared library file may contain multiple layers/extensions (perhaps
|
| 126 | even an ICD).
|
| 127 |
|
| 128 | The Vulkan loader will scan the files in the following Linux directories:
|
| 129 |
|
| 130 | /usr/share/vulkan/explicit_layer.d
|
| 131 | /usr/share/vulkan/implicit_layer.d
|
| 132 | /etc/vulkan/explicit_layer.d
|
| 133 | /etc/vulkan/implicit_layer.d
|
| 134 |
|
| 135 | Explicit layers are those which are enabled by an application (e.g. with the
|
| 136 | vkCreateInstance function), or by an environment variable (see below).
|
| 137 | Implicit layers are those which are enabled by their existence. For example,
|
| 138 | certain application environments (e.g. Steam or an automotive infotainment
|
| 139 | system) may have layers which they always want enabled for all applications
|
| 140 | that they start. Other implicit layers may be for all applications started
|
| 141 | on a given system (e.g. layers that overlay frames-per-second). Implicit
|
| 142 | layers are enabled automatically, whereas explicit
|
| 143 | layers must be enabled explicitly. What distinguishes a layer as implicit or
|
| 144 | explicit is by which directory its layer information file exists in.
|
| 145 |
|
| 146 | The “/usr/share/vulkan/*_layer.d” directories are for ICDs that are installed
|
| 147 | from Linux-distribution-provided packages. The “/etc/vulkan/*_layer.d”
|
| 148 | directories are for ICDs that are installed from
|
| 149 | non-Linux-distribution-provided packages.
|
| 150 |
|
| 151 | The information file is in the JSON format and contains the following
|
| 152 | information:
|
| 153 |
|
| 154 | - (required) “file_format_version” – same as for ICDs, except that the format
|
| 155 | version can vary independently for ICDs and layers.
|
| 156 | - (required) "name" - layer name
|
| 157 | - (required) "type" - which layer chains should the layer be activated on.
|
| 158 | Allowable values are "INSTANCE", "DEVICE", "GLOBAL". Global means activate
|
| 159 | on both device and instance chains.
|
| 160 | - (required) “library_path” - filename / full path / relative path to the text
|
| 161 | file
|
| 162 | - (required) “abi_versions” – same as for ICDs.
|
| 163 | - (required) “implementation_version” – layer code version.
|
| 164 | - (required) “description” – informative decription of the layer.
|
| 165 | - (optional) extension and it's “name” - e.g."instance_extensions”{ DEBUG_REPORT }
|
| 166 | - (optional) extension “version” - extension version (formatted as
|
| 167 | major.minor.patch).
|
| 168 | - (sometimes required) “functions” - mapping list of function entry points. If
|
| 169 | multiple layers exist within the same shared library (or if a layer is in the
|
| 170 | same shared library as an ICD), this must be specified to allow each layer to
|
| 171 | have its own vkGet*ProcAddr entrypoints that can be found by the loader. At
|
| 172 | this time, only the following two functions are required:
|
| 173 | - “vkGetInstanceProcAddr” name
|
| 174 | - “vkGetDeviceProcAddr” name
|
| 175 | - (optional for implicit layers) “enable_environment” requirement(s) -
|
| 176 | environment variable and value required to enable an implicit layer. This
|
| 177 | environment variable (which should vary with each "version" of the layer, as
|
| 178 | in "ENABLE_LAYER_FOO_1_0_0") must be set to the given value or else the
|
| 179 | implicit layer is not loaded. This is for application environments
|
| 180 | (e.g. Steam) which want to enable a layer(s) only for applications that they
|
| 181 | launch, and allows for applications run outside of an application environment
|
| 182 | to not get that implicit layer(s).
|
| 183 | - (required for implicit layers) “disable_environment” requirement(s) -
|
| 184 | environment variable and value required to disable an implicit layer. Note:
|
| 185 | in rare cases of an application not working with an implicit layer, the
|
| 186 | application can set this environment variable (before calling Vulkan
|
| 187 | functions) in order to "blacklist" the layer. This environment variable
|
| 188 | (which should vary with each "version" of the layer, as in
|
| 189 | "DISABLE_LAYER_FOO_1_0_0") must be set (not particularly to any value). If
|
| 190 | both the "enable_environment" and "disable_environment" variables are set,
|
| 191 | the implicit layer is disabled.
|
| 192 |
|
Jon Ashburn | 6121daf | 2015-07-24 09:20:11 -0600 | [diff] [blame] | 193 | For example:
|
Jon Ashburn | 4a511f1 | 2015-07-16 10:54:55 -0600 | [diff] [blame] | 194 |
|
| 195 | {
|
| 196 | “file_format_version” : “1.0.0”,
|
| 197 | “layer”: {
|
| 198 | "name": "OverlayLayer",
|
| 199 | "type": "DEVICE",
|
| 200 | "library_path": "libvkOverlayLayer.so",
|
| 201 | “abi_versions” : “1.0.0:1.1.0”,
|
| 202 | “implementation_version” : “0.9.3”,
|
| 203 | “description” : “LunarG HUD layer”,
|
| 204 | “functions”: {
|
| 205 | “vkGetInstanceProcAddr”: “Overlaylayer_GetInstanceProcAddr”,
|
| 206 | “vkGetDeviceProcAddr”: “OverlayLayer_GetDeviceProcAddr”
|
| 207 | },
|
| 208 | "instance_extensions”: [
|
| 209 | {
|
| 210 | “name”: “DEBUG_REPORT”,
|
| 211 | “version”: “1.0.0”
|
| 212 | },
|
| 213 | {
|
| 214 | “name”: “DEBUG_X”,
|
| 215 | “version”: “1.0.0”
|
| 216 | }
|
| 217 | ],
|
| 218 | "device_extensions”: [
|
| 219 | {
|
| 220 | “name”: “DEBUG_MARKER”,
|
| 221 | “version”: “1.0.0”
|
| 222 | }
|
| 223 | ],
|
| 224 | “disable_environment”: {
|
| 225 | “DISABLE_LAYER_OVERLAY_1_0_0”: “”
|
| 226 | }
|
| 227 | }
|
| 228 | }
|
| 229 |
|
| 230 | The “library_path” specifies either a filename, a relative pathname, or a full
|
| 231 | pathname to a layer shared library (“.so”) file, which the loader will attempt
|
| 232 | to load using dlopen(). If the layer is specified via a relative pathname, it
|
| 233 | is relative to the path of the info file (e.g. for cases when an application
|
| 234 | provides a layer that is in the same directory hierarchy as the rest of the
|
| 235 | application files). If the layer is specified via a filename, the shared
|
| 236 | library lives in the following system directory:
|
| 237 |
|
| 238 | /$libdir/vulkan/layer
|
| 239 |
|
| 240 | where $libdir specifies where libraries reside on the given Linux distribution
|
| 241 | (e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or
|
| 242 | “/usr/lib64” on 64-bit Red Hat-based systems).
|
| 243 |
|
| 244 | There are no rules about the name of the text files (except the .json suffix).
|
| 245 | There are no rules about the name of the layer shared library files.
|
| 246 |
|
| 247 |
|
| 248 | 2.2. Using Pre-Production Layers
|
| 249 |
|
| 250 | As with ICDs, developers may need to use special, pre-production layers,
|
| 251 | without modifying the properly-installed layers.
|
| 252 |
|
| 253 | This need is met with the use of the “VK_LAYER_DIRS” environment variable,
|
| 254 | which will override the mechanism using for finding properly-installed layers.
|
| 255 | Because many layers may exist on a system, this environment variable is a
|
| 256 | colon-separated list of directories that contain layer info files. Only the
|
| 257 | directories listed in “VK_LAYER_DIRS” will be scanned for info files. Each
|
| 258 | colon-separated entry is:
|
| 259 |
|
| 260 | - The full pathname of a directory containing layer info files
|
| 261 |
|
| 262 | In addition to overriding the mechanism for finding layers, the following
|
| 263 | environment variables are used to select one or more layers/extensions
|
| 264 | (respectively) to explicitly enable:
|
| 265 |
|
| 266 | - “VK_INSTANCE_LAYERS” for instance/global layers/extensions, enabled at
|
| 267 | vkCreateInstance time
|
| 268 |
|
| 269 | - “VK_DEVICE_LAYERS” for device layers/extensions, enabled at vkCreateDevice
|
| 270 | time
|
| 271 |
|
| 272 | These are colon-separated lists of extension names, as listed in the “name”
|
| 273 | field of the info file. The loader will load all layers/extensions that match
|
| 274 | the given extension name(s), ignoring the “version” fields.
|
| 275 |
|
| 276 | NOTE: these environment variables will be ignored for suid programs.
|