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. 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:
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.280
- 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
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.gpuav_validate_indirect_buffer | VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_INDIRECT_BUFFER | WINDOWS, LINUX |
Check copy commands | BOOL | true | khronos_validation.gpuav_validate_copies | VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_COPIES | WINDOWS, LINUX |
Validate 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.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 |
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 |
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:
- 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: VK_KHRONOS_VALIDATION_VALIDATE_CORE
- 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: VK_KHRONOS_VALIDATION_CHECK_IMAGE_LAYOUT
- 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: VK_KHRONOS_VALIDATION_CHECK_COMMAND_BUFFER
- 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: VK_KHRONOS_VALIDATION_CHECK_OBJECT_IN_USE
- 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: VK_KHRONOS_VALIDATION_CHECK_QUERY
- 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: VK_KHRONOS_VALIDATION_CHECK_SHADERS
- 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: VK_KHRONOS_VALIDATION_CHECK_SHADERS_CACHING
- 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: VK_KHRONOS_VALIDATION_UNIQUE_HANDLES
- 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: VK_KHRONOS_VALIDATION_OBJECT_LIFETIME
- 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: VK_KHRONOS_VALIDATION_STATELESS_PARAM
- 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: VK_KHRONOS_VALIDATION_THREAD_SAFETY
- 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: VK_KHRONOS_VALIDATION_VALIDATE_SYNC
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: false
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:
- vk_layer_settings.txt Variable: khronos_validation.sync_queue_submit
- Environment Variable: VK_KHRONOS_VALIDATION_SYNC_QUEUE_SUBMIT
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- Setting Type: BOOL
- Setting Default Value: true
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: VK_KHRONOS_VALIDATION_VALIDATE_GPU_BASED
- Platforms: WINDOWS, LINUX
- Setting Type: ENUM
- Setting Default Value: GPU_BASED_NONE
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:
- vk_layer_settings.txt Variable: khronos_validation.printf_to_stdout
- Environment Variable: VK_KHRONOS_VALIDATION_PRINTF_TO_STDOUT
- 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: VK_KHRONOS_VALIDATION_PRINTF_VERBOSE
- 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: VK_KHRONOS_VALIDATION_PRINTF_BUFFER_SIZE
- 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: VK_KHRONOS_VALIDATION_RESERVE_BINDING_SLOT
- 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: VK_KHRONOS_VALIDATION_VMA_LINEAR_OUTPUT
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Descriptor and OOB Checks
Enable descriptor and buffer out of bounds checking
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_descriptor_checks
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_DESCRIPTOR_CHECKS
- 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: VK_KHRONOS_VALIDATION_WARN_ON_ROBUST_OOB
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Check Draw/Dispatch/TraceRays Indirect buffers
Enable draw/dispatch/traceRays indirect checking
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_validate_indirect_buffer
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_INDIRECT_BUFFER
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Check copy commands
Enable copy commands checking
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_validate_copies
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_COPIES
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Validate RayQuery SPIR-V Instructions
Enable shader instrumentation on SPV_KHR_ray_query
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_validate_ray_query
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_VALIDATE_RAY_QUERY
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Cache instrumented shaders rather than instrumenting them on every run
Enable instrumented shader caching
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.use_instrumented_shader_cache
- Environment Variable: VK_KHRONOS_VALIDATION_USE_INSTRUMENTED_SHADER_CACHE
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: true
Enable instrumenting shaders selectively
Select which shaders to instrument passing a VkValidationFeaturesEXT struct with GPU-AV enabled in the VkShaderModuleCreateInfo pNext
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.select_instrumented_shaders
- Environment Variable: VK_KHRONOS_VALIDATION_SELECT_INSTRUMENTED_SHADERS
- Platforms: WINDOWS, LINUX
- Setting Type: BOOL
- Setting Default Value: false
Specify the maximum number of buffer device addresses in use at one time
Specify maximum number of buffer device addresses
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_max_buffer_device_addresses
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_MAX_BUFFER_DEVICE_ADDRESSES
- Platforms: WINDOWS, LINUX
- Setting Type: INT
- Setting Default Value: 10000
Validate instrumented shaders
Run spirv-val after doing shader instrumentation
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_debug_validate_instrumented_shaders
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_DEBUG_VALIDATE_INSTRUMENTED_SHADERS
- Platforms: WINDOWS, LINUX
- Setting Level: ADVANCED
- Setting Type: BOOL
- Setting Default Value: false
Dump instrumented shaders
Will dump the instrumented shaders (before and after) to working directory
Setting Properties:
- vk_layer_settings.txt Variable: khronos_validation.gpuav_debug_dump_instrumented_shaders
- Environment Variable: VK_KHRONOS_VALIDATION_GPUAV_DEBUG_DUMP_INSTRUMENTED_SHADERS
- Platforms: WINDOWS, LINUX
- Setting Level: ADVANCED
- Setting Type: BOOL
- Setting Default Value: false
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: VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES
- 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: VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_ARM
- 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: VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_AMD
- 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: VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_IMG
- 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: VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_NVIDIA
- 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: VK_KHRONOS_VALIDATION_DEBUG_ACTION
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- 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:
- vk_layer_settings.txt Variable: khronos_validation.log_filename
- Environment Variable: VK_KHRONOS_VALIDATION_LOG_FILENAME
- 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: VK_KHRONOS_VALIDATION_REPORT_FLAGS
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- 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:
- vk_layer_settings.txt Variable: khronos_validation.enable_message_limit
- Environment Variable: VK_KHRONOS_VALIDATION_ENABLE_MESSAGE_LIMIT
- 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
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:
- vk_layer_settings.txt Variable: khronos_validation.enables
- Environment Variable: VK_LAYER_ENABLES
- Platforms: WINDOWS, LINUX, MACOS, ANDROID
- 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 |
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:
- 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: true
- 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