Lines Matching +full:set +full:- +full:array
1 <!-- markdownlint-disable MD041 -->
2 <!-- Copyright 2015-2019 LunarG, Inc. -->
8 # GPU-Assisted Validation
12 [3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License"
13 [4]: https://creativecommons.org/licenses/by-nd/4.0/
15 GPU-Assisted validation is implemented in the SPIR-V Tools optimizer and the `VK_LAYER_KHRONOS_vali…
16 soon-to-be-deprecated `VK_LAYER_LUNARG_core_validation` layer). This document covers the design of …
21 The basic operation of GPU-Assisted validation is comprised of instrumenting shader code to perform…
25 The layer instruments the shaders by passing the shader's SPIR-V bytecode to the SPIR-V optimizer c…
26 …erform an instrumentation pass to add the additional instructions to perform the run-time checking.
27 The layer then passes the resulting modified SPIR-V bytecode to the driver as part of the process o…
29 …at describes the length of all descriptor arrays and the write state of each element of each array.
32 As the shader is executed, the instrumented shader code performs the run-time checks.
34 This record is small and is on the order of a dozen 32-bit words.
36 … consecutive memory locations as long as there is space available in the pre-allocated block of de…
42 If the shader was compiled with debug information (source code and SPIR-V instruction mapping to so…
45 ## GPU-Assisted Validation Checks
47 The initial release (Jan 2019) of GPU-Assisted Validation includes checking for out-of-bounds descr…
50 The second release (Apr 2019) adds validation for out-of-bounds descriptor array indexing and use o…
53 ### Out-of-Bounds(OOB) Descriptor Array Indexing
55 Checking for correct indexing of descriptor arrays is sometimes referred to as "bind-less validatio…
56 It is called "bind-less" because a binding in a descriptor set may contain an array of like descrip…
57 And unless there is a constant or compile-time indication of which descriptor in the array is selec…
58 …ding status is considered to be ambiguous, leaving the actual binding to be determined at run-time.
60 As an example, a fragment shader program may use a variable to index an array of combined image sam…
67 The array of combined image samplers is `tex` and has 6 samplers in the array.
68 The complete validation error message issued when `tex_ind` indexes past the array is:
71 ERROR : VALIDATION - Message Id Number: 0 | Message Id Name: UNASSIGNED-Image descriptor index out …
72 …Index of 6 used to index descriptor array of length 6. Command buffer (CubeDrawCommandBuf)(0xbc24…
75 /home/user/src/Vulkan-ValidationLayers/external/Vulkan-Tools/cube/cube.frag at line 45.
78 The VK_EXT_descriptor_indexing extension allows a shader to declare a descriptor array without spec…
80 layout(set = 0, binding = 1) uniform sampler2D tex[];
82 In this case, the layer needs to tell the optimization code how big the descriptor array is so the …
85 The extension also allows descriptor set bindings to be partially bound, meaning that as long as th…
86 array elements, those elements are not required to have been written.
87 The instrumentation code needs to know which elements of a descriptor array have been written, so t…
93 ## GPU-Assisted Validation Options
95 Here are the options related to activating GPU-Assisted Validation:
97 1. Enable GPU-Assisted Validation - GPU-Assisted Validation is off by default and must be enabled.
99 …GPU-Assisted Validation is disabled by default because the shader instrumentation may introduce si…
101 GPU-Assisted Validation requires additional resources such as device memory and descriptors.
102 It is desirable for the user to opt-in to this feature because of these requirements.
106 2. Reserve a Descriptor Set Binding Slot - Modifies the value of the `VkPhysicalDeviceLimits::maxBo…
107 …property to return a value one less than the actual device's value to "reserve" a descriptor set b…
109 … only of interest to applications that dynamically adjust their descriptor set bindings to adjust …
114 The existing layer configuration file mechanism can be used to enable GPU-Assisted Validation.
140 The `VK_EXT_validation_features` extension can be used to enable GPU-Assisted Validation at CreateI…
157 ## GPU-Assisted Validation Limitations
159 There are several limitations that may impede the operation of GPU-Assisted Validation:
163 Vulkan 1.1 or later is required because the GPU instrumentation code uses SPIR-V 1.3 features.
164 Vulkan 1,1 is required to ensure that SPIR-V 1.3 is available.
171 ### Descriptor Set Binding Limit
176 When applications use all the available descriptor set binding slots,
177 GPU-Assisted Validation cannot be performed because it needs a descriptor set to
185 then GPU-Assisted Validation cannot be performed.
188 building the graphics pipeline with non-instrumented shaders instead of instrumented ones.
196 GPU-Assisted Validation does allocate device memory for the error report buffers, and if
205 binding_count is the binding number of the largest binding in the set.
208 As a best practice, when using GPU-Assisted Validation with descriptor indexing enabled,
211 If GPU-Assisted Validation device memory allocations fail, the device could become
212 unstable because some previously-built pipelines may contain instrumented shaders.
222 Any failure to allocate a descriptor set means that the instrumented shader code
244 to implement GPU-Assisted Validation without some of the limitations described above.
247 This technique removes the need to create descriptors, use a descriptor set slot,
252 ## GPU-Assisted Validation Internal Design
254 This section may be of interest to readers who are interested on how GPU-Assisted Validation is imp…
273 An alternative design allocates this block on a per-device or per-queue basis and should work.
276 * For each draw, dispatch, and trace rays call, allocate a descriptor set and update it to point to…
277 …If descriptor indexing is enabled, also update the descriptor set to point to the allocated input …
278 Fill the input buffer with the size and write state information for each descriptor array.
279 There is a descriptor set manager to handle this efficiently.
280 …ditional call down the chain to create a bind descriptor set command to bind our descriptor set at…
285 * Determine the descriptor set binding index that is eventually used to bind the descriptor set jus…
289 * When creating a ShaderModule, pass the SPIR-V bytecode to the SPIR-V optimizer to perform the ins…
290 …Pass the desired descriptor set binding index to the optimizer via a parameter so that the instrum…
294 * For all pipeline layouts, add our descriptor set to the layout, at the binding index determined e…
297 …If the incoming layout already has a descriptor set placed at our desired index, the layer must no…
298 descriptor set to the layout, replacing the one in the incoming layout.
300 non-instrumented ones when the pipeline layout is later used to create a graphics pipeline.
303 If it is, replace the instrumented shaders in the pipeline with non-instrumented ones.
305 update-after-bind.
311 The above describes only the high-level details of GPU-Assisted Validation operation.
319 From these options, the layer sets instance-scope flags in the validation layer tracking data to in…
320 GPU-Assisted Validation has been requested, along with any other associated options.
324 Much of the GPU-Assisted Validation implementation involves making "application level" Vulkan API
347 * Building the validation layer with a hack to force GPU-Assisted Validation to be enabled.
352 …* Set up the layer stack so that the "khronos_validation2" layer is on top of or before the actual…
361 * The additional API calls are not state-tracked
365 For example, any device memory allocation performed by GPU-Assisted Validation won't be
370 a later implementation of GPU-Assisted Validation using the `VK_EXT_buffer_device_address`
376 The GPU-Assisted Validation code is largely contained in one
377 [file](https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/layers/gpu_validation.cp…
382 if (GetEnables(dev_data)->gpu_validation) {
387 The GPU-Assisted Validation code is linked into the shared library for the khronos and core validat…
400 The GPU-Assisted Validation functions follow this pattern not by hooking into the top-level validat…
413 * Determine and record (save in device state) the desired descriptor set binding index.
416 * Initialize descriptor set manager
417 * Make a descriptor set layout to describe our descriptor set
418 * Make a descriptor set layout to describe a "dummy" descriptor set that contains no descriptors
420 * Record these objects in the per-device state
424 * Destroy descriptor set layouts created in CreateDevice
425 * Clean up descriptor set manager
432 * Get a descriptor set from the descriptor set manager
434 …* If descriptor indexing is enabled, get an input buffer and fill with descriptor array information
435 * Update (write) the descriptor set with the memory info
437 …* If no conflict, add an additional command to the command buffer to bind our descriptor set at ou…
438 * Record the above objects in the per-CB state
445 * Give the descriptor sets back to the descriptor set manager
451 … sets up to call the SPIR-V optimizer to run the "BindlessCheckPass", replacing the original SPIR-…
454 This function generates a "unique shader ID" that is passed to the SPIR-V optimizer,
460 Therefore, the layer keeps a "counter" in per-device state that is incremented each time a shader i…
462 This unique ID is given to the SPIR-V optimizer and is stored in the shader module state tracker af…
464 The process of instrumenting the SPIR-V also includes passing the selected descriptor set binding i…
465 to the SPIR-V optimizer which the instrumented
467 An instrumented shader is now "hard-wired" to write error records via the descriptor set at that bi…
471 The original SPIR-V bytecode is left stored in the shader module tracking data.
475 This ensures that the original SPIR-V bytecode is available if we need it to replace the instrument…
481 * Check for a descriptor set binding index conflict.
485 * Copy the original descriptor set layouts into the new pipeline layout
486 …* Pad the new pipeline layout with dummy descriptor set layouts up to but not including the last o…
487 * Add our descriptor set layout as the last one in the new pipeline layout
505 …n error about a possible deadlock if CmdWaitEvents is recorded with VK_PIPELINE_STAGE_HOST_BIT set.
509 * Examine the pipelines to see if any use the debug descriptor set binding index
511 * Create non-instrumented shader modules from the saved original SPIR-V
512 * Modify the CreateInfo data to use these non-instrumented shaders.
513 * This prevents instrumented shaders from using the application's descriptor set.
547 The shader instrumentation process performed by the SPIR-V optimizer applies descriptor index bound…
560 Instrumentation is applied to the following SPIR-V operations:
597 struct decorated with Block, or a runtime or statically-sized array of such
605 This description includes the support for future GPU-Assisted Validation features
606 such as checking for uninitialized descriptors in the partially-bound scenario.
607 These items are not used in the current implementation for descriptor array
624 The `Data` array is the uint32_t words written by the shaders of the pipeline to record bindless va…
626 Note that the `Data` array has runtime length.
627 The shader queries the length of the `Data` array to make sure that it does not write past the end …
647 <Stage-Specific Words>
648 <Validation-Specific Words>
658 The Stage is the integer value used in SPIR-V for each of the Execution Models:
661 |---------------|:-----:|
681 |---------------|------------------|------------|------------|
696 ### Validation-Specific Words
708 |-----------------------------|:----:|----------------|-----------------------|
709 |IndexOutOfBounds |0 |Descriptor Index|Descriptor Array Length|
732 [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools) repository in file
733 [`instrument.hpp`](https://github.com/KhronosGroup/SPIRV-Tools/blob/master/include/spirv-tools/inst…
737 ## GPU-Assisted Validation Error Report
751 * command buffer handle - This is easily obtained because we are looping over the command
753 * draw number - keep track of how many draws we've processed for a given command buffer.
754 * pipeline handle - The shader tracker discussed earlier contains this handle
755 * shader module handle - The "Shader ID" (Word 1 in the record) is used to lookup
757 * instruction index - This is the SPIR-V instruction index where the invalid array access occurred.
758 …It is not that useful by itself, since the user would have to use it to locate a SPIR-V instruction
759 in a SPIR-V disassembly and somehow relate it back to the shader source code.
761 The user can build the shader with debug information to get source-level information.
767 The layer then adds on error message text obtained from decoding the stage-specific and
768 validation-specific data as described earlier.
770 This completes the error report when there is no source-level debug information in the shader.
772 ### Source-Level Debug Information
774 This is one of the more complicated and code-heavy parts of the GPU-Assisted Validation feature
775 and all it really does is display source-level information when the shader is compiled
776 with debugging info (`-g` option in the case of `glslangValidator`).
782 The SPIR-V generator (e.g., glslangValidator) places an OpLine SPIR-V instruction in the
789 The layer scans the SPIR-V looking for the last OpLine instruction that appears before the instruct…
793 The filename itself is obtained by scanning the SPIR-V again for an OpString instruction that
802 The SPIR-V built with source-level debug info also contains OpSource instructions that
804 Due to possible pre-processing, the layer just cannot simply use the source file line number
805 from the OpLine to index into this set of source code lines.
822 …though the input buffer is a linear array of unsigned integers, conceptually there are arrays with…
824 …ts an array (denoted by sets_to_sizes) that is number_of_sets long, with an index that indicates t…
826 …e sets_to_sizes array is the sizes array, that contains the array size (or 1 if descriptor is not …
828 …array is the sets_to_bindings array that for each descriptor set, indexes into the bindings_to_wri…
830 …dings array, is the bindings_to_written array that for each binding in the set, indexes to the sta…
832 Lastly comes the written array, which indicates whether a given binding / array element has been wr…
836 Assume Descriptor Set 0 looks like: And Descriptor Set 1 looks like:
838 0 Array[3] 2 Array[4]
839 1 Non Array 3 Array[5]
840 3 Array[2]
847 …0 |11| sets_to_bindings 1 |3| set 0 sizes start at 3 3 |3| S0B0 11 |13| set 0 bindi…
848 …starts at 11 2 |7| set 1 sizes start at 7 4 |1| S0B1 12 |17| set 1 bindings sta…
863 Alternately, you could describe the array size and write state data as:
864 (set = s, binding = b, index = i) is not initialized if
868 and the array's size = Input[ Input[ s + 1 ] + b ]
870 ## GPU-Assisted Validation Testing
872 Validation Layer Tests (VLTs) exist for GPU-Assisted Validation.
878 They activate GPU-Assisted Validation via the programmatic