Copyright © 2015-2022 LunarG, Inc.

Creative Commons



Vulkan capabilities test coverage with the Khronos Profiles Layer

The Khronos Profiles Layer helps test across a wide range of hardware capabilities without requiring a physical copy of every device. It can be applied without modifying any application binaries, and in a fully automated fashion. The Profiles layer is a Vulkan layer that can override the values returned by your application's queries of the GPU. Profiles layer uses a JSON text configuration file to make your application see a different driver/GPU than is actually in your system. This capability is useful to verify that your application both a) properly queries the limits from Vulkan, and b) obeys those limits.

The Profiles layer is available pre-built in the Vulkan Configurator included with the Vulkan SDK.

The role of the Profiles layer is to "simulate" a Vulkan implementation by modifying the features and resources of a more-capable implementation. The Profiles layer does not add capabilities to your existing Vulkan implementation by "emulating" additional capabilities with software; e.g. the Profiles layer cannot add geometry shader capability to an actual device that doesn't already provide it. Also, the Profiles layer does not "enforce" the features being simulated. You can use the Validation Layer in conjunction with the Profiles Layer to identify where your application is not adhering to the features being simulated by the Profiles Layer.

Configuring the Profiles Layer

For an overview of how to configure layers, refer to the Layers Overview and Configuration document.

The Profiles Layer settings are documented in detail in the VK_LAYER_KHRONOS_validation document.

The Profiles Layer can also be enabled and configured using Vulkan Configurator. See the Vulkan Configurator documentation for more information.

Using the Profiles layer with Vulkan Configurator

The Profiles Layer can be controlled using environment variables or more intuitively using the Vulkan Configurator GUI application.

Vulkan Configurator The built-in Portability layers configurations in Vulkan Configurator using the Validation and the Profiles layers

The Portability layers configuration in Vulkan Configurator checks that a Vulkan application follows the requirements of a Vulkan Profile. This layers configuration relies on the Vulkan Profiles layer to override the Vulkan device capabilities and the Vulkan Validation Layer to check that the Vulkan application doesn't rely on capabilities not supported by the selected profile.

The input to the Profiles layer is a profiles file that is using the flexible JSON syntax. The profiles file format is defined by a formal JSON schema, so any profiles file may be verified to be correct using freely available JSON validators. Examination of the schema file reveals the extent of parameters that are available for configuration.

To use the Profiles Layer Vulkan version 1.1 is required.

Example of a Profiles layer JSON profiles file: VP_LUNARG_test_structure_simple.json


To enable, use a setting with the path of the profiles file to load:

adb shell settings put global debug.vulkan.khronos_profiles.profile_file <path/to/profiles/JSON/file>

Optional: use settings to enable debugging output and exit-on-error:

adb shell settings put global debug.vulkan.khronos_profiles.debug_reports DEBUG_REPORT_DEBUG_BIT
adb shell settings put global debug.vulkan.khronos_profiles.debug_fail_on_error true

Technical Details

The Profiles Layer is a Vulkan layer that can modify the results of Vulkan PhysicalDevice queries based on a profiles file (JSON format), thus simulating some of the capabilities of a device by overriding the capabilities of the actual device under test.

Please note that this device simulation layer "simulates", rather than "emulates". By that we mean that the layer cannot add emulated capabilities that do not already exist in the system's underlying actual device. The Profiles layer will not enable a less-capable device to emulate a more-capable device.

Application code can be tested to verify it responds correctly to the capabilities reported by the simulated device. That could include:

The fail_on_error option can be used to make sure the device supports the requested capabilities. In this case if an application erroneously attempts to overcommit a resource, or use a disabled feature, the Profiles layer will return VK_ERROR_INITIALIZATION_FAILED from vkEnumeratePhysicalDevices().

The Profiles layer will work together with other Vulkan layers, such as the Validation layer. When configuring the order of the layers, the Profiles layer should be "last"; i.e.: closest to the driver, furthest from the application. That allows the Validation layer to see the results of the Profiles layer, and enable Validation to flag incorrect API usage beyond the simulated capabilities.

If you find issues, please report to Khronos' Vulkan-Profiles GitHub repository.

Profiles Layer operation and profiles file

At application startup, during vkEnumeratePhysicalDevices(), the Profiles layer initializes its internal tables from the actual physical device in the system, then loads the profiles file, which specifies override values to apply to those internal tables.

JSON file formats consumed by the Profiles layer are specified by the following JSON schema

The schema permits additional top-level sections to be optionally included in profiles files; any additional top-level sections will be ignored by the Profiles layer.

The schemas define basic range checking for common Vulkan data types, but they cannot detect whether a particular profile is illogical. If a profile defines capabilities beyond what the actual device is natively capable of providing and the fail_on_error option is not used, the results are undefined. The Profiles layer has some simple checking of profile values and writes debug messages (if enabled) for values that are incompatible with the capabilities of the actual device.

This version of the Profiles layer currently supports Vulkan v1.3 and below including all Vulkan extensions. If the application requests an unsupported version of the Vulkan API, the Profiles layer will emit an error message.

When a Vulkan extension gets promoted so can the structures it defines. It is invalid for a profile to specify a structure and its promoted version at the same time. In this case the Profiles layer will use the promoted version of the structure and emit a warning.

VK_KHR_portability_subset Emulation

The Profiles layer provides the ability to emulate the VK_KHR_portability_subset extension on devices that do not implement this extension. This feature allows users to test their application with limitations found on non-conformant Vulkan implementations. To turn on this feature, enable it as described below.

Layer Details

Layer Properties

Layer Settings Overview

Setting Type Default Value vk_layer_settings.txt Variable Environment Variable Platforms
Profile Selection LOAD_FILE VP_LUNARG_desktop_portability_2021.json khronos_profiles.profile_file VK_KHRONOS_PROFILES_PROFILE_FILE WINDOWS, LINUX, MACOS
Schema Validation BOOL false khronos_profiles.profile_validation VK_KHRONOS_PROFILES_PROFILE_VALIDATION WINDOWS, LINUX, MACOS
Emulate VK_KHR_portability_subset BOOL true khronos_profiles.emulate_portability VK_KHRONOS_PROFILES_EMULATE_PORTABILITY WINDOWS, LINUX
Exclude Device Extensions LIST khronos_profiles.exclude_device_extensions VK_KHRONOS_PROFILES_EXCLUDE_DEVICE_EXTENSIONS WINDOWS, LINUX, MACOS
Exclude Formats LIST khronos_profiles.exclude_formats VK_KHRONOS_PROFILES_EXCLUDE_FORMATS WINDOWS, LINUX, MACOS
Log Filename SAVE_FILE profiles_layer_log.txt khronos_profiles.debug_filename VK_KHRONOS_PROFILES_DEBUG_FILENAME WINDOWS, LINUX, MACOS
Clear Log at Launch BOOL true khronos_profiles.debug_file_clear VK_KHRONOS_PROFILES_DEBUG_FILE_CLEAR WINDOWS, LINUX, MACOS
Fail on Error BOOL false khronos_profiles.debug_fail_on_error VK_KHRONOS_PROFILES_DEBUG_FAIL_ON_ERROR WINDOWS, LINUX, MACOS

Layer Settings Details

Profile Selection

Path of a profile file and the name of the profile to load.

Setting Properties:

Setting Type: LOAD_FILE - Setting Default Value: VP_LUNARG_desktop_portability_2021.json


Name of the profile specified by the profile file to use. If set to ${VP_DEFAULT}, the layer will load the first profile in the file.

Setting Properties:

Setting Type: ENUM - Setting Default Value: ${VP_DEFAULT}

Schema Validation

Validate the profile file against the Vulkan SDK profile schema if the file is found.

Setting Properties:

Setting Type: BOOL - Setting Default Value: false

Emulate VK_KHR_portability_subset

Emulate the VK_KHR_portability_subset extension on the device.

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Simulate Profile Capabilities

Control of the simulated capabilities of the Vulkan physical device from the selected Vulkan Profile.

Setting Properties:


Flags Label Description Platforms
SIMULATE_API_VERSION_BIT Version The Vulkan device will report the API version from the selected Profile. It also overrides the api-version set in VkPhysicalDeviceProperties. WINDOWS, LINUX, MACOS
SIMULATE_FEATURES_BIT Features The Vulkan device will report the features from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_PROPERTIES_BIT Properties The Vulkan device will report the properties from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_EXTENSIONS_BIT Device Extensions The Vulkan device will report the extensions from the selected Profile. WINDOWS, LINUX, MACOS
SIMULATE_FORMATS_BIT Formats The Vulkan device will report the formats from the selected Profile. WINDOWS, LINUX, MACOS

Exclude Device Extensions

Removes the listed device extensions from being reported by the Vulkan physical device.

Setting Properties:

Setting Type: LIST - Setting Default Value:

Exclude Formats

Removes the format feature flags from being reported by the Vulkan physical device.

Setting Properties:

Setting Type: LIST - Setting Default Value:

Debug Actions

This indicates what action is to be taken when a layer wants to report information

Setting Properties:

Setting Type: FLAGS - Setting Default Value: DEBUG_ACTION_STDOUT_BIT

Flags Label Description Platforms
DEBUG_ACTION_STDOUT_BIT Log to stdout Log messages using the stdout. WINDOWS, LINUX, MACOS
DEBUG_ACTION_OUTPUT_BIT Log to OutputDebugString Log messages using the Windows OutputDebugString for Vulkan Studio output display. WINDOWS
DEBUG_ACTION_FILE_BIT Log to File Log messages to a file. WINDOWS, LINUX, MACOS
DEBUG_ACTION_BREAKPOINT_BIT Break Trigger a breakpoint if a debugger is in use. WINDOWS, LINUX, MACOS

Log Filename

Specifies the output filename

Setting Properties:

Setting Type: SAVE_FILE - Setting Default Value: profiles_layer_log.txt

Clear Log at Launch

Discard the content of the log file between each layer run

Setting Properties:

Setting Type: BOOL - Setting Default Value: true

Fail on Error

If the device doesn't support the capabilities of the selected Profile, the layer fail to load. When enabled, vkEnumeratePhysicalDevices will fail when the selected Profile is not supported.

Setting Properties:

Setting Type: BOOL - Setting Default Value: false

Message Types

This is a comma-delineated list of options telling the layer what types of messages it should report back

Setting Properties:


Flags Label Description Platforms
DEBUG_REPORT_WARNING_BIT 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
DEBUG_REPORT_DEBUG_BIT Debug Report debug information for the Profiles Layer development. WINDOWS, LINUX, MACOS

Layer Presets

LunarG Desktop Portability

Check the Vulkan 1.1 application will run on Windows, Linux and macOS platforms without exceeding ecosystem effective devices capabilities

Preset Setting Values:

Khronos Roadmap 2022

Check the Vulkan 1.3 application will run on the Khronos Roadmap 2022 Profile devices

Preset Setting Values:

Android Baseline 2021

Check the Vulkan 1.0 application will run on the Android Baseline 2022 Profile devices

Preset Setting Values: