Khronos Vulkan

VK_LAYER_KHRONOS_validation

Vulkan is an Explicit API, enabling direct control over how GPUs actually work. By design, minimal error checking is done inside a Vulkan driver - applications have full control and responsibility for correct operation. Any errors in Vulkan usage can result in unexpected behavior or even a crash. The VK_LAYER_KHRONOS_validation layer can be used to to assist developers in isolating incorrect usage, and in verifying that applications correctly use the API.

Note:

Configuring the Validation Layer

For an overview of how to configure layers, refer to the Layers Overview and Configuration document.

The Validation Layer settings are documented in detail in the VK_LAYER_KHRONOS_validation document.

The Validation Layer can also be enabled and configured using vkconfig. See the vkconfig documentation for more information.

Layer Controls

Layer behavior is controlled through either a layer settings file or an extension. The layer settings file allows a user to control various layer features and behaviors by providing easily modifiable settings. The Vulkan Validation Features extension provides layer controls, while the Vulkan Debug Utils extension provides methods of accessing and controlling feedback from the layers:

Extension Description
VK_EXT_validation_features allows application control of various layer features
VK_EXT_debug_utils allows application control and capture of debug reporting information

See the Layers Overview and Configuration document for more detailed information on configuring Vulkan layers.

VK_EXT_validation_features

The preferred method for an application to programmatically control validation layer features is through the VK_EXT_validation_features extension. Using this extension allows an application to enable or disable specific Khronos validation features. Note that this extension provides low-level control to an application, and that some combinations of enable/disable settings may produce undefined behavior.

The VK_EXT_validation_features flags can be used to disable validation corresponding to the following deprecated layers:

Setting this VK_EXT_validation_features disable flag Corresponds to not loading this deprecated layer
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT VK_LAYER_GOOGLE_threading
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT VK_LAYER_LUNARG_parameter_validation
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT VK_LAYER_LUNARG_object_tracker
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT VK_LAYER_LUNARG_core_validation
VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT VK_LAYER_GOOGLE_unique_objects

Refer to VK_EXT_validation_features in the Vulkan specification for details on this extension.

VK_EXT_debug_utils

The preferred method for an app to control layer logging is via the VK_EXT_debug_utils extension. Using the VK_EXT_debug_utils extension allows an application to register multiple messengers with the layers. Each messenger can trigger a message callback when a log message occurs. Some messenger callbacks may log the information to a file, others may cause a debug break point or other-application defined behavior. An application can create a messenger even when no layers are enabled, but they will only be called for loader and, if implemented, driver events. Each message is identified by both a severity level and a message type. Severity levels indicate the severity of the message that should be logged including: error, warning, etc. Message types indicate the specific type of message including: validation, performance, etc. Some layers return a unique message ID string per message as well. Using the severity, type, and message ID, an application can easily filter the messages received by their messenger callback.

When reporting an error, the KHRONOS validation layer returns relevant specification information and a link to that information in the official Vulkan specification. Layers included in a Vulkan SDK will link to a version of the Vulkan specification annotated with valid usage identifiers.

Message Types As Reported By VK_EXT_debug_utils flags:

Type Debug Utils Severity Debug Utils Type
Error VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
Warn VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
Perf Warn VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
Info VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT or VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT

By default, if an app uses the VK_EXT_debug_utils extension and registers a messenger, the validation layer default messenger log callback will not execute, as it is considered to be handled by the app. However, using the validation layer callback can be very useful, as it provides a unified log that can be easily parsed. On Android, the validation layer default callback can be forced to always execute, and log its contents to logcat, using the following system property:

adb shell setprop debug.vvl.forcelayerlog 1

The debug.vvl namespace signifies validation layers, and setting this property forces the validation layer callback to always execute, even if the app registers a messenger callback itself. This is especially useful for automation tasks, ensuring that errors can be read in a parseable format.

Refer to VK_EXT_debug_utils in the Vulkan Specification for details on this feature.

Layer Details

Layer Properties

Layer Settings Overview

Setting Type Default Value vk_layer_settings.txt Variable Environment Variable Platforms
Debug Action FLAGS VK_DBG_LAYER_ACTION_LOG_MSG khronos_validation.debug_action N/A WINDOWS, LINUX, MACOS, ANDROID
Log Filename SAVE_FILE stdout khronos_validation.log_filename N/A WINDOWS, LINUX, MACOS, ANDROID
Message Severity FLAGS error khronos_validation.report_flags N/A WINDOWS, LINUX, MACOS, ANDROID
Limit Duplicated Messages BOOL true khronos_validation.enable_message_limit N/A WINDOWS, LINUX, MACOS, ANDROID
Max Duplicated Messages INT 10 khronos_validation.duplicate_message_limit VK_LAYER_DUPLICATE_MESSAGE_LIMIT WINDOWS, LINUX, MACOS, ANDROID
Mute Message VUIDs LIST khronos_validation.message_id_filter VK_LAYER_MESSAGE_ID_FILTER WINDOWS, LINUX, MACOS, ANDROID
Disables FLAGS VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT khronos_validation.disables VK_LAYER_DISABLES WINDOWS, LINUX, MACOS, ANDROID
Enables FLAGS khronos_validation.enables VK_LAYER_ENABLES WINDOWS, LINUX, MACOS, ANDROID
Redirect Printf messages to stdout BOOL true khronos_validation.printf_to_stdout N/A WINDOWS, LINUX
Printf verbose BOOL false khronos_validation.printf_verbose N/A WINDOWS, LINUX
Printf buffer size INT 1024 khronos_validation.printf_buffer_size N/A WINDOWS, LINUX
Check descriptor indexing accesses BOOL true khronos_validation.gpuav_descriptor_indexing N/A WINDOWS, LINUX
Check Out of Bounds BOOL true khronos_validation.gpuav_buffer_oob N/A WINDOWS, LINUX
Generate warning on out of bounds accesses even if buffer robustness is enabled BOOL true khronos_validation.warn_on_robust_oob N/A WINDOWS, LINUX
Check Draw Indirect Count Buffers and firstInstance values BOOL true khronos_validation.validate_draw_indirect N/A WINDOWS, LINUX
Check Dispatch Indirect group count values BOOL true khronos_validation.validate_dispatch_indirect N/A WINDOWS, LINUX
Use VMA linear memory allocations for GPU-AV output buffers BOOL true khronos_validation.vma_linear_output N/A WINDOWS, LINUX
Fine Grained Locking BOOL true khronos_validation.fine_grained_locking VK_LAYER_FINE_GRAINED_LOCKING WINDOWS, LINUX, MACOS, ANDROID

Layer Settings Details

Debug Action

Specifies what action is to be taken when a layer reports information

Setting Properties:

Setting Type: FLAGS - Setting Default Value: VK_DBG_LAYER_ACTION_LOG_MSG

Flags Label Description Platforms
VK_DBG_LAYER_ACTION_LOG_MSG Log Message Log a txt message to stdout or to a log filename. WINDOWS, LINUX, MACOS, ANDROID
VK_DBG_LAYER_ACTION_DEBUG_OUTPUT Debug Output Log a txt message using the Windows OutputDebugString function. WINDOWS
VK_DBG_LAYER_ACTION_BREAK Break Trigger a breakpoint if a debugger is in use. WINDOWS, LINUX, MACOS, ANDROID

Log Filename

Specifies the output filename

Setting Properties:

Setting Type: SAVE_FILE - Setting Default Value: stdout

Message Severity

Comma-delineated list of options specifying the types of messages to be reported

Setting Properties:

Setting Type: FLAGS - Setting Default Value: error

Flags Label Description Platforms
info Info Report informational messages. WINDOWS, LINUX, MACOS, ANDROID
warn Warning Report warnings from using the API in a manner which may lead to undefined behavior or to warn the user of common trouble spots. A warning does NOT necessarily signify illegal application behavior. WINDOWS, LINUX, MACOS, ANDROID
perf Performance Report usage of the API that may cause suboptimal performance. WINDOWS, LINUX, MACOS, ANDROID
error Error Report errors in API usage. WINDOWS, LINUX, MACOS, ANDROID

Limit Duplicated Messages

Enable limiting of duplicate messages.

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Max Duplicated Messages

Maximum number of times any single validation message should be reported.

Setting Properties:

Setting Type: INT - Setting Default Value: 10

Mute Message VUIDs

List of VUIDs and VUID identifers which are to be IGNORED by the validation layer

Setting Properties:

Setting Type: LIST - Setting Default Value:

Disables

Specify areas of validation to be disabled

Setting Properties:

Setting Type: FLAGS - Setting Default Value: VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT

Flags Label Description Platforms
VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT Thread Safety Thread checks. In order to not degrade performance, it might be best to run your program with thread-checking disabled most of the time, enabling it occasionally for a quick sanity check or when debugging difficult application behaviors. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_API_PARAMETERS_EXT Stateless Parameter Stateless parameter checks. This may not always be necessary late in a development cycle. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_OBJECT_LIFETIMES_EXT Object Lifetime Object tracking checks. This may not always be necessary late in a development cycle. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_CORE_CHECKS_EXT Core The main, heavy-duty validation checks. This may be valuable early in the development cycle to reduce validation output while correcting parameter/object usage errors. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_UNIQUE_HANDLES_EXT Handle Wrapping Handle wrapping checks. Disable this feature if you are exerience crashes when creating new extensions or developing new Vulkan objects/structures. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_SHADERS_EXT Shader Validation Shader checks. These checks can be CPU intensive during application start up, especially if Shader Validation Caching is also disabled. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_DISABLE_COMMAND_BUFFER_STATE Command Buffer State Check that all Vulkan objects used by a command buffer have not been destroyed. These checks can be CPU intensive for some applications. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_DISABLE_IMAGE_LAYOUT_VALIDATION Image Layout Check that the layout of each image subresource is correct whenever it is used by a command buffer. These checks are very CPU intensive for some applications. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_DISABLE_QUERY_VALIDATION Query Checks for commands that use VkQueryPool objects. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_DISABLE_OBJECT_IN_USE Object in Use Check that Vulkan objects are not in use by a command buffer when they are destroyed. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_DISABLE_SHADER_VALIDATION_CACHE_EXT Shader Validation Caching Disable caching of shader validation results. WINDOWS, LINUX, MACOS, ANDROID

Enables

Setting an option here will enable specialized areas of validation

Setting Properties:

Setting Type: FLAGS - Setting Default Value:

Flags Label Description Platforms
VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT Synchronization This feature reports resource access conflicts due to missing or incorrect synchronization operations between actions (Draw, Copy, Dispatch, Blit) reading or writing the same regions of memory. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_ENABLE_SYNCHRONIZATION_VALIDATION_QUEUE_SUBMIT QueueSubmit Synchronization Validation Enable synchronization validation between submitted command buffers when Synchronization Validation is enabled. WINDOWS, LINUX, MACOS, ANDROID
VK_VALIDATION_FEATURE_ENABLE_DEBUG_PRINTF_EXT Debug Printf Enables processing of debug printf instructions in shaders and sending debug strings to the debug callback. WINDOWS, LINUX
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_EXT GPU-Assisted Check for API usage errors at shader execution time. WINDOWS, LINUX
VK_VALIDATION_FEATURE_ENABLE_GPU_ASSISTED_RESERVE_BINDING_SLOT_EXT Reserve Descriptor Set Binding Slot Specifies that the validation layers reserve a descriptor set binding slot for their own use. The layer reports a value for VkPhysicalDeviceLimits::maxBoundDescriptorSets that is one less than the value reported by the device. If the device supports the binding of only one descriptor set, the validation layer does not perform GPU-assisted validation. WINDOWS, LINUX
VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT Best Practices Activating this feature enables the output of warnings related to common misuse of the API, but which are not explicitly prohibited by the specification. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_ENABLE_VENDOR_SPECIFIC_ARM ARM-specific best practices Activating this feature enables the output of warnings related to ARM-specific misuse of the API, but which are not explicitly prohibited by the specification. WINDOWS, LINUX, MACOS, ANDROID
VALIDATION_CHECK_ENABLE_VENDOR_SPECIFIC_AMD AMD-specific best practices Adds check for spec-conforming but non-ideal code on AMD GPUs. WINDOWS, LINUX, MACOS
VALIDATION_CHECK_ENABLE_VENDOR_SPECIFIC_IMG IMG-specific best practices Adds check for spec-conforming but non-ideal code on Imagination GPUs. WINDOWS, LINUX, MACOS
VALIDATION_CHECK_ENABLE_VENDOR_SPECIFIC_NVIDIA NVIDIA-specific best practices Activating this feature enables the output of warnings related to NVIDIA-specific misuse of the API, but which are not explicitly prohibited by the specification. WINDOWS, LINUX, ANDROID

Redirect Printf messages to stdout

Enable redirection of Debug Printf messages from the debug callback to stdout

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Printf verbose

Set the verbosity of debug printf messages

Setting Properties:

Setting Type: BOOL - Setting Default Value: false

Printf buffer size

Set the size in bytes of the buffer used by debug printf

Setting Properties:

Setting Type: INT - Setting Default Value: 1024

Check descriptor indexing accesses

Enable descriptor indexing access checking

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Check Out of Bounds

Enable buffer out of bounds checking

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Generate warning on out of bounds accesses even if buffer robustness is enabled

Warn on out of bounds accesses even if robustness is enabled

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Check Draw Indirect Count Buffers and firstInstance values

Enable draw indirect checking

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Check Dispatch Indirect group count values

Enable dispatch indirect checking

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Use VMA linear memory allocations for GPU-AV output buffers

Use linear allocation algorithm

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Fine Grained Locking

Enable fine grained locking for Core Validation, which should improve performance in multithreaded applications. This setting allows the optimization to be disabled for debugging.

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Layer Presets

Standard

Good default validation setup that balance validation coverage and performance.

Preset Setting Values:

Reduced-Overhead

Disables some checks in the interest of better performance.

Preset Setting Values:

Best Practices

Provides warnings on valid API usage that is potential API misuse.

Preset Setting Values:

Synchronization

Identify resource access conflicts due to missing or incorrect synchronization operations between actions reading or writing the same regions of memory.

Preset Setting Values:

GPU-Assisted

Check for API usage errors at shader execution time.

Preset Setting Values:

Debug Printf

Debug shader code by "printing" any values of interest to the debug callback or stdout.

Preset Setting Values: