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:

• Most Khronos Validation layer features can be used simultaneously. However, this could result in noticeable performance degradation. The best practice is to run Core validation, GPU-Assisted validation, Synchronization Validation and Best practices validation features individually.

• Debug Printf functionality and GPU-Assisted validation cannot be run at the same time.

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:

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:

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:

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

• API Version: 1.3.250
• Implementation Version: 1
• Layer Manifest: VkLayer_khronos_validation.json
  • File Format: 1.2.0
  • Layer Binary: libVkLayer_khronos_validation.so
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Number of Layer Settings: 7
• Number of Layer Presets: 6

Layer Settings Overview

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:

• vk_layer_settings.txt Variable: khronos_validation.fine_grained_locking
• Environment Variable: VK_LAYER_FINE_GRAINED_LOCKING
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.validate_core
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.check_image_layout
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.check_command_buffer
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Object in Use

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.check_object_in_use
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Query

Checks for commands that use VkQueryPool objects.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.check_query
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Shader

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.check_shaders
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Caching

Enable caching of shader validation results.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.check_shaders_caching
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.unique_handles
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Object Lifetime

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.object_lifetime
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Stateless Parameter

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.stateless_param
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.thread_safety
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.validate_sync
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: false

QueueSubmit Synchronization Validation(ALPHA)

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.sync_queue_submit
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: false

GPU Base

Setting an option here will enable specialized areas of validation

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_gpu_based
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: ENUM
• Setting Default Value: GPU_BASED_NONE

Redirect Printf messages to stdout

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.printf_to_stdout
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Printf verbose

Set the verbosity of debug printf messages

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.printf_verbose
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: false

Printf buffer size

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.printf_buffer_size
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: INT
• Setting Default Value: 1024

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:

• vk_layer_settings.txt Variable: khronos_validation.reserve_binding_slot
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

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:

• vk_layer_settings.txt Variable: khronos_validation.vma_linear_output
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Check descriptor indexing accesses

Enable descriptor indexing access checking

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.gpuav_descriptor_indexing
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Check Out of Bounds

Enable buffer out of bounds checking

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.gpuav_buffer_oob
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• 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:

• vk_layer_settings.txt Variable: khronos_validation.warn_on_robust_oob
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Check Draw Indirect Count Buffers and firstInstance values

Enable draw indirect checking

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_draw_indirect
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Check Dispatch Indirect group count values

Enable dispatch indirect checking

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_dispatch_indirect
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX
• Setting Type: BOOL
• Setting Default Value: true

Best Practices

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_best_practices
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: false

ARM-specific best practices

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_best_practices_arm
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: false

AMD-specific best practices

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_best_practices_amd
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: false

IMG-specific best practices

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_best_practices_img
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS
• Setting Type: BOOL
• Setting Default Value: false

NVIDIA-specific best practices

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.validate_best_practices_nvidia
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, ANDROID
• Setting Type: BOOL
• Setting Default Value: false

Debug Action

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.debug_action
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: FLAGS
• Setting Default Value: VK_DBG_LAYER_ACTION_LOG_MSG

Log Filename

Specifies the output filename

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.log_filename
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• 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:

• vk_layer_settings.txt Variable: khronos_validation.report_flags
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: FLAGS
• Setting Default Value: error

Limit Duplicated Messages

Enable limiting of duplicate messages.

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.enable_message_limit
• Environment Variable: N/A
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: BOOL
• Setting Default Value: true

Max Duplicated Messages

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

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.duplicate_message_limit
• Environment Variable: VK_LAYER_DUPLICATE_MESSAGE_LIMIT
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• 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:

• vk_layer_settings.txt Variable: khronos_validation.message_id_filter
• Environment Variable: VK_LAYER_MESSAGE_ID_FILTER
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: LIST
• Setting Default Value:

Disables

Specify areas of validation to be disabled

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.disables
• Environment Variable: VK_LAYER_DISABLES
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: FLAGS
• Setting Default Value: VK_VALIDATION_FEATURE_DISABLE_THREAD_SAFETY_EXT

Enables

Setting an option here will enable specialized areas of validation

Setting Properties:

• vk_layer_settings.txt Variable: khronos_validation.enables
• Environment Variable: VK_LAYER_ENABLES
• Platforms: WINDOWS, LINUX, MACOS, ANDROID
• Setting Type: FLAGS
• Setting Default Value:

Layer Presets

Standard

Good default validation setup that balance validation coverage and performance.

Preset Setting Values:

• Core: true
• Image Layout: true
• Command Buffer State: true
• Object in Use: true
• Query: true
• Shader: true
• Caching: true
• Handle Wrapping: true
• Object Lifetime: true
• Stateless Parameter: true
• Thread Safety: false
• Synchronization: false
• GPU Base: GPU_BASED_NONE
• Best Practices: false

Reduced-Overhead

Disables some checks in the interest of better performance.

Preset Setting Values:

• Core: true
• Image Layout: false
• Command Buffer State: false
• Object in Use: false
• Query: false
• Shader: true
• Caching: true
• Handle Wrapping: false
• Object Lifetime: true
• Stateless Parameter: true
• Thread Safety: false
• Synchronization: false
• GPU Base: GPU_BASED_NONE
• Best Practices: false

Best Practices

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

Preset Setting Values:

• Core: false
• Image Layout: false
• Command Buffer State: false
• Object in Use: false
• Query: false
• Shader: false
• Caching: false
• Handle Wrapping: false
• Object Lifetime: false
• Stateless Parameter: false
• Thread Safety: false
• Synchronization: false
• GPU Base: GPU_BASED_NONE
• Best Practices: true

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:

• Core: false
• Image Layout: false
• Command Buffer State: false
• Object in Use: false
• Query: false
• Shader: false
• Caching: false
• Handle Wrapping: false
• Object Lifetime: false
• Stateless Parameter: false
• Thread Safety: true
• Synchronization: true
• GPU Base: GPU_BASED_NONE
• Best Practices: false

GPU-Assisted

Check for API usage errors at shader execution time.

Preset Setting Values:

• Core: false
• Image Layout: false
• Command Buffer State: false
• Object in Use: false
• Query: false
• Shader: false
• Caching: false
• Handle Wrapping: false
• Object Lifetime: false
• Stateless Parameter: false
• Thread Safety: false
• Synchronization: false
• GPU Base: GPU_BASED_GPU_ASSISTED
• Reserve Descriptor Set Binding Slot: true
• Best Practices: false

Debug Printf

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

Preset Setting Values:

• Core: false
• Image Layout: false
• Command Buffer State: false
• Object in Use: false
• Query: false
• Shader: false
• Caching: false
• Handle Wrapping: false
• Object Lifetime: false
• Stateless Parameter: false
• Thread Safety: false
• Synchronization: false
• GPU Base: GPU_BASED_DEBUG_PRINTF
• Best Practices: false