mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-10 05:24:38 +00:00
56e0289318
* Update release number to 97.
Public Issues:
* Add a special case to the <<renderpass-compatibility, Render Pass
Compatibility>> rules allowing single-subpass renderpasses to be
compatible even if they have different resolve attachment references
(public issue 835).
* Fix the miss shader binding table record address rule in the
<<shader-binding-table-indexing-rules, Miss Shaders>> section to index
by code:missIndex, not code:sbtOffset (public issue 875).
Internal Issues:
* Add a missing anchor to the elink:VkSamplerCreateFlagBits language
(internal issue 1483).
* Add missing implicit valid usage include for slink:VkHdrMetadataEXT and
corresponding `noautovalidity` attributes in `vk.xml` for the
externally-defined metadata properties (internal issue 1514).
* Remove restrictions on the `mask` parameter of SPIR-V's
code:OpGroupNonUniformXor in the <<spirvenv-module-validation,
Validation Rules within a Module>> appendix (internal merge request
2971).
* Restore `noautovalidity` attribute for
slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:pViewportWScalings
in `vk.xml` (internal merge request 2975).
* Update copyright dates on Khronos-copyrighted files to 2019 (internal
merge request 2980).
New Extensions:
* `VK_KHR_depth_stencil_resolve`
* `VK_EXT_buffer_device_address`
* `VK_EXT_memory_budget`
* `VK_EXT_memory_priority`
* `VK_EXT_validation_features`
129 lines
4.3 KiB
Plaintext
129 lines
4.3 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.
|
|
|
|
|
|
== 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 `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.
|
|
====
|