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``` 102LAYER: Searching for layer manifest files 103LAYER: In following locations: 104LAYER: /home/${USER}/.config/vulkan/implicit_layer.d 105LAYER: /etc/xdg/vulkan/implicit_layer.d 106LAYER: /usr/local/etc/vulkan/implicit_layer.d 107LAYER: /etc/vulkan/implicit_layer.d 108LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d 109LAYER: /home/${USER}/.local/share/flatpak/exports/share/vulkan/implicit_layer.d 110LAYER: /var/lib/flatpak/exports/share/vulkan/implicit_layer.d 111LAYER: /usr/local/share/vulkan/implicit_layer.d 112LAYER: /usr/share/vulkan/implicit_layer.d 113LAYER: Found the following files: 114LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/renderdoc_capture.json 115LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamfossilize_i386.json 116LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamfossilize_x86_64.json 117LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamoverlay_i386.json 118LAYER: /home/${USER}/.local/share/vulkan/implicit_layer.d/steamoverlay_x86_64.json 119LAYER: /usr/share/vulkan/implicit_layer.d/nvidia_layers.json 120LAYER: /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``` 126LAYER | DEBUG: Loading layer library libVkLayer_khronos_validation.so 127LAYER | INFO: Insert instance layer VK_LAYER_KHRONOS_validation (libVkLayer_khronos_validation.so) 128LAYER | DEBUG: Loading layer library libVkLayer_MESA_device_select.so 129LAYER | INFO: 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``` 136LAYER: vkCreateInstance layer callstack setup to: 137LAYER: <Application> 138LAYER: || 139LAYER: <Loader> 140LAYER: || 141LAYER: VK_LAYER_MESA_device_select 142LAYER: Type: Implicit 143LAYER: Disable Env Var: NODEVICE_SELECT 144LAYER: Manifest: /usr/share/vulkan/implicit_layer.d/VkLayer_MESA_device_select.json 145LAYER: Library: libVkLayer_MESA_device_select.so 146LAYER: || 147LAYER: VK_LAYER_KHRONOS_validation 148LAYER: Type: Explicit 149LAYER: Manifest: /usr/share/vulkan/explicit_layer.d/VkLayer_khronos_validation.json 150LAYER: Library: libVkLayer_khronos_validation.so 151LAYER: || 152LAYER: <Drivers> 153``` 154 155In this scenario, two layers were used (the same two that were loaded earlier): 156* `VK_LAYER_MESA_device_select` 157* `VK_LAYER_KHRONOS_validation` 158 159This information now shows us that the `VK_LAYER_MESA_device_select` is loaded 160first, followed by `VK_LAYER_KHRONOS_validation` which will then continue into 161any available drivers. 162It also shows that `VK_LAYER_MESA_device_select` is an implicit layer which 163implies that it wasn't directly enabled by the application. 164On the other hand, `VK_LAYER_KHRONOS_validation` is shown as an explicit layer 165which indicates that it was likely enabled by the application. 166 167### Disable Layers 168 169**NOTE:** This functionality is only available with Loaders built with version 1701.3.234 of the Vulkan headers and later. 171 172Sometimes, implicit layers can cause issues with an application. 173Because of this, the next step is to try to disable one or more of the listed 174implicit layers. 175You can use the filtering environment variables 176(`VK_LOADER_LAYERS_ENABLE` and `VK_LOADER_LAYERS_DISABLE`) to selectively enable 177or disable various layers. 178If you're not sure what to do, try disabling all implicit layers manually by 179setting `VK_LOADER_LAYERS_DISABLE` to `~implicit~`. 180 181``` 182 set VK_LOADER_LAYERS_DISABLE=~implicit~ 183``` 184 185This will disable all implicit layers and the loader will report any disabled 186layers to the logging output when layer logging is enabled in the following way: 187 188``` 189WARNING | LAYER: Implicit layer "VK_LAYER_MESA_device_select" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 190WARNING | LAYER: Implicit layer "VK_LAYER_AMD_switchable_graphics_64" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 191WARNING | LAYER: Implicit layer "VK_LAYER_Twitch_Overlay" forced disabled because name matches filter of env var 'VK_LOADER_LAYERS_DISABLE'. 192``` 193 194### Selectively Re-enable Layers 195 196**NOTE:** This functionality is only available with Loaders built with version 1971.3.234 of the Vulkan headers and later. 198 199When trying to diagnose problems caused by layers, it is useful to first disable 200all layers and re-enable each layer individually. 201If the problem reappears, then it is immediately clear which layer is the source 202of the issue. 203 204For example, from the above given list of disabled layers, let’s selectively 205re-enable one: 206 207``` 208set VK_LOADER_LAYERS_DISABLE=~implicit~ 209set VK_LOADER_LAYERS_ENABLE=*AMD* 210``` 211 212This would keep both the "VK_LAYER_MESA_device_select" and 213"VK_LAYER_Twitch_Overlay" layers disabled, while enabling the 214"VK_LAYER_AMD_switchable_graphics_64" layer. 215If everything continues to work, then the evidence seems to suggest the issue is 216likely not related to the AMD layer. 217This would lead to enabling one other layer and trying again: 218 219``` 220set VK_LOADER_LAYERS_DISABLE=~implicit~ 221set VK_LOADER_LAYERS_ENABLE=*AMD*,*twitch* 222``` 223 224And so forth. 225 226For more info on how to use the filtering environment variables, refer to the 227[Layer Filtering](LoaderLayerInterface.md#layer-filtering) section of the 228[LoaderLayerInterface](LoaderLayerInterface.md) document. 229 230## Allow specific layers to be ignored by VK_LOADER_LAYERS_DISABLE 231 232**NOTE:** VK_LOADER_LAYERS_DISABLE is only available with Loaders built with version 2331.3.262 of the Vulkan headers and later. 234 235When using `VK_LOADER_LAYERS_DISABLE` to disable implicit layers, it is possible 236to allow specific layers to be enabled using `VK_LOADER_LAYERS_ENABLE`. 237However, this has the effect of *forcing* layers to be enabled, which is not 238always desired. 239Implicit layers have the ability to only be enabled when a layer specified 240environment variable is set, allow for context dependent enablement. 241`VK_LOADER_LAYERS_ENABLE` ignores that context. 242 243Thus, a different environment variable is needed: `VK_LOADER_LAYERS_ALLOW` 244 245The behavior of `VK_LOADER_LAYERS_ALLOW` is similar to `VK_LOADER_LAYERS_ENABLE` 246except that it does not force a layer to be enabled. 247The way to think about this environment variable is that every layer matching 248`VK_LOADER_LAYERS_ALLOW` is excluded from being forcibly disabled by 249`VK_LOADER_LAYERS_DISABLE`. 250this allows for implicit layers that are context dependent to be enabled 251depending on the relevant context instead of force enabling them. 252 253Example: Disable all implicit layers except for any layers that have steam or 254mesa in their name. 255``` 256set VK_LOADER_LAYERS_DISABLE=~implicit~ 257set VK_LOADER_LAYERS_ALLOW=*steam*,*Mesa* 258``` 259 260## Debugging Possible Driver Issues 261 262### Enable Driver Logging 263 264**NOTE:** This functionality is only available with Loaders built with version 2651.3.234 of the Vulkan headers and later. 266 267If you suspect a driver issue, set the loader logging to specifically output 268driver messages: 269 270``` 271set VK_LOADER_DEBUG=error,warn,driver 272``` 273 274Most important driver messages should go out with error or warning levels set, 275but this will provide more driver-specific info as well such as: 276 * What drivers are found 277 * Where they were found 278 * If there is any incompatibility with a given driver 279 * If any environment variables are disabling any of the drivers 280 281For example, the output of the loader looking for drivers on a Linux system may 282look like the following (NOTE: additional spaces have been removed from the 283output for easier reading): 284 285``` 286DRIVER: Searching for driver manifest files 287DRIVER: In following folders: 288DRIVER: /home/$(USER)/.config/vulkan/icd.d 289DRIVER: /etc/xdg/vulkan/icd.d 290DRIVER: /etc/vulkan/icd.d 291DRIVER: /home/$(USER)/.local/share/vulkan/icd.d 292DRIVER: /home/$(USER)/.local/share/flatpak/exports/share/vulkan/icd.d 293DRIVER: /var/lib/flatpak/exports/share/vulkan/icd.d 294DRIVER: /usr/local/share/vulkan/icd.d 295DRIVER: /usr/share/vulkan/icd.d 296DRIVER: Found the following files: 297DRIVER: /usr/share/vulkan/icd.d/intel_icd.x86_64.json 298DRIVER: /usr/share/vulkan/icd.d/lvp_icd.x86_64.json 299DRIVER: /usr/share/vulkan/icd.d/radeon_icd.x86_64.json 300DRIVER: /usr/share/vulkan/icd.d/lvp_icd.i686.json 301DRIVER: /usr/share/vulkan/icd.d/radeon_icd.i686.json 302DRIVER: /usr/share/vulkan/icd.d/intel_icd.i686.json 303DRIVER: /usr/share/vulkan/icd.d/nvidia_icd.json 304DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/intel_icd.x86_64.json, version "1.0.0" 305DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/lvp_icd.x86_64.json, version "1.0.0" 306DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/radeon_icd.x86_64.json, version "1.0.0" 307DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/lvp_icd.i686.json, version "1.0.0" 308DRIVER: Requested driver /usr/lib/libvulkan_lvp.so was wrong bit-type. Ignoring this JSON 309DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/radeon_icd.i686.json, version "1.0.0" 310DRIVER: Requested driver /usr/lib/libvulkan_radeon.so was wrong bit-type. Ignoring this JSON 311DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/intel_icd.i686.json, version "1.0.0" 312DRIVER: Requested driver /usr/lib/libvulkan_intel.so was wrong bit-type. Ignoring this JSON 313DRIVER: Found ICD manifest file /usr/share/vulkan/icd.d/nvidia_icd.json, version "1.0.0" 314``` 315 316Then when the application selects the device to use, you will see the Vulkan 317device call chain reported in the following way (NOTE: additional spaces have 318been removed from the output for easier reading): 319 320``` 321DRIVER: vkCreateDevice layer callstack setup to: 322DRIVER: <Application> 323DRIVER: || 324DRIVER: <Loader> 325DRIVER: || 326DRIVER: <Device> 327DRIVER: Using "Intel(R) UHD Graphics 630 (CFL GT2)" with driver: "/usr/lib64/libvulkan_intel.so" 328``` 329 330 331### Selectively Enable Specific Drivers 332 333**NOTE:** This functionality is only available with Loaders built with version 3341.3.234 of the Vulkan headers and later. 335 336You can now use the filtering environment variables 337(`VK_LOADER_DRIVERS_SELECT` and `VK_LOADER_DRIVERS_DISABLE`) to control what 338drivers the loader will attempt to load. 339For drivers, the string globs passed into the above environment variables will 340be compared against the driver JSON file name since there is no driver name 341known to the loader until much later in the Vulkan initialization process. 342 343For example, to disable all drivers except Nvidia you could do the following: 344 345``` 346set VK_LOADER_DRIVERS_DISABLE=* 347set VK_LOADER_DRIVERS_SELECT=*nvidia* 348``` 349 350The loader outputs messages like the following when the environment variables 351are used: 352 353``` 354WARNING | DRIVER: Driver "intel_icd.x86_64.json" ignored because not selected by env var 'VK_LOADER_DRIVERS_SELECT' 355WARNING | DRIVER: Driver "radeon_icd.x86_64.json" ignored because it was disabled by env var 'VK_LOADER_DRIVERS_DISABLE' 356``` 357 358For more info on how to use the filtering environment variables, refer to the 359[Driver Filtering](LoaderDriverInterface.md#driver-filtering) section of the 360[LoaderDriverInterface](LoaderDriverInterface.md) document. 361 362
