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