// Copyright 2015-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-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 asciidoctor 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.


[[appendix-vuid-format]]
== 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.

[NOTE]
.Note
====
The _blockname_, _paramname_, and _category_ portions of a VUID tag name
must each be composed only of the alphanumeric characters A-Z, a-z, and 0-9,
and the ':' character.
In general only the alphabetic subset of these characters is used, but there
are a few exceptions.
====


[[appendix-vuid-creating]]
== 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 `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 default branch (currently `main`) which contains the canonical
Specification source, invoke the following command:

[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 do not
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 update the file
`scripts/vuidCounts.py`, which contains reserved ranges of VUIDs for the
default branch and certain other development branches.

Commit the updated source files and `vuidCounts.py` together.
The next time the script is run, VUID tags will be assigned numbers starting
from the next free value in the range available to default branch.

In-development Vulkan extensions are kept in their own branches, with the
branch name the same as the name of the extension being developed.
VUID tags may be assigned in these branches in the same fashion as in
default branch.
To enable this, each development branch must be assigned its own independent
VUID range in the default branch copy of `vuidCounts.py`, to prevent
collisions.
In the event that default branch or any development branch exhausts the
available VUID range, `reflow.py` will report this and stop assigning VUIDs.
At that point, a new range must be assigned to the branch in the default
branch copy of `vuidCounts.py`, as well as in the per-branch copy.


== 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 removing or changing extension suffixes when
    promoting an extension to `EXT`, `KHR`, or core status.
  * The valid usage statement has not yet been implemented in the validation
    layers.

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