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: Vulkan Configurator, application defined
, vk_layer_settings.txt
, environment variables
as described in the layers configuration documentation and described in the Configuring Vulkan Layers whitepaper.
Vulkan Configurator
We suggest people to use Vulkan Configurator.
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 Settings
We suggest using Vulkan Configurator to discover the layer settings, but the following is generated per SDK version
The settings for this layer are specified in VkLayer_khronos_validation.json
. The settings details are in khronos_validation_layer.html.
Layer Properties
- API Version: 1.4.321
- 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: 65
- Number of Layer Presets: 6
Layer Settings Overview
Label | Variables Key | Type | Default Value | Platforms |
---|---|---|---|---|
Validation Areas | validation_control |
GROUP |
`` | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Fine Grained Locking | fine_grained_locking |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Core | validate_core |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Image Layout | check_image_layout |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Command Buffer State | check_command_buffer |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Object in Use | check_object_in_use |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Query | check_query |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Shader | check_shaders |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Caching | check_shaders_caching |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Handle Wrapping | unique_handles |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Object Lifetime | object_lifetime |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Stateless Parameter | stateless_param |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Thread Safety | thread_safety |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Synchronization | validate_sync |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Submit time validation | syncval_submit_time_validation |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Shader accesses heuristic | syncval_shader_accesses_heuristic |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Error messages | syncval_reporting |
GROUP |
`` | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Extra properties | syncval_message_extra_properties |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Debug Printf | printf_enable |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Redirect Printf messages to stdout | printf_to_stdout |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Printf verbose | printf_verbose |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Printf buffer size | printf_buffer_size |
INT |
1024 |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
GPU Assisted Validation | gpuav_enable |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Safe Mode | gpuav_safe_mode |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Force on robustness features | gpuav_force_on_robustness |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Shader instrumentation | gpuav_shader_instrumentation |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Enable instrumenting shaders selectively | gpuav_select_instrumented_shaders |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX |
Shader/pipeline name regexes | gpuav_shaders_to_instrument |
LIST |
`` | WINDOWS_X86 , WINDOWS_ARM , LINUX |
Best Practices | validate_best_practices |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
ARM-specific best practices | validate_best_practices_arm |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
AMD-specific best practices | validate_best_practices_amd |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS |
IMG-specific best practices | validate_best_practices_img |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS |
NVIDIA-specific best practices | validate_best_practices_nvidia |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , ANDROID |
Debug Action | debug_action |
FLAGS |
VK_DBG_LAYER_ACTION_LOG_MSG |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Log Filename | log_filename |
SAVE_FILE |
stdout |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Message Severity | report_flags |
FLAGS |
error |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Limit Duplicated Messages | enable_message_limit |
BOOL |
true |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Max Duplicated Messages | duplicate_message_limit |
INT |
10 |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Mute Message VUIDs | message_id_filter |
LIST |
`` | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Message Format | message_format |
GROUP |
`` | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
JSON | message_format_json |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Display Application Name | message_format_display_application_name |
BOOL |
false |
WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Layer Settings Details
Validation Areas
Control of the Validation layer validation.
Sub-settings: Fine Grained Locking, Core, Handle Wrapping, Object Lifetime, Stateless Parameter, Thread Safety, Synchronization, Debug Printf only preset, Debug Printf, GPU Assisted Validation, and Best Practices.
- Key:
validation_control
- 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.
Learn more about the Fine Grained Locking setting.
- Key:
fine_grained_locking
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.fine_grained_locking = true |
Environment variables: | export VK_KHRONOS_VALIDATION_FINE_GRAINED_LOCKING=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.fine_grained_locking 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.
Learn more about the Core setting.
Sub-settings: Image Layout, Command Buffer State, Object in Use, Query, and Shader.
- Key:
validate_core
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.validate_core = true |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_CORE=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.validate_core 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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
- Key:
check_image_layout
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_image_layout = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_IMAGE_LAYOUT=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_image_layout 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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
- Key:
check_command_buffer
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_command_buffer = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_COMMAND_BUFFER=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_command_buffer true |
Object in Use
Check that Vulkan objects are not in use by a command buffer when they are destroyed.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
- Key:
check_object_in_use
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_object_in_use = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_OBJECT_IN_USE=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_object_in_use true |
Query
Checks for commands that use VkQueryPool objects.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
- Key:
check_query
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_query = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_QUERY=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_query true |
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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
Sub-settings: Caching, and Disable spirv-val.
- Key:
check_shaders
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_shaders = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_SHADERS=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_shaders true |
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.
All the following condition must be fulfilled for the setting to be applied.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Core | validate_core |
BOOL | true |
Shader | check_shaders |
BOOL | true |
- Key:
check_shaders_caching
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.check_shaders_caching = true |
Environment variables: | export VK_KHRONOS_VALIDATION_CHECK_SHADERS_CACHING=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.check_shaders_caching true |
Handle Wrapping
Handle wrapping checks. Disable this feature if you are experiencing crashes when creating new extensions or developing new Vulkan objects/structures.
Learn more about the Handle Wrapping setting.
- Key:
unique_handles
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.unique_handles = true |
Environment variables: | export VK_KHRONOS_VALIDATION_UNIQUE_HANDLES=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.unique_handles true |
Object Lifetime
Object tracking checks. This may not always be necessary late in a development cycle.
Learn more about the Object Lifetime setting.
- Key:
object_lifetime
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.object_lifetime = true |
Environment variables: | export VK_KHRONOS_VALIDATION_OBJECT_LIFETIME=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.object_lifetime true |
Stateless Parameter
Stateless parameter checks. This may not always be necessary late in a development cycle.
Learn more about the Stateless Parameter setting.
- Key:
stateless_param
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.stateless_param = true |
Environment variables: | export VK_KHRONOS_VALIDATION_STATELESS_PARAM=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.stateless_param 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.
Learn more about the Thread Safety setting.
- Key:
thread_safety
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.thread_safety = true |
Environment variables: | export VK_KHRONOS_VALIDATION_THREAD_SAFETY=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.thread_safety true |
Synchronization
Check for resource access conflicts caused by missing or incorrectly used synchronization operations.
Learn more about the Synchronization setting.
Sub-settings: Submit time validation, Shader accesses heuristic, and Error messages.
- Key:
validate_sync
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_sync = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_SYNC=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.validate_sync false |
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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Synchronization | validate_sync |
BOOL | true |
- Key:
syncval_submit_time_validation
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.syncval_submit_time_validation = true |
Environment variables: | export VK_KHRONOS_VALIDATION_SYNCVAL_SUBMIT_TIME_VALIDATION=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.syncval_submit_time_validation true |
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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Synchronization | validate_sync |
BOOL | true |
- Key:
syncval_shader_accesses_heuristic
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.syncval_shader_accesses_heuristic = false |
Environment variables: | export VK_KHRONOS_VALIDATION_SYNCVAL_SHADER_ACCESSES_HEURISTIC=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.syncval_shader_accesses_heuristic false |
Error messages
Options to configure synchronization validation error reporting.
Sub-setting: Extra properties,
- Key:
syncval_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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Synchronization | validate_sync |
BOOL | true |
- Key:
syncval_message_extra_properties
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.syncval_message_extra_properties = false |
Environment variables: | export VK_KHRONOS_VALIDATION_SYNCVAL_MESSAGE_EXTRA_PROPERTIES=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.syncval_message_extra_properties false |
Debug Printf
Enable DebugPrintf and will print anything use NonSemantic.DebugPrintf in their SPIR-V.
Learn more about the Debug Printf setting.
Sub-settings: Redirect Printf messages to stdout, Printf verbose, and Printf buffer size.
- Key:
printf_enable
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.printf_enable = false |
Environment variables: | export VK_KHRONOS_VALIDATION_PRINTF_ENABLE=false |
Redirect Printf messages to stdout
Enable redirection of Debug Printf messages from the debug callback to stdout.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Debug Printf | printf_enable |
BOOL | true |
- Key:
printf_to_stdout
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.printf_to_stdout = true |
Environment variables: | export VK_KHRONOS_VALIDATION_PRINTF_TO_STDOUT=true |
Printf verbose
Will print out handles, instruction location, position in command buffer, and more.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Debug Printf | printf_enable |
BOOL | true |
- Key:
printf_verbose
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.printf_verbose = false |
Environment variables: | export VK_KHRONOS_VALIDATION_PRINTF_VERBOSE=false |
Printf buffer size
Set the size in bytes of the buffer per draw/dispatch/traceRays to hold the messages.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Debug Printf | printf_enable |
BOOL | true |
- Key:
printf_buffer_size
- Type:
INT
- Default Value:
1024
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
int32_t data[] = { 1024 }; |
vk_layer_settings.txt : |
khronos_validation.printf_buffer_size = 1024 |
Environment variables: | export VK_KHRONOS_VALIDATION_PRINTF_BUFFER_SIZE=1024 |
GPU Assisted Validation
Enable validation that cannot be done the CPU and needs hooks into the GPU execution.
Learn more about the GPU Assisted Validation setting.
Sub-settings: Safe Mode, Force on robustness features, Shader instrumentation, Buffer content validation, Advanced Settings, and Developer Debug Settings.
- Key:
gpuav_enable
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_enable = false |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_ENABLE=false |
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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
GPU Assisted Validation | gpuav_enable |
BOOL | true |
- Key:
gpuav_safe_mode
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_safe_mode = false |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_SAFE_MODE=false |
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.
Dependences | Variables Key | Type | Value |
---|---|---|---|
GPU Assisted Validation | gpuav_enable |
BOOL | true |
- Key:
gpuav_force_on_robustness
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_force_on_robustness = false |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_FORCE_ON_ROBUSTNESS=false |
Shader instrumentation
Instrument shaders to validate descriptors, descriptor indexing, buffer device addresses and ray queries. Warning: will considerably slow down shader executions.
Learn more about the Shader instrumentation setting.
Dependences | Variables Key | Type | Value |
---|---|---|---|
GPU Assisted Validation | gpuav_enable |
BOOL | true |
Sub-settings: Enable instrumenting shaders selectively, Descriptors indexing, Post process descriptor indexing, Out of bounds buffer device addresses, RayQuery SPIR-V instructions, and Out of bounds vertex attribute fetching.
- Key:
gpuav_shader_instrumentation
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_shader_instrumentation = true |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_SHADER_INSTRUMENTATION=true |
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.
Learn more about the Enable instrumenting shaders selectively setting.
All the following condition must be fulfilled for the setting to be applied.
Dependences | Variables Key | Type | Value |
---|---|---|---|
GPU Assisted Validation | gpuav_enable |
BOOL | true |
Shader instrumentation | gpuav_shader_instrumentation |
BOOL | true |
Sub-setting: Shader/pipeline name regexes,
- Key:
gpuav_select_instrumented_shaders
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_select_instrumented_shaders = false |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_SELECT_INSTRUMENTED_SHADERS=false |
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.
All the following condition must be fulfilled for the setting to be applied.
Dependences | Variables Key | Type | Value |
---|---|---|---|
GPU Assisted Validation | gpuav_enable |
BOOL | true |
Shader instrumentation | gpuav_shader_instrumentation |
BOOL | true |
Enable instrumenting shaders selectively | gpuav_select_instrumented_shaders |
BOOL | true |
- Key:
gpuav_shaders_to_instrument
- Type:
LIST
- Default Value:
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
Methods: | |
---|---|
VK_EXT_layer_settings : |
const char* data[] = { "" }; |
vk_layer_settings.txt : |
khronos_validation.gpuav_shaders_to_instrument = |
Environment variables: | export VK_KHRONOS_VALIDATION_GPUAV_SHADERS_TO_INSTRUMENT= |
Best Practices
Outputs warnings related to common misuse of the API, but which are not explicitly prohibited by the specification.
Learn more about the Best Practices setting.
Sub-settings: ARM-specific best practices, AMD-specific best practices, IMG-specific best practices, and NVIDIA-specific best practices.
- Key:
validate_best_practices
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_best_practices = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.validate_best_practices false |
ARM-specific best practices
Outputs warnings for spec-conforming but non-ideal code on ARM GPUs.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Best Practices | validate_best_practices |
BOOL | true |
- Key:
validate_best_practices_arm
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_best_practices_arm = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_ARM=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.validate_best_practices_arm false |
AMD-specific best practices
Outputs warnings for spec-conforming but non-ideal code on AMD GPUs.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Best Practices | validate_best_practices |
BOOL | true |
- Key:
validate_best_practices_amd
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_best_practices_amd = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_AMD=false |
IMG-specific best practices
Outputs warnings for spec-conforming but non-ideal code on Imagination GPUs.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Best Practices | validate_best_practices |
BOOL | true |
- Key:
validate_best_practices_img
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_best_practices_img = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_IMG=false |
NVIDIA-specific best practices
Outputs warnings for spec-conforming but non-ideal code on NVIDIA GPUs.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Best Practices | validate_best_practices |
BOOL | true |
- Key:
validate_best_practices_nvidia
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.validate_best_practices_nvidia = false |
Environment variables: | export VK_KHRONOS_VALIDATION_VALIDATE_BEST_PRACTICES_NVIDIA=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.validate_best_practices_nvidia false |
Debug Action
Specifies what action is to be taken when a layer reports information.
- Key:
debug_action
- Type:
FLAGS
- Default Value:
VK_DBG_LAYER_ACTION_LOG_MSG
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Flags | Label | Description | Platforms |
---|---|---|---|
VK_DBG_LAYER_ACTION_LOG_MSG |
Log Message | Log a txt message to stdout or to a log filename. | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
VK_DBG_LAYER_ACTION_DEBUG_OUTPUT |
Debug Output | Log a txt message using the Windows OutputDebugString function. | WINDOWS_X86 , WINDOWS_ARM |
VK_DBG_LAYER_ACTION_BREAK |
Break | Trigger a breakpoint if a debugger is in use. | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Methods: | |
---|---|
VK_EXT_layer_settings : |
const char* data[] = { "VK_DBG_LAYER_ACTION_LOG_MSG" }; |
vk_layer_settings.txt : |
khronos_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG |
Environment variables: | export VK_KHRONOS_VALIDATION_DEBUG_ACTION=VK_DBG_LAYER_ACTION_LOG_MSG |
Android system properties: | adb setprop debug.vulkan.khronos_validation.debug_action VK_DBG_LAYER_ACTION_LOG_MSG |
Log Filename
Specifies the output filename.
- Key:
log_filename
- Type:
SAVE_FILE
- Default Value:
stdout
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
const char* data[] = { "stdout" }; |
vk_layer_settings.txt : |
khronos_validation.log_filename = stdout |
Environment variables: | export VK_KHRONOS_VALIDATION_LOG_FILENAME=stdout |
Android system properties: | adb setprop debug.vulkan.khronos_validation.log_filename stdout |
Message Severity
Comma-delineated list of options specifying the types of messages to be reported.
- Key:
report_flags
- Type:
FLAGS
- Default Value:
error
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Flags | Label | Description | Platforms |
---|---|---|---|
info |
Info | Report informational messages. | WINDOWS_X86 , WINDOWS_ARM , 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_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
perf |
Performance | Report usage of the API that may cause suboptimal performance. | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
error |
Error | Report errors in API usage. | WINDOWS_X86 , WINDOWS_ARM , LINUX , MACOS , ANDROID |
Methods: | |
---|---|
VK_EXT_layer_settings : |
const char* data[] = { "error" }; |
vk_layer_settings.txt : |
khronos_validation.report_flags = error |
Environment variables: | export VK_KHRONOS_VALIDATION_REPORT_FLAGS=error |
Android system properties: | adb setprop debug.vulkan.khronos_validation.report_flags error |
Limit Duplicated Messages
Enable limiting of duplicate messages.
Sub-setting: Max Duplicated Messages,
- Key:
enable_message_limit
- Type:
BOOL
- Default Value:
true
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_TRUE }; |
vk_layer_settings.txt : |
khronos_validation.enable_message_limit = true |
Environment variables: | export VK_KHRONOS_VALIDATION_ENABLE_MESSAGE_LIMIT=true |
Android system properties: | adb setprop debug.vulkan.khronos_validation.enable_message_limit true |
Max Duplicated Messages
Maximum number of times any single validation message should be reported.
Dependences | Variables Key | Type | Value |
---|---|---|---|
Limit Duplicated Messages | enable_message_limit |
BOOL | true |
- Key:
duplicate_message_limit
- Type:
INT
- Default Value:
10
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
int32_t data[] = { 10 }; |
vk_layer_settings.txt : |
khronos_validation.duplicate_message_limit = 10 |
Environment variables: | export VK_KHRONOS_VALIDATION_DUPLICATE_MESSAGE_LIMIT=10 |
Android system properties: | adb setprop debug.vulkan.khronos_validation.duplicate_message_limit 10 |
Mute Message VUIDs
List of VUIDs and VUID identifiers which are to be IGNORED by the validation layer.
- Key:
message_id_filter
- Type:
LIST
- Default Value:
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
const char* data[] = { "" }; |
vk_layer_settings.txt : |
khronos_validation.message_id_filter = |
Environment variables: | export VK_KHRONOS_VALIDATION_MESSAGE_ID_FILTER= |
Android system properties: | adb setprop debug.vulkan.khronos_validation.message_id_filter |
Message Format
Specifies how error messages are reported.
Sub-settings: JSON, and Display Application Name.
- Key:
message_format
- Type:
GROUP
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
JSON
Display Validation as JSON (VkDebugUtilsMessengerCallbackDataEXT::pMessage will contain JSON).
- Key:
message_format_json
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.message_format_json = false |
Environment variables: | export VK_KHRONOS_VALIDATION_MESSAGE_FORMAT_JSON=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.message_format_json false |
Display Application Name
Useful when running multiple instances to know which instance the message is from.
- Key:
message_format_display_application_name
- Type:
BOOL
- Default Value:
false
- Platforms:
WINDOWS_X86
,WINDOWS_ARM
,LINUX
,MACOS
,ANDROID
Methods: | |
---|---|
VK_EXT_layer_settings : |
VkBool32 data[] = { VK_FALSE }; |
vk_layer_settings.txt : |
khronos_validation.message_format_display_application_name = false |
Environment variables: | export VK_KHRONOS_VALIDATION_MESSAGE_FORMAT_DISPLAY_APPLICATION_NAME=false |
Android system properties: | adb setprop debug.vulkan.khronos_validation.message_format_display_application_name false |
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