1// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[appendix] 6[[appendix-vuid]] 7= Valid Usage ID Tags 8 9Valid usage statements in the published Vulkan Specification must all be 10given _Valid Usage ID_ or _VUID_ tags. 11These tags are asciidoc anchors, intended for use by the validation layer to 12provide unique names for each validation condition, and a way to link from 13validation layer reports into the corresponding parts of the Specification. 14 15 16== Format of VUID Tags 17 18For implicit valid usage statements, the tags are formatted like this: 19 20[source,asciidoc] 21---- 22[[VUID-blockname-paramname-category]] 23---- 24 25_blockname_ is the name of the function or structure for which a valid usage 26statement is being generated. 27 28_paramname_ is the name of the parameter being validated. 29In some cases, the statement does not validate a single parameter and this 30portion of the tag is absent. 31 32_category_ is the type of statement being generated. 33There are over one dozen types referring to distinct conditions such as 34valid objects, required bitmasks, required array lengths, constraints on 35parent objects, and so on. 36 37For explicit valid usage statements, the tags are formatted like this: 38 39[source,asciidoc] 40---- 41[[VUID-blockname-paramname-number]] 42---- 43 44_blockname_ is the name of the function or structure for which a valid usage 45statement is being generated. 46 47_paramname_ is the name of the parameter being validated. 48In some cases, the statement does not validate a single parameter and this 49portion of the tag is replaced by `-None-` 50 51_number_ is a unique five digit, zero-filled number used to disambiguate 52similar tag names. 53 54 55== Creating VUID Tags 56 57For implicit valid usage statements generated automatically from `vk.xml`, 58VUID tags are created automatically by the generator scripts. 59 60For explicit valid usage statements, VUID tags are generated by passing 61appropriate options to the script `reflow.py`. 62 63Since these tags are of use only to the published validation layer, they are 64needed only in the published Specification sources and outputs. 65Therefore, authors of extensions, or other branches adding valid usage 66statements, are not themselves responsible for adding tags in their 67branches. 68The specification editors will take care of this as part of the process of 69publishing updates. 70For reference purposes, this process is described below: 71 72First, after integrating all new specification language into the internal 73gitlab branch which contains the canonical Specification source, invoke the 74following command: 75 76[source,sh] 77---- 78python3 reflow.py -overwrite -noflow -tagvu chapters/*.txt chapters/*/*.txt 79---- 80 81This will add VUID tags to all statements in valid usage blocks which don't 82already have them. 83Some diagnostics will be reported, but these are do not in general require 84any action. 85After updating all files, the script will print out a final line like: 86 87[source,sh] 88---- 89WARN: You must now edit the value of reflow.py:startVUID to 1376 so that future runs will not overwrite existing VUID tags 90---- 91 92Second, after verifying the updates are correct using e.g. `git diff`, edit 93`reflow.py` and edit the definition of the variable startVUID as directed: 94 95[source,python] 96---- 97# The value to start tagging VU statements at, unless overridden by -nextvu 98startVUID = 1376 99---- 100 101Commit the updated source files and `reflow.py` together. 102The next time the script is run, VUID tags will be assigned numbers starting 103from the current startVUID value. 104 105 106== Updating VUID Tags When Valid Usage Statements Change 107 108Valid usage statements have corresponding tests in the Vulkan Validation 109Layer. 110The tests must be changed in response to semantic changes in the VU 111statements, whether for bug-fixing, adding extension interactions, or 112otherwise. 113The rule used when updating explicit VU statements is that the merge request 114or pull request responsible for making the change must remove the existing 115VUID tag, so that a new one can be assigned, _except_ in the following 116cases: 117 118 * The changes are non-semantic, such as using consistent phrasing or 119 markup. 120 * The changes consist of changing `KHX` to `KHR` suffixes when promoting a 121 Khronos-defined extension. 122 123[NOTE] 124.Note 125==== 126This section may need further modification in response to guidelines agreed 127to by the Vulkan Working Group. 128==== 129