Home | History | Annotate | only in /external/vulkan-validation-layers/layers
Up to higher level directory
NameDateSize
.clang-format05-Oct-2017133
CMakeLists.txt05-Oct-20178.7K
core_validation.cpp05-Oct-2017642K
core_validation.h05-Oct-20178.3K
core_validation_error_enums.h05-Oct-201719.9K
core_validation_types.h05-Oct-201726.3K
descriptor_sets.cpp05-Oct-201781.6K
descriptor_sets.h05-Oct-201719.7K
image.cpp05-Oct-201792.1K
image.h05-Oct-20173.5K
linux/05-Oct-2017
object_tracker.cpp05-Oct-2017206.5K
object_tracker.h05-Oct-20177.6K
parameter_name.h05-Oct-20176.1K
parameter_validation.cpp05-Oct-2017271.9K
parameter_validation_utils.h05-Oct-201740.2K
README.md05-Oct-20177.7K
spec.py05-Oct-201730K
swapchain.cpp05-Oct-2017133.6K
swapchain.h05-Oct-201713.2K
threading.cpp05-Oct-201718.5K
threading.h05-Oct-201716.7K
unique_objects.cpp05-Oct-201736.9K
unique_objects.h05-Oct-20174.5K
vk_layer_config.cpp05-Oct-201710.4K
vk_layer_config.h05-Oct-20172.8K
vk_layer_data.h05-Oct-20171.4K
vk_layer_extension_utils.cpp05-Oct-20172.1K
vk_layer_extension_utils.h05-Oct-20171.4K
vk_layer_logging.h05-Oct-201716.1K
vk_layer_settings.txt05-Oct-20174.2K
vk_layer_table.cpp05-Oct-20177.6K
vk_layer_table.h05-Oct-20172.3K
vk_layer_utils.cpp05-Oct-201737.9K
vk_layer_utils.h05-Oct-20175.5K
vk_validation_error_database.txt05-Oct-2017832.7K
vk_validation_error_messages.h05-Oct-2017837.1K
vk_validation_layer_details.md05-Oct-201764.6K
windows/05-Oct-2017

README.md

      1 # Layer Description and Status
      2 
      3 ## Layer Library Interface
      4 
      5 All layer libraries must support the layer library interface defined in
      6 [`LoaderAndLayerInterface.md`][].
      7 
      8 [`LoaderAndLayerInterface.md`]: ../loader/LoaderAndLayerInterface.md#layer-library-interface
      9 
     10 ## Overview
     11 
     12 Layer libraries can be written to intercept or hook VK entry points for various
     13 debug and validation purposes.  One or more VK entry points can be defined in your Layer
     14 library.  Undefined entrypoints in the Layer library will be passed to the next Layer which
     15 may be the driver.  Multiple layer libraries can be chained (actually a hierarchy) together.
     16 vkEnumerateInstanceLayerProperties can be called to list the
     17 available layers and their properties.  Layers can intercept all Vulkan commands
     18 that take a dispatchable object as it's first argument. I.e.  VkInstance, VkPhysicalDevice,
     19 VkDevice, VkCommandBuffer, and VkQueue.
     20 vkXXXXGetProcAddr is used internally by the Layers and Loader to initialize dispatch tables.
     21 Layers can also be activated via the VK_INSTANCE_LAYERS environment variable.
     22 
     23 All validation layers work with the DEBUG_REPORT extension to provide validation feedback.
     24 When a validation layer is enabled, it will look for a vk_layer_settings.txt file (see"Using
     25 Layers" section below for more details) to define its logging behavior, which can include
     26 sending output to a file, stdout, or debug output (Windows). Applications can also register
     27 debug callback functions via the DEBUG_REPORT extension to receive callbacks when validation
     28 events occur. Application callbacks are independent of settings in a vk_layer_settings.txt
     29 file which will be carried out separately. If no vk_layer_settings.txt file is present and
     30 no application callbacks are registered, error messages will be output through default
     31 logging callbacks.
     32 
     33 ### Layer library example code
     34 
     35 Note that some layers are code-generated and will therefore exist in the directory `(build_dir)/layers`
     36 
     37 `include/vkLayer.h` - header file for layer code.
     38 
     39 ### Layer Details
     40 For complete details of current validation layers, including all of the validation checks that they perform, please refer to the document `layers/vk_validation_layer_details.md`. Below is a brief overview of each layer.
     41 
     42 ### Standard Validation
     43 This is a meta-layer managed by the loader. (name = `VK_LAYER_LUNARG_standard_validation`) - specifying this layer name will cause the loader to load the all of the standard validation layers (listed below) in the following optimal order:  `VK_LAYER_GOOGLE_threading`, `VK_LAYER_LUNARG_parameter_validation`, `VK_LAYER_LUNARG_object_tracker`, `VK_LAYER_LUNARG_image`, `VK_LAYER_LUNARG_core_validation`,` VK_LAYER_LUNARG_swapchain`, and `VK_LAYER_GOOGLE_unique_objects`. Other layers can be specified and the loader will remove duplicates.
     44 
     45 ### Object Validation and Statistics
     46 (build dir)/layers/object_tracker.cpp (name=`VK_LAYER_LUNARG_object_tracker`) - Track object creation, use, and destruction. As objects are created they are stored in a map. As objects are used the layer verifies they exist in the map, flagging errors for unknown objects. As objects are destroyed they are removed from the map. At `vkDestroyDevice()` and `vkDestroyInstance()` times, if any objects have not been destroyed they are reported as leaked objects. If a Dbg callback function is registered this layer will use callback function(s) for reporting, otherwise it will use stdout.
     47 
     48 ### Validate API State and Shaders
     49 layers/core\_validation.cpp (name=`VK_LAYER_LUNARG_core_validation`) - The core\_validation layer does the bulk of the API validation that requires storing state. Some of the state it tracks includes the Descriptor Set, Pipeline State, Shaders, and dynamic state, and memory objects and bindings. It performs some point validation as states are created and used, and further validation Draw call and QueueSubmit time. Of primary interest is making sure that the resources bound to Descriptor Sets correctly align with the layout specified for the Set. Also, all of the image and buffer layouts are validated to make sure explicit layout transitions are properly managed. Related to memory, core\_validation includes tracking object bindings, memory hazards, and memory object lifetimes. It also validates several other hazard-related issues related to command buffers, fences, and memory mapping. Additionally core\_validation include shader validation (formerly separate shader\_checker layer) that inspects the SPIR-V shader images and fixed function pipeline stages at PSO creation time. It flags errors when inconsistencies are found across interfaces between shader stages. The exact behavior of the checks depends on the pair of pipeline stages involved. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout.
     50 
     51 ### Check parameters
     52 layers/parameter_validation.cpp (name=`VK_LAYER_LUNARG_parameter_validation`) - Check the input parameters to API calls for validity. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout.
     53 
     54 ### Image Validity
     55 layers/image.cpp (name=`VK_LAYER_LUNARG_image`) - The image layer is intended to validate image parameters, formats, and correct use. Images are a significant enough area that they were given a separate layer. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout.
     56 
     57 ### Check threading
     58 layers/threading.cpp (name=`VK_LAYER_GOOGLE_threading`) - Check multithreading of API calls for validity. Currently this checks that only one thread at a time uses an object in free-threaded API calls. If a Dbg callback function is registered, this layer will use callback function(s) for reporting, otherwise uses stdout.
     59 
     60 ### Swapchain
     61 layers/swapchain.cpp (name=`VK_LAYER_LUNARG_swapchain`) - Check that WSI extensions are being used correctly.
     62 
     63 ### Unique Objects
     64 (build dir)/layers/unique_objects.cpp (name=`VK_LAYER_GOOGLE_unique_objects`) - The Vulkan specification allows objects that have non-unique handles. This makes tracking object lifetimes difficult in that it is unclear which object is being referenced on deletion. The unique_objects layer was created to address this problem. If loaded in the correct position (last, which is closest to the display driver) it will alias all objects with a unique object representation, allowing proper object lifetime tracking. This layer does no validation on its own and may not be required for the proper operation of all layers or all platforms. One sign that it is needed is the appearance of errors emitted from the object_tracker layer indicating the use of previously destroyed objects.
     65 
     66 ## Using Layers
     67 
     68 1. Build VK loader using normal steps (cmake and make)
     69 2. Place `libVkLayer_<name>.so` in the same directory as your VK test or app:
     70 
     71     `cp build/layer/libVkLayer_threading.so  build/tests`
     72 
     73     This is required for the Loader to be able to scan and enumerate your library.
     74     Alternatively, use the `VK_LAYER_PATH` environment variable to specify where the layer libraries reside.
     75 
     76 3. To specify how your layers should behave, create a vk_layer_settings.txt file. This file can exist in the same directory as your app or in a directory given by the `VK_LAYER_SETTINGS_PATH` environment variable. Alternatively, you can use any filename you want if you set `VK_LAYER_SETTINGS_PATH` to the full path of the file, rather than the directory that contains it.
     77 
     78     Model the file after the following example:  [*vk_layer_settings.txt*](vk_layer_settings.txt)
     79 
     80 4. Specify which layers to activate using environment variables.
     81 
     82     `export VK\_INSTANCE\_LAYERS=VK\_LAYER\_LUNARG\_parameter\_validation:VK\_LAYER\_LUNARG\_core\_validation`
     83     `cd build/tests; ./vkinfo`
     84 
     85 
     86 ## Status
     87 
     88 
     89 ### Current known issues
     90 
     91