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. With Vulkan Header 272, VK_EXT_validation_features was deprecated and replaced with VK_EXT_layer_settings enabling all settings to be controlled programmatically.

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 feedback

The Vulkan Debug Utils extension provides methods of accessing and controlling feedback from the layers:

Extension Description
VK_EXT_debug_utils allows application control and capture of debug reporting information

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
Fine Grained Locking BOOL true khronos_validation.fine_grained_locking VK_LAYER_FINE_GRAINED_LOCKING WINDOWS, LINUX, MACOS, ANDROID
Core BOOL true khronos_validation.validate_core VK_KHRONOS_VALIDATION_VALIDATE_CORE WINDOWS, LINUX, MACOS, ANDROID
Image Layout BOOL true khronos_validation.check_image_layout VK_KHRONOS_VALIDATION_CHECK_IMAGE_LAYOUT WINDOWS, LINUX, MACOS, ANDROID
Command Buffer State BOOL true khronos_validation.check_command_buffer VK_KHRONOS_VALIDATION_CHECK_COMMAND_BUFFER WINDOWS, LINUX, MACOS, ANDROID
Object in Use BOOL true khronos_validation.check_object_in_use VK_KHRONOS_VALIDATION_CHECK_OBJECT_IN_USE WINDOWS, LINUX, MACOS, ANDROID
Query BOOL true khronos_validation.check_query VK_KHRONOS_VALIDATION_CHECK_QUERY WINDOWS, LINUX, MACOS, ANDROID
Shader BOOL true khronos_validation.check_shaders VK_KHRONOS_VALIDATION_CHECK_SHADERS WINDOWS, LINUX, MACOS, ANDROID
Caching BOOL true khronos_validation.check_shaders_caching VK_KHRONOS_VALIDATION_CHECK_SHADERS_CACHING WINDOWS, LINUX, MACOS, ANDROID
Handle Wrapping BOOL true khronos_validation.unique_handles VK_KHRONOS_VALIDATION_UNIQUE_HANDLES WINDOWS, LINUX, MACOS, ANDROID
Object Lifetime BOOL true khronos_validation.object_lifetime VK_KHRONOS_VALIDATION_OBJECT_LIFETIME WINDOWS, LINUX, MACOS, ANDROID
Stateless Parameter BOOL true khronos_validation.stateless_param VK_KHRONOS_VALIDATION_STATELESS_PARAM WINDOWS, LINUX, MACOS, ANDROID
Thread Safety BOOL true khronos_validation.thread_safety VK_KHRONOS_VALIDATION_THREAD_SAFETY WINDOWS, LINUX, MACOS, ANDROID
Synchronization BOOL false khronos_validation.validate_sync VK_KHRONOS_VALIDATION_VALIDATE_SYNC WINDOWS, LINUX, MACOS, ANDROID
QueueSubmit Synchronization Validation BOOL true khronos_validation.sync_queue_submit VK_KHRONOS_VALIDATION_SYNC_QUEUE_SUBMIT WINDOWS, LINUX, MACOS, ANDROID
GPU Base ENUM GPU_BASED_NONE khronos_validation.validate_gpu_based VK_KHRONOS_VALIDATION_VALIDATE_GPU_BASED WINDOWS, LINUX
Redirect Printf messages to stdout BOOL true khronos_validation.printf_to_stdout VK_KHRONOS_VALIDATION_PRINTF_TO_STDOUT WINDOWS, LINUX
Printf verbose BOOL false khronos_validation.printf_verbose VK_KHRONOS_VALIDATION_PRINTF_VERBOSE WINDOWS, LINUX
Printf buffer size INT 1024 khronos_validation.printf_buffer_size VK_KHRONOS_VALIDATION_PRINTF_BUFFER_SIZE WINDOWS, LINUX
Reserve Descriptor Set Binding Slot BOOL true khronos_validation.reserve_binding_slot VK_KHRONOS_VALIDATION_RESERVE_BINDING_SLOT WINDOWS, LINUX
Linear Memory Allocation Mode BOOL true khronos_validation.vma_linear_output VK_KHRONOS_VALIDATION_VMA_LINEAR_OUTPUT WINDOWS, LINUX
Descriptor and OOB Checks BOOL true khronos_validation.gpuav_descriptor_checks VK_KHRONOS_VALIDATION_GPUAV_DESCRIPTOR_CHECKS WINDOWS, LINUX
Generate warning on out of bounds accesses even if buffer robustness is enabled BOOL true khronos_validation.warn_on_robust_oob VK_KHRONOS_VALIDATION_WARN_ON_ROBUST_OOB WINDOWS, LINUX
Check Draw/Dispatch/TraceRays Indirect buffers BOOL true khronos_validation.validate_indirect_buffer VK_KHRONOS_VALIDATION_VALIDATE_INDIRECT_BUFFER WINDOWS, LINUX
Cache instrumented shaders rather than instrumenting them on every run BOOL true khronos_validation.use_instrumented_shader_cache VK_KHRONOS_VALIDATION_USE_INSTRUMENTED_SHADER_CACHE WINDOWS, LINUX
Enable instrumenting shaders selectively BOOL false khronos_validation.select_instrumented_shaders VK_KHRONOS_VALIDATION_SELECT_INSTRUMENTED_SHADERS WINDOWS, LINUX
Specify the maximum number of buffer device addresses in use at one time INT 10000 khronos_validation.gpuav_max_buffer_device_addresses VK_KHRONOS_VALIDATION_GPUAV_MAX_BUFFER_DEVICE_ADDRESSES WINDOWS, LINUX
Best Practices BOOL false khronos_validation.validate_best_practices VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES WINDOWS, LINUX, MACOS, ANDROID
ARM-specific best practices BOOL false khronos_validation.validate_best_practices_arm VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_ARM WINDOWS, LINUX, MACOS, ANDROID
AMD-specific best practices BOOL false khronos_validation.validate_best_practices_amd VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_AMD WINDOWS, LINUX, MACOS
IMG-specific best practices BOOL false khronos_validation.validate_best_practices_img VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_IMG WINDOWS, LINUX, MACOS
NVIDIA-specific best practices BOOL false khronos_validation.validate_best_practices_nvidia VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_NVIDIA WINDOWS, LINUX, ANDROID
Debug Action FLAGS VK_DBG_LAYER_ACTION_LOG_MSG khronos_validation.debug_action VK_KHRONOS_VALIDATION_DEBUG_ACTION WINDOWS, LINUX, MACOS, ANDROID
Log Filename SAVE_FILE stdout khronos_validation.log_filename VK_KHRONOS_VALIDATION_LOG_FILENAME WINDOWS, LINUX, MACOS, ANDROID
Message Severity FLAGS error khronos_validation.report_flags VK_KHRONOS_VALIDATION_REPORT_FLAGS WINDOWS, LINUX, MACOS, ANDROID
Limit Duplicated Messages BOOL true khronos_validation.enable_message_limit VK_KHRONOS_VALIDATION_ENABLE_MESSAGE_LIMIT 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

Layer Settings Details

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:

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.

Setting Properties:

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.

Setting Properties:

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.

Setting Properties:

Object in Use

Check that Vulkan objects are not in use by a command buffer when they are destroyed.

Setting Properties:

Query

Checks for commands that use VkQueryPool objects.

Setting Properties:

Shader

Shader checks. These checks can be CPU intensive during application start up, especially if Shader Validation Caching is also disabled.

Setting Properties:

Caching

Enable caching of shader validation results.

Setting Properties:

Handle Wrapping

Handle wrapping checks. Disable this feature if you are exerience crashes when creating new extensions or developing new Vulkan objects/structures.

Setting Properties:

Object Lifetime

Object tracking checks. This may not always be necessary late in a development cycle.

Setting Properties:

Stateless Parameter

Stateless parameter checks. This may not always be necessary late in a development cycle.

Setting Properties:

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.

Setting Properties:

Synchronization

Enable synchronization validation during command buffers recording. 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.

Setting Properties:

QueueSubmit Synchronization Validation

Enable synchronization validation between submitted command buffers when Synchronization Validation is enabled. This option will increase the synchronization performance cost.

Setting Properties:

GPU Base

Setting an option here will enable specialized areas of validation

Setting Properties:
Enum Value Label Description Platforms
GPU_BASED_NONE None No GPU-based validation. WINDOWS, LINUX
GPU_BASED_DEBUG_PRINTF Debug Printf Enables processing of debug printf instructions in shaders and sending debug strings to the debug callback. WINDOWS, LINUX
GPU_BASED_GPU_ASSISTED GPU-Assisted Check for API usage errors at shader execution time. WINDOWS, LINUX

Redirect Printf messages to stdout

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

Setting Properties:

Printf verbose

Set the verbosity of debug printf messages

Setting Properties:

Printf buffer size

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

Setting Properties:

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.

Setting Properties:

Linear Memory Allocation Mode

Use VMA linear memory allocations for GPU-AV output buffers instead of finding best place for new allocations among free regions to optimize memory usage. Enabling this setting reduces performance cost but disabling this method minimizes memory usage.

Setting Properties:

Descriptor and OOB Checks

Enable descriptor and buffer out of bounds checking

Setting Properties:

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:

Check Draw/Dispatch/TraceRays Indirect buffers

Enable draw/dispatch/traceRays indirect checking

Setting Properties:

Cache instrumented shaders rather than instrumenting them on every run

Enable instrumented shader caching

Setting Properties:

Enable instrumenting shaders selectively

Select which shaders to instrument passing a VkValidationFeaturesEXT struct with GPU-AV enabled in the VkShaderModuleCreateInfo pNext

Setting Properties:

Specify the maximum number of buffer device addresses in use at one time

Specify maximum number of buffer device addresses

Setting Properties:

Best Practices

Outputs warnings related to common misuse of the API, but which are not explicitly prohibited by the specification.

Setting Properties:

ARM-specific best practices

Outputs warnings for spec-conforming but non-ideal code on ARM GPUs.

Setting Properties:

AMD-specific best practices

Outputs warnings for spec-conforming but non-ideal code on AMD GPUs.

Setting Properties:

IMG-specific best practices

Outputs warnings for spec-conforming but non-ideal code on Imagination GPUs.

Setting Properties:

NVIDIA-specific best practices

Outputs warnings for spec-conforming but non-ideal code on NVIDIA GPUs.

Setting Properties:

Debug Action

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

Setting Properties:
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:

Message Severity

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

Setting Properties:
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:

Max Duplicated Messages

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

Setting Properties:

Mute Message VUIDs

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

Setting Properties:

Disables

Specify areas of validation to be disabled

Setting Properties:
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
VALIDATION_CHECK_DISABLE_SYNCHRONIZATION_VALIDATION_QUEUE_SUBMIT QueueSubmit Synchronization Validation Check synchronization validation between submitted command buffers when Synchronization Validation is enabled. 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:
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
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
VALIDATION_CHECK_ENABLE_VENDOR_SPECIFIC_ALL Hardware specific best practices Activating this feature enables all vendor specific best practices. WINDOWS, LINUX, ANDROID

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: