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
Disable spirv-val BOOL false khronos_validation.debug_disable_spirv_val VK_KHRONOS_VALIDATION_DEBUG_DISABLE_SPIRV_VAL 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
Submit time validation BOOL true khronos_validation.syncval_submit_time_validation VK_KHRONOS_VALIDATION_SYNCVAL_SUBMIT_TIME_VALIDATION WINDOWS, LINUX, MACOS, ANDROID
Shader accesses heuristic BOOL false khronos_validation.syncval_shader_accesses_heuristic VK_KHRONOS_VALIDATION_SYNCVAL_SHADER_ACCESSES_HEURISTIC 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
Shader instrumentation BOOL true khronos_validation.gpuav_shader_instrumentation VK_KHRONOS_VALIDATION_GPUAV_SHADER_INSTRUMENTATION WINDOWS, LINUX
Descriptors indexing 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.gpuav_warn_on_robust_oob VK_KHRONOS_VALIDATION_GPUAV_WARN_ON_ROBUST_OOB WINDOWS, LINUX
Out of bounds buffer device addresses BOOL true khronos_validation.gpuav_buffer_address_oob VK_KHRONOS_VALIDATION_GPUAV_BUFFER_ADDRESS_OOB WINDOWS, LINUX
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
RayQuery SPIR-V Instructions BOOL true khronos_validation.gpuav_validate_ray_query VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_RAY_QUERY WINDOWS, LINUX
Cache instrumented shaders rather than instrumenting them on every run BOOL true khronos_validation.gpuav_cache_instrumented_shaders VK_KHRONOS_VALIDATION_GPUAV_CACHE_INSTRUMENTED_SHADERS WINDOWS, LINUX
Enable instrumenting shaders selectively BOOL false khronos_validation.gpuav_select_instrumented_shaders VK_KHRONOS_VALIDATION_GPUAV_SELECT_INSTRUMENTED_SHADERS WINDOWS, LINUX
Buffer content validation BOOL true khronos_validation.gpuav_buffers_validation VK_KHRONOS_VALIDATION_GPUAV_BUFFERS_VALIDATION WINDOWS, LINUX
Indirect draws parameters BOOL false khronos_validation.gpuav_indirect_draws_buffers VK_KHRONOS_VALIDATION_GPUAV_INDIRECT_DRAWS_BUFFERS WINDOWS, LINUX
Indirect dispatches parameters BOOL false khronos_validation.gpuav_indirect_dispatches_buffers VK_KHRONOS_VALIDATION_GPUAV_INDIRECT_DISPATCHES_BUFFERS WINDOWS, LINUX
Indirect trace rays parameters BOOL false khronos_validation.gpuav_indirect_trace_rays_buffers VK_KHRONOS_VALIDATION_GPUAV_INDIRECT_TRACE_RAYS_BUFFERS WINDOWS, LINUX
Buffer copies BOOL true khronos_validation.gpuav_buffer_copies VK_KHRONOS_VALIDATION_GPUAV_BUFFER_COPIES WINDOWS, LINUX
Reserve Descriptor Set Binding Slot BOOL true khronos_validation.gpuav_reserve_binding_slot VK_KHRONOS_VALIDATION_GPUAV_RESERVE_BINDING_SLOT WINDOWS, LINUX
Linear Memory Allocation Mode BOOL true khronos_validation.gpuav_vma_linear_output VK_KHRONOS_VALIDATION_GPUAV_VMA_LINEAR_OUTPUT WINDOWS, LINUX
Validate instrumented shaders BOOL false khronos_validation.gpuav_debug_validate_instrumented_shaders VK_KHRONOS_VALIDATION_GPUAV_DEBUG_VALIDATE_INSTRUMENTED_SHADERS WINDOWS, LINUX
Dump instrumented shaders BOOL false khronos_validation.gpuav_debug_dump_instrumented_shaders VK_KHRONOS_VALIDATION_GPUAV_DEBUG_DUMP_INSTRUMENTED_SHADERS WINDOWS, LINUX
Limit how many time a pass can instrument the SPIR-V INT 0 khronos_validation.gpuav_debug_max_instrumented_count VK_KHRONOS_VALIDATION_GPUAV_DEBUG_MAX_INSTRUMENTED_COUNT WINDOWS, LINUX
Print SPIR-V instrumentation info BOOL false khronos_validation.gpuav_debug_print_instrumentation_info VK_KHRONOS_VALIDATION_GPUAV_DEBUG_PRINT_INSTRUMENTATION_INFO 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
Display Application Name BOOL false khronos_validation.message_format_display_application_name VK_KHRONOS_VALIDATION_MESSAGE_FORMAT_DISPLAY_APPLICATION_NAME 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

This will validate the contents of the SPIR-V which can be CPU intensive during application start up. This does internal checks as well as calling spirv-val.

Setting Properties:

Caching

Creates an internal instance of VK_EXT_validation_cache and upon vkDestroyInstance, will cache the shader validation so sequential usage of the validation layers will be skipped.

Setting Properties:

Disable spirv-val

Allows normal shader validation to run, but removes just spirv-val for performance reasons

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

Check for resource access conflicts caused by missing or incorrectly used synchronization operations.

Setting Properties:

Submit time validation

Enable synchronization validation on the boundary between submitted command buffers. This also validates accesses from presentation operations. This option can incur a significant performance cost.

Setting Properties:

Shader accesses heuristic

Takes into account memory accesses performed by the shader based on SPIR-V static analysis. Warning: can produce false-positives, can ignore certain types of accesses.

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

Will print out handles, instruction location, position in command buffer, and more

Setting Properties:

Printf buffer size

Set the size in bytes of the buffer per draw/dispatch/traceRays to hold the messages

Setting Properties:

Shader instrumentation

Instrument shaders to validate descriptors, descriptor indexing, buffer device addresses and ray queries. Warning: will considerably slow down shader executions.

Setting Properties:

Descriptors indexing

Enable descriptors and buffer out of bounds validation when using descriptor indexing

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:

Out of bounds buffer device addresses

Check for

Setting Properties:

Maximum number of buffer device addresses in use at one time

Setting Properties:

RayQuery SPIR-V Instructions

Enable shader instrumentation on OpRayQueryInitializeKHR

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:

Buffer content validation

Validate buffers containing parameters used in indirect Vulkan commands, or used in copy commands

Setting Properties:

Indirect draws parameters

(Warning - still experimental) Validate buffers containing draw parameters used in indirect draw commands

Setting Properties:

Indirect dispatches parameters

(Warning - still experimental) Validate buffers containing dispatch parameters used in indirect dispatch commands

Setting Properties:

Indirect trace rays parameters

(Warning - still experimental) Validate buffers containing ray tracing parameters used in indirect ray tracing commands

Setting Properties:

Buffer copies

Validate copies involving a VkBuffer. Right now only validates copy buffer to image.

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:

Validate instrumented shaders

Run spirv-val after doing shader instrumentation

Setting Properties:

Dump instrumented shaders

Will dump the instrumented shaders (before and after) to working directory

Setting Properties:

Limit how many time a pass can instrument the SPIR-V

Zero is same as unlimited

Setting Properties:

Prints verbose information about the instrumentation of the SPIR-V

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:

Display Application Name

Useful when running multiple instances to know which instance the message is from.

Setting Properties:

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: