mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-25 12:35:11 +00:00
521e98405f
* Update release number to 120.
Github Issues:
* Add slink:VkAccelerationStructureTypeNV explicitly to extension XML for
`<<VK_NV_ray_tracing>>` (public issue 848).
* Add missing valid usage statements for feature flags in
slink:VkCommandBufferInheritanceInfo (public pull request 1017).
Internal Issues:
* Clarify behavior of non-premultiplied destination colors for
`<<VK_EXT_blend_operation_advanced>>` prior to the definition of
slink:VkBlendOverlapEXT (internal issue 1766).
* Fix the confusing phrasing "`no other queue must: be (doing something)`"
for flink:vkQueuePresentKHR, flink:vkQueueSubmit, and
flink:vkQueueBindSparse (internal issue 1774).
* Add `<<VK_EXT_validation_features>>` flag to enable best practices
checks, which will soon be available in the validation layer (internal
issue 1779).
* Specify allowed characters for VUID tag name components in the style
guide (internal issue 1788).
* Update links to SPIR-V extension specifications, and parameterize their
markup in case the URLs change in the future (internal issue 1797).
* Fix an off-by-one error in the valid usage statement for
slink:VkPipelineExecutableInfoKHR (internal merge request 3303).
* Clean up markup indentation not matching the style guide (internal merge
request 3314).
* Minor script updates to allow refpage aliases, generate a dynamic TOC
for refpages, generate Apache rewrite rules for aliases, open external
links from refpages in a new window, and synchronize with the OpenCL
scripts. This will shortly enable a paned navigation setup for refpages,
similar to the OpenCL 2.2 refpages (internal merge request 3322).
* Script updates to add tests to the checker, refactor and reformat code,
generate better text for some valid usage statements, use more Pythonic
idioms, and synchronize with the OpenXR scripts (internal merge request
3239).
* Script updates and minor fixes in spec language to not raise checker
errors for refpage markup of pages not existing in the API, such as
VKAPI_NO_STDINT_H. Remove corresponding suppression of some
check_spec_links.py tests from .gitlab-ci.yml and 'allchecks' target
(internal merge request 3315).
140 lines
4.6 KiB
Plaintext
140 lines
4.6 KiB
Plaintext
// Copyright (c) 2015-2019 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.
|
|
|
|
|
|
[[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.
|
|
====
|
|
|
|
|
|
== 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 branch 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 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.
|
|
====
|