1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[appendix] 6[[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 asciidoctor anchors, intended for use by the validation layer 12to provide unique names for each validation condition, and a way to link 13from validation layer reports into the corresponding parts of the 14Specification. 15 16 17[[vuid-format]] 18== Format of VUID Tags 19 20For implicit valid usage statements, the tags are formatted like this: 21 22[source,asciidoc] 23---- 24[[VUID-blockname-paramname-category]] 25---- 26 27_blockname_ is the name of the function or structure for which a valid usage 28statement is being generated. 29 30_paramname_ is the name of the parameter being validated. 31In some cases, the statement does not validate a single parameter and this 32portion of the tag is absent. 33 34_category_ is the type of statement being generated. 35There are over one dozen types referring to distinct conditions such as 36valid objects, required bitmasks, required array lengths, constraints on 37parent objects, and so on. 38 39For explicit valid usage statements, the tags are formatted like this: 40 41[source,asciidoc] 42---- 43[[VUID-blockname-paramname-number]] 44---- 45 46_blockname_ is the name of the function or structure for which a valid usage 47statement is being generated. 48 49_paramname_ is the name of the parameter being validated. 50In some cases, the statement does not validate a single parameter and this 51portion of the tag is replaced by `-None-` 52 53_number_ is a unique five digit, zero-filled number used to disambiguate 54similar tag names. 55 56[NOTE] 57.Note 58==== 59The _blockname_, _paramname_, and _category_ portions of a VUID tag name 60must each be composed only of the alphanumeric characters A-Z, a-z, and 0-9, 61and the ':' character. 62In general only the alphabetic subset of these characters is used, but there 63are a few exceptions. 64==== 65 66 67[[vuid-creating]] 68== Creating VUID Tags 69 70For implicit valid usage statements generated automatically from `vk.xml`, 71VUID tags are created automatically by the generator scripts. 72 73For explicit valid usage statements, VUID tags are generated by passing 74appropriate options to the script `reflow.py`. 75 76Since these tags are of use only to the published validation layer, they are 77needed only in the published Specification sources and outputs. 78Therefore, authors of extensions, or other branches adding valid usage 79statements, are not themselves responsible for adding tags in their 80branches. 81The specification editors will take care of this as part of the process of 82publishing updates. 83For reference purposes, this process is described below: 84 85First, after integrating all new specification language into the internal 86gitlab default branch (currently `main`) containing the canonical 87Specification source, invoke the following command: 88 89[source,sh] 90---- 91python3 scripts/reflow.py -overwrite -noflow -tagvu chapters/*.adoc chapters/*/*.adoc 92---- 93 94This will add VUID tags to all statements in valid usage blocks which do not 95already have them. 96Some diagnostics will be reported, but these are do not in general require 97any action. 98 99After updating all files, the script will update the file 100`scripts/vuidCounts.py` containing reserved ranges of VUIDs for the default 101branch and certain other development branches. 102 103Commit the updated source files and `vuidCounts.py` together. 104The next time the script is run, VUID tags will be assigned numbers starting 105from the next free value in the range available to default branch. 106 107In-development Vulkan extensions are kept in their own branches, with the 108branch name the same as the name of the extension being developed. 109VUID tags may be assigned in these branches in the same fashion as in 110default branch. 111To enable this, each development branch must be assigned its own independent 112VUID range in the default branch copy of `vuidCounts.py`, to prevent 113collisions. 114In the event that default branch or any development branch exhausts the 115available VUID range, `reflow.py` will report this and stop assigning VUIDs. 116At that point, a new range must be assigned to the branch in the default 117branch copy of `vuidCounts.py`, as well as in the per-branch copy. 118 119 120== Updating VUID Tags When Valid Usage Statements Change 121 122Valid usage statements have corresponding tests in the Vulkan Validation 123Layer. 124The tests must be changed in response to semantic changes in the VU 125statements, whether for bug-fixing, adding extension interactions, or 126otherwise. 127The rule used when updating explicit VU statements is that the merge request 128or pull request responsible for making the change must remove the existing 129VUID tag, so that a new one can be assigned, _except_ in the following 130cases: 131 132 * The changes are non-semantic, such as using consistent phrasing or 133 markup. 134 * The changes consist of removing or changing extension suffixes when 135 promoting an extension to `EXT`, `KHR`, or core status. 136 * The valid usage statement has not yet been implemented in the validation 137 layers. 138 139[NOTE] 140.Note 141==== 142This section may need further modification in response to guidelines agreed 143to by the Vulkan Working Group. 144==== 145