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.

Configuring the Validation Layer

There are 4 ways to configure the settings: vkconfig, application defined, vk_layer_settings.txt, environment variables

VkConfig

We suggest people to use VkConfig.

The GUI comes with the SDK, and takes the VkLayer_khronos_validation.json file and does everything for you!

Application Defined

The application can now use the VK_EXT_layer_settings extension to do everything at vkCreateInstance time. (Don't worry, we implement the extension, so it will be supported 100% of the time!).

// Example how to turn on verbose mode for DebugPrintf
const VkBool32 verbose_value = true;
const VkLayerSettingEXT layer_setting = {"VK_LAYER_KHRONOS_validation", "printf_verbose", VK_LAYER_SETTING_TYPE_BOOL32_EXT, 1, &verbose_value};
VkLayerSettingsCreateInfoEXT layer_settings_create_info = {VK_STRUCTURE_TYPE_LAYER_SETTINGS_CREATE_INFO_EXT, nullptr, 1, &layer_setting};

VkInstanceCreateInfo instance_ci = GetYourCreateInfo();
instance_ci.pNext = &layer_settings_create_info;

vk_layer_settings.txt

There is info elsewhere to describe this file, but the short answer is to set the VK_LAYER_SETTINGS_PATH like the following:

# windows
set VK_LAYER_SETTINGS_PATH=C:\path\to\vk_layer_settings.txt

# linux
export VK_LAYER_SETTINGS_PATH=/path/to/vk_layer_settings.txt

and it will set things for you in that file. We have a default example file you can start with.

Environment Variables

This is done for us via the vkuCreateLayerSettingSet call in the Vulkan-Utility-Libraries.

As an example, in our VkLayer_khronos_validation.json file you will find something like "key": "message_id_filter",.

From here you just need to adjust it the naming and prefix depending on your platform:

# Windows
set VK_LAYER_MESSAGE_ID_FILTER=VUID-VkInstanceCreateInfo-pNext-pNext

# Linux
export VK_LAYER_MESSAGE_ID_FILTER=VUID-VkInstanceCreateInfo-pNext-pNext

# Android
adb setprop debug.vulkan.khronos_validation.message_id_filter=VUID-VkInstanceCreateInfo-pNext-pNext

Layer Details

Layer Properties

• API Version: 1.4.313
• Implementation Version: 1
• Layer Manifest: VkLayer_khronos_validation.json
  • File Format: 1.2.0
  • Layer Binary: libVkLayer_khronos_validation.so
• Variables:
  • vk_layer_settings.txt namespace: khronos_validation
  • Environment Variable prefix: VK_KHRONOS_VALIDATION_
  • Android system property prefix: adb setprop debug.vulkan.khronos_validation.
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID
• Number of Layer Settings: 64
• Number of Layer Presets: 6

Layer Settings Overview

Layer Settings Details

Validation Areas

Control of the Validation layer validation

• Type: GROUP
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Object in Use

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Query

Checks for commands that use VkQueryPool objects.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

All the following condition must be fulfilled for the setting to be applied.

Handle Wrapping

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Object Lifetime

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Stateless Parameter

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Synchronization

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

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.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Shader accesses heuristic

Take 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.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Error messages

Options to configure synchronization validation error reporting

• Type: GROUP
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Extra properties

Append a section of key-value properties to the error message. Useful for filtering errors.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Debug Printf

Enable DebugPrintf and will print anything use NonSemantic.DebugPrintf in their SPIR-V

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Redirect Printf messages to stdout

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Printf verbose

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Printf buffer size

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

• Type: INT
• Default Value: 1024
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

GPU Assisted Validation

Enable validation that cannot be done the CPU and needs hooks into the GPU execution

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Safe Mode

Will have GPU-AV try and prevent crashes, but will be much slower to validate. If using Safe Mode, consider using selective shader instrumentation, to only instrument the shaders/pipelines causing issues.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Force on robustness features

This will enable all possible robustness features for the app at device creation time. This can be used to quickly detect if with robustness, your issue disappears. GPU-AV will also skip validating things already covered by robustness, so turning on should reduce GPU-AV performance overhead.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Shader instrumentation

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Enable instrumenting shaders selectively

Select which shaders to instrument by passing a VkValidationFeaturesEXT struct with GPU-AV enabled in the VkShaderModuleCreateInfo pNext or using a regex matching a shader/pipeline debug name. Because this only validates the selected shaders, it will allow GPU-AV to run much faster.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Shader/pipeline name regexes

Any shader or pipeline library debug name (set with vkSetDebugUtilsObjectNameEXT) fully matching any listed regular expression will be instrumented when creating pipelines with those shaders or libraries. Regex grammar: Modified ECMAScript. No support for shader objects yet. Warning: instrumentation being performed at final pipeline creation time, if shaders modules have already been destroyed at this step (possible when using pipeline libraries), they won't be found by this regex selection system. In this case, consider naming pipeline libraries instead.

• Type: LIST
• Default Value:
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Descriptors indexing

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Post process descriptor indexing

Track which descriptor indexes were used in shader to run normal validation afterwards

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Out of bounds buffer device addresses

Check for invalid access using buffer device address

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Maximum number of buffer device addresses in use at one time

• Type: INT
• Default Value: 10000
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

RayQuery SPIR-V instructions

Enable shader instrumentation on OpRayQueryInitializeKHR

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Out of bounds vertex attribute fetching

Validate that no vertex attribute fetching is out of bonds

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Buffer content validation

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Indirect draws parameters

Validate buffers containing draw parameters used in indirect draw commands. Includes vkCmdDrawMeshTasks* calls as well

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Indirect dispatches parameters

Validate buffers containing dispatch parameters used in indirect dispatch commands

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Indirect trace rays parameters

Validate buffers containing ray tracing parameters used in indirect ray tracing commands

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Buffer copies

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

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Index buffers

Validate that indexed draws do not fetch indices outside of the bounds of the index buffer.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

All the following condition must be fulfilled for the setting to be applied.

Image Layout

(Warning - still known to have false positives) Use GPU-AV to detect which descriptors where accessed. Then using post processing, check that the layout of each image subresource is correct whenever it is used by a command buffer.

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX

Best Practices

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

ARM-specific best practices

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

AMD-specific best practices

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS

IMG-specific best practices

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS

NVIDIA-specific best practices

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, ANDROID

Debug Action

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

• Type: FLAGS
• Default Value: VK_DBG_LAYER_ACTION_LOG_MSG
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Log Filename

Specifies the output filename

• Type: SAVE_FILE
• Default Value: stdout
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Message Severity

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

• Type: FLAGS
• Default Value: error
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Limit Duplicated Messages

Enable limiting of duplicate messages.

• Type: BOOL
• Default Value: true
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Max Duplicated Messages

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

• Type: INT
• Default Value: 10
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Mute Message VUIDs

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

• Type: LIST
• Default Value:
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Message Format

Specifies how error messages are reported

• Type: GROUP
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

JSON

Display Validation as JSON (VkDebugUtilsMessengerCallbackDataEXT::pMessage will contain JSON)

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, ANDROID

Display Application Name

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

• Type: BOOL
• Default Value: false
• Platforms: WINDOWS_X86, WINDOWS_ARM, LINUX, MACOS, 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
• Debug Printf: false
• GPU Assisted Validation: false
• Best Practices: false
• Message Severity: error, warn
• Debug Action: VK_DBG_LAYER_ACTION_LOG_MSG
• Limit Duplicated Messages: true

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
• Debug Printf: false
• GPU Assisted Validation: false
• Best Practices: false
• Message Severity: error
• Debug Action: VK_DBG_LAYER_ACTION_LOG_MSG
• Limit Duplicated Messages: true

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
• Debug Printf: false
• GPU Assisted Validation: false
• Best Practices: true
• Message Severity: error, warn, perf
• Debug Action: VK_DBG_LAYER_ACTION_LOG_MSG
• Limit Duplicated Messages: 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
• Debug Printf: false
• GPU Assisted Validation: false
• Best Practices: false
• Message Severity: error
• Debug Action: VK_DBG_LAYER_ACTION_LOG_MSG
• Limit Duplicated Messages: true

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
• Debug Printf: false
• GPU Assisted Validation: true
• Shader instrumentation: true
• Enable instrumenting shaders selectively: false
• Buffer content validation: true
• Reserve Descriptor Set Binding Slot: true
• Best Practices: false
• Message Severity: error
• Debug Action: VK_DBG_LAYER_ACTION_LOG_MSG
• Limit Duplicated Messages: true

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 Assisted Validation: false
• Debug Printf: true
• Best Practices: false
• Message Severity: error, info
• Debug Action:
• Limit Duplicated Messages: false