Vulkan Validation and Debugging Layers

Vulkan supports intercepting or hooking API entry points via the Layer framework. A Layer can intercept all or any subset of Vulkan API entry points. Multiple layers can be chained together to cascade their functionality in the appearance of a single, larger layer.

Vulkan application developers will enable layers to validate and debug their applications.

Layers Included in the SDK

The LunarG Vulkan SDK includes the following layers:

Layer Name Description
VK_LAYER_GOOGLE_unique_objects wrap all Vulkan objects in a unique pointer at create time and unwrap them at use time
VK_LAYER_LUNARG_api_dump print API calls and their parameters and values
VK_LAYER_LUNARG_device_limits validate that app properly queries features and obeys feature limitations
VK_LAYER_LUNARG_core_validation validate the descriptor set, pipeline state, and dynamic state; validate the interfaces between SPIR-V modules and the graphics pipeline; track and validate GPU memory and its binding to objects and command buffers
VK_LAYER_LUNARG_image validate texture formats and render target formats
VK_LAYER_LUNARG_object_tracker track all Vulkan objects and flag invalid objects and object memory leaks
VK_LAYER_LUNARG_parameter_validation validate API parameter values
VK_LAYER_LUNARG_swapchain validate the use of the WSI "swapchain" extensions
VK_LAYER_GOOGLE_threading check validity of multi-threaded API usage

Later sections of this document detail the specific functions of the layers described above.

In addition to the above individually specified layers, a built-in meta-layer definition has been provided which simplifies validation for applications. Specifying this short-hand layer definition will load a standard set of validation layers in the optimal order:

     VK_LAYER_LUNARG_standard_validation

Specifying this layer definition will load the following layers in the order show below:

     VK_LAYER_GOOGLE_threading
     VK_LAYER_LUNARG_parameter_validation
     VK_LAYER_LUNARG_device_limits
     VK_LAYER_LUNARG_object_tracker
     VK_LAYER_LUNARG_image
     VK_LAYER_LUNARG_core_validation
     VK_LAYER_LUNARG_swapchain
     VK_LAYER_GOOGLE_unique_objects

This is done by the Vulkan loader. The loader will remove redundant layer specifications and enforce the order of the standard_validation layer. Layers not included in the meta-layer will be added to the layer chain as expected.

Use of the LUNARG_standard_validation layer is recommended as the order and names of the Vulkan Validations layers are undergoing reorganization and consolidation. For instance, the legacy shader_checker, draw_state and mem_tracker layers have been combined into the new core_validation layer, and param_checker was renamed to parameter_validation. Additional layers are slated to be added to core_validation along with some new features to improve usability. Using standard_validation on the desktop will help to insulate applications from these interim changes.

The long-term goal is to have a very small number of layers or meta-layers which will be optimal for both desktop and mobile solutions. However, until the reorganization is complete the recommended solution is for applications to load standard_validation and if it fails, to load the individual layers in the recommended order as shown above.

Configuring Layers on Linux

The Vulkan Loader searches the /usr/share/vulkan/implicit_layer.d, /usr/share/vulkan/explicit_layer.d, /etc/vulkan/implicit_layer.d, and /etc/vulkan/explicit_layer.d directories for layer JSON manifest files.

Sample Layer manifest file (core_validation.json):

{
    "file_format_version" : "1.0.0",
    "layer" : {
        "name": "VK_LAYER_LUNARG_core_validation",
        "type": "GLOBAL",
        "library_path": "libVKLayer_core_validation.so",
        "api_version": "1.0.5",
        "implementation_version": "1",
        "description": "LunarG Validation Layer"
    }
}

Full and relative (to JSON manifest file) library_path names are supported, as are unqualified file names. If just a filename is specified, the loader will search the default library directory, /usr/lib/x86_64-linux-gnu/, for the layer shared library.

Setting the VK_LAYER_PATH environment variable overrides the default Loader layer search mechanism. When set, the Loader will search only the directory(s) identified by $VK_LAYER_PATH for layer manifest files.

Applications can query available layers via the vkEnumerateInstanceLayerProperties() entry point.

Configuring Layers on Windows

The Vulkan Loader searches the following registry keys to find layers:

HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers

For each value in each of the above two keys for which DWORD data set to 0, the Vulkan Loader opens the json text file specified by the value name. For example, if the HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers key contains the following value:

Name                                          Type         Data
C:\VulkanSDK\1.0.5\Bin\core_validation.json   REG_DWORD    0x00000000

The Loader will open the file C:\VulkanSDK\1.0.5\Bin\core_validation.json to find the pathname to the layer library file. The core_validation.json file might contain:

{
    "file_format_version" : "1.0.0",
    "layer" : {
        "name": "VK_LAYER_LUNARG_core_validation",
        "type": "GLOBAL",
        "library_path": ".\\libVKLayer_core_validation.dll"
        "api_version": "1.0.5",
        "implementation_version": "1",
        "description": "LunarG Validation Layer"
    }
}

Full and relative (to JSON manifest file) library_path names are supported, as are unqualified file names. If just a filename is specified, the loader will search the default library directory, C:\Windows\System32, for the layer shared library. For the above example, the layer library file for the VK_LAYER_LUNARG_core_validation layer is libVKLayer_core_validation.dll, and that file will be loaded from C:\VulkanSDK\1.0.5\Bin and used by the loader if the VK_LAYER_core_validation layer is activated.

Activating Layers on Linux

Before or during execution of a Vulkan application, the Loader must be informed of the layers to activate. Applications can activate layers at runtime via the vkCreateInstance() entry point.

Layers configured in /usr/share/vulkan/implicit_layer.d and /etc/vulkan/implicit_layer.d are activated automatically by the Loader.

Layers configured in /usr/share/vulkan/explicit_layer.d and /etc/vulkan/explicit_layer.d can be activated by applications at runtime. These explicit layers can also be activated by the user by setting the VK_INSTANCE_LAYERS environment variable. Set this variable to identify a colon separated list of layer names to activate. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottom-most layer (closest to the driver).

For example, the list of explicit layers to activate can be specified with:

$ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump:VK_LAYER_LUNARG_core_validation

To activate layers in a local SDK install, identify certain library paths and the layer JSON manifest file directory in addition to the layers to activate. If the Vulkan SDK was locally installed to /sdks, VULKAN_SDK=/sdks/VulkanSDK/1.0.5/x86_64:

$ export VK_LAYER_PATH=$VULKAN_SDK/lib/vulkan/layers
$ export LD_LIBRARY_PATH=$VULKAN_SDK/lib:$VULKAN_SDK/lib/vulkan/layers
$ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump:VK_LAYER_LUNARG_core_validation
$ ./tri

Developers may choose to activate all Vulkan Validation layers simply by using LUNARG_standard_validation. To do so via the environment:

$ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_standard_validation

Alternatively, the layers can be loaded manually like so:

$ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_device_limits:VK_LAYER_LUNARG_core_validation:VK_LAYER_LUNARG_image:VK_LAYER_LUNARG_object_tracker:VK_LAYER_LUNARG_parameter_validation:VK_LAYER_LUNARG_swapchain:VK_LAYER_GOOGLE_threading:VK_LAYER_GOOGLE_unique_objects

Activating Layers on Windows

Before or during execution of a Vulkan application, the Loader must be informed of the layers to activate. Applications can activate layers at runtime via the vkCreateInstance() entry point.

Layers configured in registry key HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ImplicitLayers are activated automatically by the Loader.

Layers configured in registry key HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers can be activated by applications at runtime. These explicit layers can also be activated by the user by setting the VK_INSTANCE_LAYERS environment variable. Set this variable to identify a semi-colon separated list of layer names to activate. Order is relevant with the first layer in the list being the topmost layer (closest to the application) and the last layer in the list being the bottom-most layer (closest to the driver).

In a Command Window, the list of explicit layers to activate can be specified with:

C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_LUNARG_core_validation

VK_INSTANCE_LAYERS can also be set in the system environment variables.

To activate layers located in a particular SDK install, identify the layer JSON manifest file directory using the VK_LAYER_PATH environment variable. For example, if a Vulkan SDK is locally installed to C:\VulkanSDK\1.0.5:

C:\> set VK_LAYER_PATH=C:\VulkanSDK\1.0.5\Bin
C:\> set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump;VK_LAYER_LUNARG_core_validation
C:\> tri

Developers may choose to activate all Vulkan Validation layers simply by using LUNARG_standard_validation. To do so via the environment:

C:\> set  VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_standard_validation

Alternatively, the layers can be loaded manually like so:

C:\> set  VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_device_limits;VK_LAYER_LUNARG_core_validation;VK_LAYER_LUNARG_image;VK_LAYER_LUNARG_object_tracker;VK_LAYER_LUNARG_parameter_validation;VK_LAYER_LUNARG_swapchain;VK_LAYER_GOOGLE_threading

Layer Settings File

In addition to activating the layers, specific reporting levels must be set for each layer programmatically or via the vk_layer_settings.txt settings file. vk_layer_settings.txt must be located in the same directory as the running application.

Note: To generate layer reporting output, a vk_layer_settings.txt file must be provided that identifies specific reporting levels for the layers enabled via the VK_INSTANCE_LAYER environment variable.

The settings file consists of comment lines and settings lines. Comment lines begin with the # character. Settings lines have the following format:

<LayerName><setting_name> = <setting_value>

Three settings are common to all layers:

Setting Values Description
LayerName.report_flags info Report information level messages
warn Report warning level messages
perf Report performance level warning messages
error Report error level messages
debug No output messages
LayerName.debug_action VK_DBG_LAYER_ACTION_IGNORE Ignore message reporting
VK_DBG_LAYER_ACTION_LOG_MSG Report messages to log
VK_DBG_LAYER_ACTION_DEBUG_OUTPUT (Windows) Report messages to debug console of Microsoft Visual Studio
VK_DBG_LAYER_ACTION_BREAK Break on messages (not currently used)
LayerName.log_filename filename.txt Name of file to log report_flags level messages; default is stdout

Layer-specific settings are also supported in the vk_layer_settings.txt file.

Sample vk_layer_settings.txt config file contents:

lunarg_core_validation.report_flags = info,error
lunarg_core_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG
# VK_LAYER_LUNARG_api_dump custom settings
lunarg_api_dump.no_addr = TRUE
lunarg_api_dump.file = FALSE

The LunarG Vulkan SDK includes a sample layer settings file identifying the available and supported settings for each layer. On Linux, you can find the sample layer settings file in config/vk_layer_settings.txt of your local Vulkan SDK install. On Windows, you can find the sample layer settings file in Config\vk_layer_settings.txt of your local Vulkan SDK install.

Note: The default reporting level for all enabled layers is no reporting. When activated via VK_INSTANCE_LAYER environment variable, layer level reporting is enabled by providing a vk_layer_settings.txt file that identifies the desired reporting level(s) for each layer. Applications that enable layers must register a callback.

Layer Output Message Format

The output messages of the validation layers included in the SDK follow the same format:

{LAYER_IDENTIFIER}<INFO|WARN|ERROR> : <Message description>

Examples of 3 types of output from 3 different layers:

{MEM}INFO :     VK OBJECT Binding list of size 1 elements:
{MEM}INFO :         VK OBJECT 0x7a8bd0

{PARAMCHECK}ERROR : Parameter pCreateInfo to function CreateFence contains an invalid value.

Layer Details

Refer to the Validation Layer Details document for detailed information on the specific error checks performed by each of the validation layers.

VK_LAYER_LUNARG_api_dump

The VK_LAYER_LUNARG_api_dump debugging layer prints API calls, parameters, and values to the identified output stream.

VK_LAYER_LUNARG_api_dump has three custom settings that can be set to TRUE or FALSE values:

Setting Description
lunarg_api_dump.detailed if TRUE (the default), dump all function parameters and values; if FALSE, dump only function signatures
lunarg_api_dump.file dump to file; otherwise dump to stdout
lunarg_api_dump.no_addr if TRUE, replace all addresses with static string "address"
lunarg_api_dump.flush if TRUE, force i/o flush after every line

VK_LAYER_LUNARG_device_limits

This layer is a work in progress. VK_LAYER_LUNARG_device_limits layer is intended to capture two broad categories of errors:

  1. incorrect use of APIs to query device capabilities
  2. attempt to use API functionality beyond the capability of the underlying device

For the first category, the layer tracks which calls are made and flags errors if calls are excluded that should not be, or if call sequencing is incorrect. An example is an app that attempts to Query and use queues without ever having called vkGetPhysicalDeviceQueueFamilyProperties(). Also, if an app is calling vkGetPhysicalDeviceQueueFamilyProperties() to retrieve properties with some assumed count for array size instead of first calling vkGetPhysicalDeviceQueueFamilyProperties() w/ a NULL pQueueFamilyProperties parameter in order to query the actual count. For the second category of errors, VK_LAYER_LUNARG_device_limits stores its own internal record of underlying device capabilities and flags errors if requests are made beyond those limits. The device limits are queried via calls.

VK_LAYER_LUNARG_device_limits intercepts the following API calls:

In this early version of VK_LAYER_LUNARG_device_limits layer, queue capabilities are the primary functionality being validated. Further validation checks will continue to be added to this layer.

VK_LAYER_LUNARG_core_validation

The VK_LAYER_LUNARG_core_validation layer validates the status of descriptor sets, command buffers, pipeline states, and dynamic states. All of this encompasses that state that feeds into a Draw call, hence the name "VK_LAYER_LUNARG_core_validation." The VK_LAYER_LUNARG_core_validation layer also validates that the RenderPass construct is used correctly. Additionally, it also validates the interfaces between SPIR-V modules and the pipeline.

VK_LAYER_LUNARG_core_validation intercepts the following API calls:

VK_LAYER_LUNARG_core_validation validates that:

The VK_LAYER_LUNARG_core_validation layer will print errors if validation checks are not correctly met. VK_LAYER_LUNARG_core_validation will also display the values of the objects tracked.

VK_LAYER_LUNARG_core_validation Shader-related functionality

Checks performed by this layer apply to the VS->FS and FS->CB interfaces with the pipeline. These checks include:

These extra checks are to ensure that the legacy broadcast of gl_FragColor to all bound color attachments is well-defined.

VK_LAYER_LUNARG_core_validation Memory/Resource related functionality

This layer additionally attempts to ensure that memory objects are managed correctly by the application. These memory objects may be bound to pipelines, objects, and command buffers, and then submitted to the GPU for work. Specifically the layer validates that:

Errors will be printed if validation checks are not correctly met and warnings if improper (but not illegal) use of memory is detected. This validation layer also dumps all memory references and bindings for each operation.

VK_LAYER_LUNARG_object_tracker

The VK_LAYER_LUNARG_object_tracker layer tracks all Vulkan objects. Issues related to unknown objects and object clean up are also flagged.

Objects tracked by the VK_LAYER_LUNARG_object_tracker layer include device, command buffer, image, presentable image memory, GPU memory, depth stencil view, color attachment view, sampler, shader, and descriptor set layout objects, among others.

This layer validates that:

The VK_LAYER_LUNARG_object_tracker layer will print errors if validation checks are not correctly met and warnings if improper reference of objects is detected.

VK_LAYER_LUNARG_image

The VK_LAYER_LUNARG_image validation layer checks texture formats and render target formats.

VK_LAYER_LUNARG_parameter_validation

The VK_LAYER_LUNARG_parameter_validation validation layer checks the input parameters to API calls for validity. This layer performs the following tasks:

VK_LAYER_LUNARG_swapchain

The VK_LAYER_LUNARG_swapchain layer validates the use of the WSI (Window System Integration) "swapchain" extensions (i.e. VK_EXT_KHR_swapchain and VK_EXT_KHR_device_swapchain).

Checks include:

VK_LAYER_GOOGLE_threading

The VK_LAYER_GOOGLE_threading layer checks multi-threading of API calls for validity. Checks performed by this layer include ensuring that only one thread at a time uses an object in free-threaded API calls

VK_LAYER_GOOGLE_unique_objects

The VK_LAYER_LUNARG_unique_objects does not operate as a strict validation layer, but enables consistent and coherent validation on systems which return non-unique object handles. This layer will alias all Vulkan objects with a unique identifier at object creation time. This is used during validation to ensure that duplicate object handles are correctly managed and tracked by the other validation layers. Note that for optimal efficiency, this layer MUST be last in the chain (closest to the display driver).

ShaderChecker layer functionality

The ShaderChecker functionality is part of VK_LAYER_LUNARG_core_validation layer and it inspects the SPIR-V shader images and fixed function pipeline stages at PSO creation time.

Checks performed by this layer apply to the VS->FS and FS->CB interfaces with the pipeline. These checks include:

These extra checks are to ensure that the legacy broadcast of gl_FragColor to all bound color attachments is well-defined.