codegen/vulkan/vulkan-docs-next/style/vuid.adoc - platform/hardware/google/gfxstream - Git at Google

 // Copyright 2015-2023 The Khronos Group Inc.
 //
 // SPDX-License-Identifier: CC-BY-4.0

 [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.


 [[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.
 ====


 [[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`) containing the canonical
 Specification source, invoke the following command:

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

 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` containing 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.
 ====
	// Copyright 2015-2023 The Khronos Group Inc.
	//
	// SPDX-License-Identifier: CC-BY-4.0

	[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.


	[[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.
	====


	[[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`) containing the canonical
	Specification source, invoke the following command:

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

	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` containing 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.
	====