1<!-- markdownlint-disable MD041 --> 2[![Khronos Vulkan][1]][2] 3 4[1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/" 5[2]: https://www.khronos.org/vulkan/ 6 7# Debugging The Vulkan Desktop Loader <!-- omit from toc --> 8[![Creative Commons][3]][4] 9 10<!-- Copyright © 2015-2023 LunarG, Inc. --> 11 12[3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" 13[4]: https://creativecommons.org/licenses/by-nd/4.0/ 14## Table of Contents <!-- omit from toc --> 15 16- [Debugging Issues](#debugging-issues) 17- [Loader Logging](#loader-logging) 18- [Debugging Possible Layer Issues](#debugging-possible-layer-issues) 19 - [Enable Layer Logging](#enable-layer-logging) 20 - [Disable Layers](#disable-layers) 21 - [Selectively Re-enable Layers](#selectively-re-enable-layers) 22- [Allow specific layers to be ignored by VK\_LOADER\_LAYERS\_DISABLE](#allow-specific-layers-to-be-ignored-by-vk_loader_layers_disable) 23- [Debugging Possible Driver Issues](#debugging-possible-driver-issues) 24 - [Enable Driver Logging](#enable-driver-logging) 25 - [Selectively Enable Specific Drivers](#selectively-enable-specific-drivers) 26 27## Debugging Issues 28 29If your application is crashing or behaving weirdly, the loader provides 30several mechanisms for you to debug the issues. 31 32**NOTE**: This functionality is all specific to the desktop Vulkan loader and 33does not work for the Android loader. 34 35## Loader Logging 36 37The Vulkan desktop loader has added logging functionality that can be enabled by 38using the `VK_LOADER_DEBUG` environment variable. 39The results will be output to the standard output, but will also be passed to 40any `VK_EXT_debug_utils` messengers present as well. 41The variable can be set to a comma-delimited list of debug level options which 42include: 43 44 * error Report any errors encountered by 45 the loader 46 * warn Report any warnings encountered by 47 the loader 48 * info Report info-level 49 messages generated by the loader 50 * debug Report debug-level messages generated by the 51 loader 52 * layer Report all layer-specific messages 53 generated by the loader 54 * driver Report all driver-specific messages 55 generated by the loader 56 * all Report all 57 messages generated by the loader (includes all of the above) 58 59If you're not sure where the issue comes from, at least set it to output all 60messages through the "info" level: 61 62``` 63set VK_LOADER_DEBUG=error,warn,info 64``` 65 66Then, you can search the list for any errors or warnings that might provide a 67hint at why you're seeing issues. 68 69For more info on enabling loader logging, refer to the 70[Enable Loader Debug Layer Output](LoaderApplicationInterface.md#enable-loader-debug-layer-output) 71and the 72[Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-variables) 73below. 74 75## Debugging Possible Layer Issues 76 77### Enable Layer Logging 78 79If you suspect a layer issue, set the loader logging to specifically output 80layer messages in addition to warnings and errors: 81 82``` 83set VK_LOADER_DEBUG=error,warn,layer 84``` 85 86Most important layer messages should go out with error or warning levels set, 87but this will provide more layer-specific info as well such as: 88 * What layers are found 89 * Where they were found 90 * If they are implicit, what environment variables can be used to disable them 91 * If there is any incompatibility with a given layer, this could include: 92 * The layer library file (.so/.dll) wasn't found 93 * The layer library is the wrong bit-depth for the executing application 94 (i.e. 32-bit vs 64-bit) 95 * The layer itself doesn't support the application desired version of Vulkan 96 * If any environment variables are disabling any layers 97 98For example, the output of the loader looking for implicit layers may look like 99the following: 100 101``` 102[Vulkan Loader] LAYER: Searching for implicit layer manifest files 103[Vulkan Loader] LAYER: In following locations: 104[Vulkan Loader] LAYER: /home/${USER}/.config/vulkan/implicit_layer.d 105[Vulkan Loader] LAYER: /etc/xdg/vulkan/implicit_layer.d 106[Vulkan Loader] LAYER: /usr/local/etc/vulkan/implicit_layer.d 107[Vulkan Loader] LAYER: /etc/vulkan/implicit_layer.d 108[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d 109[Vulkan Loader] LAYER: /home/${USER}/.local/share/flatpak/exports/share/vulkan/implicit_layer.d 110[Vulkan Loader] LAYER: /var/lib/flatpak/exports/share/vulkan/implicit_layer.d 111[Vulkan Loader] LAYER: /usr/local/share/vulkan/implicit_layer.d 112[Vulkan Loader] LAYER: /usr/share/vulkan/implicit_layer.d 113[Vulkan Loader] LAYER: Found the following files: 114[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/renderdoc_capture.json 115[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamfossilize_i386.json 116[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamfossilize_x86_64.json 117[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamoverlay_i386.json 118[Vulkan Loader] LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamoverlay_x86_64.json 119[Vulkan Loader] LAYER: /usr/share/vulkan/implicit_layer.d/nvidia_layers.json 120[Vulkan Loader] LAYER: /usr/share/vulkan/implicit_layer.d/VkLayer_MESA_device_select.json 121``` 122 123Then, the loading of layer libraries is reported similar to this: 124 125``` 126[Vulkan Loader] DEBUG | LAYER : Loading layer library libVkLayer_khronos_validation.so 127[Vulkan Loader] INFO | LAYER : Insert instance layer VK_LAYER_KHRONOS_validation (libVkLayer_khronos_validation.so) 128[Vulkan Loader] DEBUG | LAYER : Loading layer library libVkLayer_MESA_device_select.so 129[Vulkan Loader] INFO | LAYER : Insert instance layer VK_LAYER_MESA_device_select (libVkLayer_MESA_device_select.so) 130``` 131 132Finally, when the Vulkan instance is created, you can see the full instance 133call-chain from a functional standpoint with output like this: 134 135``` 136[Vulkan Loader] LAYER: vkCreateInstance layer callstack setup to: 137[Vulkan Loader] LAYER: <Application> 138[Vulkan Loader] LAYER: || 139[Vulkan Loader] LAYER: <Loader> 140[Vulkan Loader] LAYER: || 141[Vulkan Loader] LAYER: VK_LAYER_MESA_device_select 142[Vulkan Loader] LAYER: Type: Implicit 143[Vulkan Loader] LAYER: Enabled By: Implicit Layer 144[Vulkan Loader] LAYER: Disable Env Var: NODEVICE_SELECT 145[Vulkan Loader] LAYER: Manifest: /usr/share/vulkan/implicit_layer.d/VkLayer_MESA_device_select.json 146[Vulkan Loader] LAYER: Library: libVkLayer_MESA_device_select.so 147[Vulkan Loader] LAYER: || 148[Vulkan Loader] LAYER: VK_LAYER_KHRONOS_validation 149[Vulkan Loader] LAYER: Type: Explicit 150[Vulkan Loader] LAYER: Enabled By: By the Application 151[Vulkan Loader] LAYER: Manifest: /usr/share/vulkan/explicit_layer.d/VkLayer_khronos_validation.json 152[Vulkan Loader] LAYER: Library: libVkLayer_khronos_validation.so 153[Vulkan Loader] LAYER: || 154[Vulkan Loader] LAYER: <Drivers> 155``` 156 157In this scenario, two layers were used (the same two that were loaded earlier): 158* `VK_LAYER_MESA_device_select` 159* `VK_LAYER_KHRONOS_validation` 160 161This information now shows us that the `VK_LAYER_MESA_device_select` is loaded 162first, followed by `VK_LAYER_KHRONOS_validation` which will then continue into 163any available drivers. 164It also shows that `VK_LAYER_MESA_device_select` is an implicit layer which 165implies that it wasn't directly enabled by the application. 166On the other hand, `VK_LAYER_KHRONOS_validation` is shown as an explicit layer 167which indicates that it was likely enabled by the application. 168 169### Disable Layers 170 171**NOTE:** This functionality is only available with Loaders built with version 1721.3.234 of the Vulkan headers and later. 173 174Sometimes, implicit layers can cause issues with an application. 175Because of this, the next step is to try to disable one or more of the listed 176implicit layers. 177You can use the filtering environment variables 178(`VK_LOADER_LAYERS_ENABLE` and `VK_LOADER_LAYERS_DISABLE`) to selectively enable 179or disable various layers. 180If you're not sure what to do, try disabling all implicit layers manually by 181setting `VK_LOADER_LAYERS_DISABLE` to `~implicit~`. 182 183``` 184 set VK_LOADER_LAYERS_DISABLE=~implicit~ 185``` 186 187This will disable all implicit layers and the loader will report any disabled 188layers to the logging output when layer logging is enabled in the following way: 189 190``` 191[Vulkan Loader] WARNING | LAYER: Implicit layer "VK_LAYER_MESA_device_select" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 192[Vulkan Loader] WARNING | LAYER: Implicit layer "VK_LAYER_AMD_switchable_graphics_64" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 193[Vulkan Loader] WARNING | LAYER: Implicit layer "VK_LAYER_Twitch_Overlay" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 194``` 195 196### Selectively Re-enable Layers 197 198**NOTE:** This functionality is only available with Loaders built with version 1991.3.234 of the Vulkan headers and later. 200 201When trying to diagnose problems caused by layers, it is useful to first disable 202all layers and re-enable each layer individually. 203If the problem reappears, then it is immediately clear which layer is the source 204of the issue. 205 206For example, from the above given list of disabled layers, let’s selectively 207re-enable one: 208 209``` 210set VK_LOADER_LAYERS_DISABLE=~implicit~ 211set VK_LOADER_LAYERS_ENABLE=*AMD* 212``` 213 214This would keep both the "VK_LAYER_MESA_device_select" and 215"VK_LAYER_Twitch_Overlay" layers disabled, while enabling the 216"VK_LAYER_AMD_switchable_graphics_64" layer. 217If everything continues to work, then the evidence seems to suggest the issue is 218likely not related to the AMD layer. 219This would lead to enabling one other layer and trying again: 220 221``` 222set VK_LOADER_LAYERS_DISABLE=~implicit~ 223set VK_LOADER_LAYERS_ENABLE=*AMD*,*twitch* 224``` 225 226And so forth. 227 228For more info on how to use the filtering environment variables, refer to the 229[Layer Filtering](LoaderLayerInterface.md#layer-filtering) section of the 230[LoaderLayerInterface](LoaderLayerInterface.md) document. 231 232## Allow specific layers to be ignored by VK_LOADER_LAYERS_DISABLE 233 234**NOTE:** VK_LOADER_LAYERS_DISABLE is only available with Loaders built with version 2351.3.262 of the Vulkan headers and later. 236 237When using `VK_LOADER_LAYERS_DISABLE` to disable implicit layers, it is possible 238to allow specific layers to be enabled using `VK_LOADER_LAYERS_ENABLE`. 239However, this has the effect of *forcing* layers to be enabled, which is not 240always desired. 241Implicit layers have the ability to only be enabled when a layer specified 242environment variable is set, allow for context dependent enablement. 243`VK_LOADER_LAYERS_ENABLE` ignores that context. 244 245Thus, a different environment variable is needed: `VK_LOADER_LAYERS_ALLOW` 246 247The behavior of `VK_LOADER_LAYERS_ALLOW` is similar to `VK_LOADER_LAYERS_ENABLE` 248except that it does not force a layer to be enabled. 249The way to think about this environment variable is that every layer matching 250`VK_LOADER_LAYERS_ALLOW` is excluded from being forcibly disabled by 251`VK_LOADER_LAYERS_DISABLE`. 252this allows for implicit layers that are context dependent to be enabled 253depending on the relevant context instead of force enabling them. 254 255Example: Disable all implicit layers except for any layers that have steam or 256mesa in their name. 257``` 258set VK_LOADER_LAYERS_DISABLE=~implicit~ 259set VK_LOADER_LAYERS_ALLOW=*steam*,*Mesa* 260``` 261 262## Debugging Possible Driver Issues 263 264### Enable Driver Logging 265 266**NOTE:** This functionality is only available with Loaders built with version 2671.3.234 of the Vulkan headers and later. 268 269If you suspect a driver issue, set the loader logging to specifically output 270driver messages: 271 272``` 273set VK_LOADER_DEBUG=error,warn,driver 274``` 275 276Most important driver messages should go out with error or warning levels set, 277but this will provide more driver-specific info as well such as: 278 * What drivers are found 279 * Where they were found 280 * If there is any incompatibility with a given driver 281 * If any environment variables are disabling any of the drivers 282 283For example, the output of the loader looking for drivers on a Linux system may 284look like the following (NOTE: additional spaces have been removed from the 285output for easier reading): 286 287``` 288[Vulkan Loader] DRIVER: Searching for driver manifest files 289[Vulkan Loader] DRIVER: In following folders: 290[Vulkan Loader] DRIVER: /home/$(USER)/.config/vulkan/icd.d 291[Vulkan Loader] DRIVER: /etc/xdg/vulkan/icd.d 292[Vulkan Loader] DRIVER: /etc/vulkan/icd.d 293[Vulkan Loader] DRIVER: /home/$(USER)/.local/share/vulkan/icd.d 294[Vulkan Loader] DRIVER: /home/$(USER)/.local/share/flatpak/exports/share/vulkan/icd.d 295[Vulkan Loader] DRIVER: /var/lib/flatpak/exports/share/vulkan/icd.d 296[Vulkan Loader] DRIVER: /usr/local/share/vulkan/icd.d 297[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d 298[Vulkan Loader] DRIVER: Found the following files: 299[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/intel_icd.x86_64.json 300[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/lvp_icd.x86_64.json 301[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/radeon_icd.x86_64.json 302[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/lvp_icd.i686.json 303[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/radeon_icd.i686.json 304[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/intel_icd.i686.json 305[Vulkan Loader] DRIVER: /usr/share/vulkan/icd.d/nvidia_icd.json 306[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/intel_icd.x86_64.json, version "1.0.0" 307[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/lvp_icd.x86_64.json, version "1.0.0" 308[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/radeon_icd.x86_64.json, version "1.0.0" 309[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/lvp_icd.i686.json, version "1.0.0" 310[Vulkan Loader] DRIVER: Requested driver /usr/lib/libvulkan_lvp.so was wrong bit-type. Ignoring this JSON 311[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/radeon_icd.i686.json, version "1.0.0" 312[Vulkan Loader] DRIVER: Requested driver /usr/lib/libvulkan_radeon.so was wrong bit-type. Ignoring this JSON 313[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/intel_icd.i686.json, version "1.0.0" 314[Vulkan Loader] DRIVER: Requested driver /usr/lib/libvulkan_intel.so was wrong bit-type. Ignoring this JSON 315[Vulkan Loader] DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/nvidia_icd.json, version "1.0.0" 316``` 317 318Then when the application selects the device to use, you will see the Vulkan 319device call chain reported in the following way (NOTE: additional spaces have 320been removed from the output for easier reading): 321 322``` 323[Vulkan Loader] DRIVER: vkCreateDevice layer callstack setup to: 324[Vulkan Loader] DRIVER: <Application> 325[Vulkan Loader] DRIVER: || 326[Vulkan Loader] DRIVER: <Loader> 327[Vulkan Loader] DRIVER: || 328[Vulkan Loader] DRIVER: <Device> 329[Vulkan Loader] DRIVER: Using "Intel(R) UHD Graphics 630 (CFL GT2)" with driver: "/usr/lib64/libvulkan_intel.so" 330``` 331 332 333### Selectively Enable Specific Drivers 334 335**NOTE:** This functionality is only available with Loaders built with version 3361.3.234 of the Vulkan headers and later. 337 338You can now use the filtering environment variables 339(`VK_LOADER_DRIVERS_SELECT` and `VK_LOADER_DRIVERS_DISABLE`) to control what 340drivers the loader will attempt to load. 341For drivers, the string globs passed into the above environment variables will 342be compared against the driver JSON file name since there is no driver name 343known to the loader until much later in the Vulkan initialization process. 344 345For example, to disable all drivers except Nvidia you could do the following: 346 347``` 348set VK_LOADER_DRIVERS_DISABLE=* 349set VK_LOADER_DRIVERS_SELECT=*nvidia* 350``` 351 352The loader outputs messages like the following when the environment variables 353are used: 354 355``` 356[Vulkan Loader] WARNING | DRIVER: Driver "intel_icd.x86_64.json" ignored because not selected by env var 'VK_LOADER_DRIVERS_SELECT' 357[Vulkan Loader] WARNING | DRIVER: Driver "radeon_icd.x86_64.json" ignored because it was disabled by env var 'VK_LOADER_DRIVERS_DISABLE' 358``` 359 360For more info on how to use the filtering environment variables, refer to the 361[Driver Filtering](LoaderDriverInterface.md#driver-filtering) section of the 362[LoaderDriverInterface](LoaderDriverInterface.md) document. 363 364
