// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[appendix]
[[appendix-vuid]]
= Valid Usage ID Tags

Valid usage statements in the published Vulkan Specification must all be
given _Valid Usage ID_ or _VUID_ tags.
These tags are asciidoc anchors, intended for use by the validation layer to
provide unique names for each validation condition, and a way to link from
validation layer reports into the corresponding parts of the Specification.


== Format of VUID Tags

For implicit valid usage statements, the tags are formatted like this:

[source,asciidoc]
----
[[VUID-blockname-paramname-category]]
----

_blockname_ is the name of the function or structure for which a valid usage
statement is being generated.

_paramname_ is the name of the parameter being validated.
In some cases, the statement does not validate a single parameter and this
portion of the tag is absent.

_category_ is the type of statement being generated.
There are over one dozen types referring to distinct conditions such as
valid objects, required bitmasks, required array lengths, constraints on
parent objects, and so on.

For explicit valid usage statements, the tags are formatted like this:

[source,asciidoc]
----
[[VUID-blockname-paramname-number]]
----

_blockname_ is the name of the function or structure for which a valid usage
statement is being generated.

_paramname_ is the name of the parameter being validated.
In some cases, the statement does not validate a single parameter and this
portion of the tag is replaced by `-None-`

_number_ is a unique five digit, zero-filled number used to disambiguate
similar tag names.


== Creating VUID Tags

For implicit valid usage statements generated automatically from `vk.xml`,
VUID tags are created automatically by the generator scripts.

For explicit valid usage statements, VUID tags are generated by passing
appropriate options to the script `doc/specs/vulkan/reflow.py`.

Since these tags are of use only to the published validation layer, they are
needed only in the published Specification sources and outputs.
Therefore, authors of extensions, or other branches adding valid usage
statements, are not themselves responsible for adding tags in their
branches.
The specification editors will take care of this as part of the process of
publishing updates.
For reference purposes, this process is described below:

First, after integrating all new specification language into the internal
gitlab branch which contains the canonical Specification source, invoke the
following command in `doc/specs/vulkan`:

[source,sh]
----
python3 reflow.py -overwrite -noflow -tagvu chapters/*.txt chapters/*/*.txt
----

This will add VUID tags to all statements in valid usage blocks which don't
already have them.
Some diagnostics will be reported, but these are do not in general require
any action.
After updating all files, the script will print out a final line like:

[source,sh]
----
WARN:  You must now edit the value of reflow.py:startVUID to 1376 so that future runs will not overwrite existing VUID tags
----

Second, after verifying the updates are correct using e.g. `git diff`, edit
`reflow.py` and edit the definition of the variable startVUID as directed:

[source,python]
----
# The value to start tagging VU statements at, unless overridden by -nextvu
startVUID = 1376
----

Commit the updated source files and `reflow.py` together.
The next time the script is run, VUID tags will be assigned numbers starting
from the current startVUID value.


== Updating VUID Tags When Valid Usage Statements Change

Valid usage statements have corresponding tests in the Vulkan Validation
Layer.
The tests must be changed in response to semantic changes in the VU
statements, whether for bug-fixing, adding extension interactions, or
otherwise.
The rule used when updating explicit VU statements is that the merge request
or pull request responsible for making the change must remove the existing
VUID tag, so that a new one can be assigned, _except_ in the following
cases:

  * The changes are non-semantic, such as using consistent phrasing or
    markup.
  * The changes consist of changing `KHX` to `KHR` suffixes when promoting a
    Khronos-defined extension.

[NOTE]
.Note
====
This section may need further modification in response to guidelines agreed
to by the Vulkan Working Group.
====