1<!-- markdownlint-disable MD041 -->
2<!-- Copyright 2015-2021 LunarG, Inc. -->
3[![Khronos Vulkan][1]][2]
4
5[1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/"
6[2]: https://www.khronos.org/vulkan/
7
8# Synchronization Validation
9
10Synchronization Validation
11
12Synchronization Validation is implemented in the `VK_LAYER_KHRONOS_validation layer`. When enabled, the Synchronization Object is intended to identify resource access conflicts due to missing or incorrect synchronization operations between actions (Draw, Copy, Dispatch, Blit) reading or writing the same regions of memory.
13
14Synchronization will ideally be run periodically after resolving any outstanding validation checks from all other validation objects, so that issues may be addressed in early stages of development.
15
16Synchronization can easily be enabled and configured using the [Vulkan Configurator](https://vulkan.lunarg.com/doc/sdk/latest/windows/vkconfig.html) included with the Vulkan SDK. You can also manually enable Synchronization following instructions below.
17
18
19
20The specific areas covered by this layer are currently tracked in the
21[Synchronization Validation Project](https://github.com/KhronosGroup/Vulkan-ValidationLayers/projects/5).
22Requests for additional checks can be requested by creating a [Github issue](https://github.com/KhronosGroup/Vulkan-ValidationLayers/issues).
23
24## Synchronization Validation Functionality
25
26### Overview
27
28The pipelined and multi-threaded nature of Vulkan makes it particularly important for applications to correctly insert needed synchronization primitives, and for validation to diagnose unprotected memory access hazards. Synchronization reports the presence of access hazards including information to identify the Vulkan operations which are in conflict. The reported hazards are:
29
30
31<table>
32  <tr>
33   <td>RAW
34   </td>
35   <td>Read-after-write
36   </td>
37   <td>Occurs when a subsequent operation uses the result of a previous operation without waiting for the result to be completed.
38   </td>
39  </tr>
40  <tr>
41   <td>WAR
42   </td>
43   <td>Write-after-read
44   </td>
45   <td>Occurs when a subsequent operation overwrites a memory location read by a previous operation before that operation is complete (requires only execution dependency).
46   </td>
47  </tr>
48  <tr>
49   <td>WAW
50   </td>
51   <td>Write-after-write
52   </td>
53   <td>Occurs when a subsequent operation writes to the same set of memory locations (in whole or in part) being written by a previous operation.
54   </td>
55  </tr>
56  <tr>
57   <td>WRW
58   </td>
59   <td>Write-racing-write
60   </td>
61   <td>Occurs when unsynchronized subpasses/queues perform writes to the same set of memory locations.
62   </td>
63  </tr>
64  <tr>
65   <td>RRW
66   </td>
67   <td>Read-racing-write
68   </td>
69   <td>Occurs when unsynchronized subpasses/queues perform read and write operations on the same set of memory locations.
70   </td>
71  </tr>
72</table>
73
74
75
76### Current Feature set
77
78- Hazard detection for memory usage for commands within the *same* command buffer.
79- Synchronization operations .
80  - vkCmdPipelineBarrier.
81  - vkCmdSetEvent/vkCmdWaitEvents/vkCmdResetEvent.
82  - renderpass/subpass barriers.
83- The `VK_KHR_synchronization2` extension
84  - vkCmdPipelineBarrier2KHR
85  - vkCmdSetEvent2KHR/vkCmdWaitEvents2KHR/vkCmdResetEvent2KHR.
86- Image layout transition hazard and access tracking.
87- Load/Store/Resolve operations within Subpasses.
88
89### Known Limitations
90
91- Does not include implementation of multi-view renderpass support.
92- Host set event not supported.
93- ExecuteCommands and QueueSubmit hazards from are not tracked or reported.
94- Memory access checks not suppressed for VK_CULL_MODE_FRONT_AND_BACK.
95- Does not include component granularity access tracking.
96- Host synchronization not supported.
97
98## Enabling Synchronization Validation
99
100Synchronization Validation is disabled by default. To turn on Synchronization Validation, add the following to your layer settings file,
101`vk_layer_settings.txt`:
102
103```code
104khronos_validation.enables = VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT
105```
106
107To enable using environment variables, set the following variable:
108
109```code
110VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT
111```
112
113Mobile platforms (such as Android) do not support configuration of the validation layers with this configuration file.
114Programs running on these platforms must then use the programmatic interface.
115
116As Synchronization Validation is resource intensive, it is recommended to disable all other validation layer objects.
117
118### Enabling and Specifying Options with the Programmatic Interface
119
120The `VK_EXT_validation_features` extension can be used to enable Synchronization Validation at CreateInstance time.
121
122Here is sample code illustrating how to enable it:
123
124```code
125VkValidationFeatureEnableEXT enables[] = {VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT};
126VkValidationFeaturesEXT features = {};
127features.sType = VK_STRUCTURE_TYPE_VALIDATION_FEATURES_EXT;
128features.enabledValidationFeatureCount = 1;
129features.pEnabledValidationFeatures = enables;
130
131VkInstanceCreateInfo info = {};
132info.pNext = &features;
133```
134
135## Typical Synchronization Validation Usage
136
137### Debugging Synchronization Validation Issues
138
139To debug synchronization validation issues (all platforms):
140
141- Create a debug callback with `vkCreateDebugUtilsMessengerEXT` with the `VK_DEBUG_REPORT_ERROR_BIT_EXT` set.
142- Enable synchronization as noted above. On Linux and Windows this can be simplified by enabling Synchronization Validation using [Vulkan Configurator (vkconfig)](https://vulkan.lunarg.com/doc/sdk/latest/windows/vkconfig.html).
143- Set a breakpoint in the debug callback and run your application in the debugger.
144- The callback will be called when a `vkCmd`... command with a hazard is recorded.
145
146On Windows, Synchronization Validation can be run using just vkconfig and the debugger without defining a callback:
147
148*   In vkconfig.
149    *   Enable Synchronization Validation.
150    *   Select 'Debug Actions' 'Break' and 'Debug Output'.
151*   Debug application in Visual Studio.
152*   Hazard messages will appear in the debugger output window and the debugger will break (in the validation layer code)  when a `vkCmd`... command with a hazard is recorded.
153
154
155### Synchronization Validation Messages
156
157All synchronization error messages begin with SYNC-&lt;hazard name>.  The message body is constructed:
158
159
160```
161<cmd name>: Hazard <hazard name> <command specific details> Access info (<...>)
162```
163
164
165Command specific details typically include the specifics of the access within the current command. The Access info is common to all Synchronization Validation error messages.
166
167<table>
168  <tr>
169   <td><strong>Field</strong>
170   </td>
171   <td><strong>Description</strong>
172   </td>
173  </tr>
174  <tr>
175   <td><code>usage</code>
176   </td>
177   <td>The stage/access of the current command
178   </td>
179  </tr>
180  <tr>
181   <td><code>prior_usage</code>
182   </td>
183   <td>The stage/access of the previous (hazarded) use
184   </td>
185  </tr>
186  <tr>
187   <td><code>read_barrier</code>
188   </td>
189   <td>For read <code>usage</code>, the list of stages with execution barriers between <code>prior_usage</code> and <code>usage</code>
190   </td>
191  </tr>
192  <tr>
193   <td><code>write_barrier</code>
194   </td>
195   <td>For write <code>usage</code>, the list of stage/access (in <code>usage</code> format) with memory barriers between <code>prior_usage</code> and <code>usage</code>
196   </td>
197  </tr>
198  <tr>
199   <td><code>command</code>
200   </td>
201   <td>The command that performed <code>prior_usage</code>
202   </td>
203  </tr>
204  <tr>
205   <td><code>seq_no</code>
206   </td>
207   <td>The zero based index of <code>command</code> within the command buffer
208   </td>
209  </tr>
210  <tr>
211   <td><code>reset_no</code>
212   </td>
213   <td>the reset count of the command buffer <code>command</code> is recorded to
214   </td>
215  </tr>
216</table>
217
218
219### Frequently Found Issues
220
221*   Assuming Pipeline stages are logically extended with respect to memory access barriers.  Specifying the vertex shader stage in a barrier will **not** apply to all subsequent shader stages read/write access.
222*   Invalid stage/access pairs (specifying a pipeline stage for which a given access is not valid) that yield no barrier.
223*   Relying on implicit subpass dependencies with `VK_SUBPASS_EXTERNAL` when memory barriers are needed.
224*   Missing memory dependencies with Image Layout Transitions from pipeline barrier or renderpass Begin/Next/End operations.
225*   Missing stage/access scopes for load operations, noting that color and depth/stencil are done by different stage/access.
226
227
228### Debugging Tips
229
230*   Read and write barriers in the error message can help identify the synchronization operation (either subpass dependency or pipeline barrier) with insufficient or incorrect destination stage/access masks (second scope).
231*   `Access info read_barrier` and `write_barrier` values of 0, reflect the absence of any barrier, and can indicate an insufficient or incorrect source mask (first scope).
232*   Insert additional barriers with stage/access `VK_PIPELINE_STAGE_ALL_COMMANDS_BIT`, `VK_ACCESS_MEMORY_READ_BIT`|`VK_ACCESS_MEMORY_WRITE_BIT` for both` src*Mask` and `dst*Mask` fields to locate missing barriers. If the inserted barrier _resolves_ a hazard, the conflicting access _happens-before_ the inserted barrier. (Be sure to delete later.)
233
234
235## Synchronization blogs/articles
236
237Synchronization Examples[ https://github.com/KhronosGroup/Vulkan-Docs/wiki/Synchronization-Examples](https://github.com/KhronosGroup/Vulkan-Docs/wiki/Synchronization-Examples)
238
239Keeping your GPU fed without getting bitten [ https://www.youtube.com/watch?v=oF7vOTTaAh4](https://www.youtube.com/watch?v=oF7vOTTaAh4)
240
241Yet another blog explaining Vulkan synchronization[ http://themaister.net/blog/2019/08/14/yet-another-blog-explaining-vulkan-synchronization/](http://themaister.net/blog/2019/08/14/yet-another-blog-explaining-vulkan-synchronization/)
242
243A Guide to Vulkan Synchronization Validation https://www.khronos.org/news/permalink/blog-a-guide-to-vulkan-synchronization-validation
244
245