Add support for codified VUs

The following is implemented in this change:

- Codified VU parsing
- Codified VU reformatting in source (reflow.py)
- Codified VU formatting for build
- Codified VU type checking
- Codified VU customization for build with/without extensions/versions
  * Removes the need for ifdef
- Unit tests

There is no mention of codified VUs in the spec text however at this
point.  That will be added as VUs are converted.

Makefile

@@ -133,6 +133,7 @@ VERBOSE =
 # EXTRAATTRIBS sets additional attributes, if passed to make
 # ADOCMISCOPTS miscellaneous options controlling error behavior, etc.
 # ADOCEXTS asciidoctor extensions to load
+# ADOCPROCOPTS options for passes that process the spec and produce side effects (such as validusage)
 # ADOCOPTS options for asciidoc->HTML5 output
 
 NOTEOPTS = -a editing-notes -a implementation-guide
@@ -204,10 +205,12 @@ ADOCMISCOPTS = --failure-level ERROR
 # Look in $(GENERATED) for explicitly required non-extension Ruby, such
 # as apimap.rb
 ADOCEXTS = -I$(GENERATED) \
+ -I$(CONFIGS)/helpers/ \
  -r $(CONFIGS)/spec-macros.rb \
  -r $(CONFIGS)/open_listing_block.rb \
  -r $(CONFIGS)/ifdef-mismatch.rb
-ADOCOPTS = -d book $(ADOCMISCOPTS) $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
+ADOCPROCOPTS = -d book $(ADOCMISCOPTS) $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS)
+ADOCOPTS = $(ADOCPROCOPTS) -r $(CONFIGS)/vu-formatter.rb
 
 # HTML target-specific Asciidoctor extensions and options
 ADOCHTMLEXTS = -r $(CONFIGS)/katex_replace.rb \
@@ -363,11 +366,12 @@ $(PDFDIR)/vkspec.pdf: $(SPECSRC) $(COMMONDOCS)
  $(QUIET)$(OPTIMIZEPDF) $@ $@.out.pdf && mv $@.out.pdf $@
  $(QUIET)$(RMRF) $(PDFMATHDIR)
 
-validusage: $(VUDIR)/validusage.json $(SPECSRC) $(COMMONDOCS)
+.PHONY: validusage
+validusage: $(VUDIR)/validusage.json
 
-$(VUDIR)/validusage.json: $(SPECSRC) $(COMMONDOCS)
+$(VUDIR)/validusage.json: $(SPECSRC) $(COMMONDOCS) $(CONFIGS)/vu-to-json/extension.rb $(CONFIGS)/helpers/vu_helpers.rb
  $(QUIET)$(MKDIR) $(VUDIR)
- $(QUIET)$(ASCIIDOC) $(ADOCOPTS) $(ADOCVUOPTS) --trace \
+ $(QUIET)$(ASCIIDOC) $(ADOCPROCOPTS) $(ADOCVUOPTS) --trace \
  -a json_output=$@ -o $@ $(SPECSRC)
 
 # Vulkan Documentation and Extensions, a.k.a. "Style Guide" documentation

build_tests/chapters/commonvalidity/dolor.adoc

@@ -14,13 +14,12 @@
  pname:{bufferrowlength} must: be `0`, or greater than or equal to the
  pname:width member of pname:imageExtent
  * [[VUID-{refpage}-{bufferimageheight}-99102]]
- pname:{bufferimageheight} must: be `0`, or greater than or equal to the
- pname:height member of pname:imageExtent
- * [[VUID-{refpage}-aspectMask-99103]]
- The pname:aspectMask member of pname:imageSubresource must: only have a
+ # Start with comment
+ require(macro(bufferimageheight) == 0 or macro(bufferimageheight) >= imageExtent.height)
+ * The pname:aspectMask member of pname:imageSubresource must: only have a
  single bit set
- * [[VUID-{refpage}-imageExtent-96659]]
- pname:imageExtent.width must: not be 0
+ * # Start with comment, no VUID
+ require(imageExtent.width != 0)
  * [[VUID-{refpage}-imageExtent-96660]]
  pname:imageExtent.height must: not be 0
  * [[VUID-{refpage}-imageExtent-96661]]

build_tests/chapters/commonvalidity/ipsum.adoc

@@ -21,23 +21,18 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
  _disjoint_ plane must: be bound completely and contiguously to a single
  sname:VkDeviceMemory object
 endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
- * [[VUID-{refpage}-{imagesubresource}-97967]]
- The pname:{imagesubresource}.mipLevel member of each element of
- pname:pRegions must: be less than the pname:mipLevels specified in
- slink:VkImageCreateInfo when pname:{imageparam} was created
+ * for region in pRegions:
+ require(region.macro(imagesubresource).mipLevel < macro(imageparam).create_info().mipLevels)
  * [[VUID-{refpage}-{imagesubresource}-97968]]
- The [eq]#pname:{imagesubresource}.baseArrayLayer {plus}
- pname:{imageSubresource}.layerCount# of each element of pname:pRegions
-ifdef::VK_KHR_maintenance5[]
- , if pname:{imageSubresource}.layerCount is not
- ename:VK_REMAINING_ARRAY_LAYERS and <<features-maintenance5,
- pname:maintenance5>> is not enabled,
-endif::VK_KHR_maintenance5[]
- must: be less than or equal to the pname:arrayLayers specified in
- slink:VkImageCreateInfo when pname:{imageparam} was created
+ # Comment line
+ for region in pRegions:
+ layerCount = region.macro(imagesubresource).layerCount
+ if not is_feature_enabled(maintenance5) or layerCount != VK_REMAINING_ARRAY_LAYERS:
+ # Other comment line
+ require(layerCount < macro(imageparam).create_info().arrayLayers)
 ifdef::VK_EXT_fragment_density_map[]
  * [[VUID-{refpage}-{imageparam}-97969]]
- pname:{imageparam} must: not have been created with pname:flags
- containing ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT
+ imageFlags = macro(imageparam).create_info().flags
+ require(not imageFlags.has_bit(VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT))
 endif::VK_EXT_fragment_density_map[]
 // Common Valid Usage

build_tests/chapters/ipsum.adoc

@@ -77,6 +77,9 @@ include::{chapters}/commonvalidity/ipsum.adoc[]
  pname:dstImageLayout must: Lorem ipsum dolor sit amet, pname:dstImage
  consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
  pname:pRegions et dolore magna aliqua
+ * [[VUID-VkCopyMemoryToImageInfoEXT-bogus4-99994]]
+ for region in pRegions:
+ require(region.macro(bufferrowlength) > 0 and macro(imageparam).create_info().mipLevels == 4)
 ****
 
 include::{generated}/validity/structs/VkCopyMemoryToImageInfoEXT.adoc[]

build_tests/chapters/lorem.adoc

@@ -94,6 +94,16 @@ endif::VK_KHR_copy_commands2[]
 
 .Valid Usage
 ****
+ * require(dstImageLayout != VK_IMAGE_LAYOUT_PREINITIALIZED)
+ * [[VUID-VkCopyBufferToImageInfo2-bogus1-99991]]
+ require(regionCount == 1)
+ * if regionCount == 1:
+ for region in pRegions:
+ require(region.macro(bufferrowlength) < region.macro(bufferimageheight))
+ * [[VUID-VkCopyBufferToImageInfo2-bogus2-99992]]
+ if srcBuffer.valid() and dstImage.valid():
+ for region in pRegions:
+ require(region.imageOffset.x * region.imageExtent.width == 0)
  * [[VUID-VkCopyBufferToImageInfo2-pRegions-94565]]
  Id velit ut tortor pretium viverra suspendisse potenti pname:pRegions
 ifdef::VK_QCOM_rotated_copy_commands[]
@@ -110,7 +120,6 @@ ifdef::VK_QCOM_rotated_copy_commands[]
  pname:dstImage
 endif::VK_QCOM_rotated_copy_commands[]
 include::{chapters}/commonvalidity/ipsum.adoc[]
-include::{chapters}/commonvalidity/dolor.adoc[]
  * [[VUID-VkCopyBufferToImageInfo2-pRegions-96223]]
  Id leo in vitae turpis massa sed elementum
  pname:imageOffset.x and [eq]#(pname:imageExtent.width {plus}
@@ -154,6 +163,24 @@ orci a scelerisque purus semper eget duis.
 .Valid Usage
 ****
 include::{chapters}/commonvalidity/dolor.adoc[]
+ * if bufferOffset > 0:
+ require(bufferRowLength < bufferImageHeight)
+ require(imageSubresource.aspectMask.has_bit(VK_IMAGE_ASPECT_COLOR_BIT))
+ * [[VUID-VkBufferImageCopy2-bogus3-99993]]
+ if imageOffset.x == imageOffset.y and imageOffset.y == imageOffset.z:
+ if bufferImageHeight < 2:
+ require(bufferRowLength > 3 or bufferRowLength < 1)
+ require(imageSubresource.aspectMask.has_bit(VK_IMAGE_ASPECT_DEPTH_BIT))
+ * # Comment on first line
+ if bufferOffset > 0:
+ require(bufferRowLength < bufferImageHeight)
+ require(imageSubresource.aspectMask.has_bit(VK_IMAGE_ASPECT_COLOR_BIT))
+ * [[VUID-VkBufferImageCopy2-bogus5-99995]]
+ # Comment on first line with VUID
+ if imageOffset.x == imageOffset.y and imageOffset.y == imageOffset.z:
+ if bufferImageHeight < 2:
+ require(bufferRowLength > 3 or bufferRowLength < 1)
+ require(imageSubresource.aspectMask.has_bit(VK_IMAGE_ASPECT_DEPTH_BIT))
 ****
 
 include::{generated}/validity/structs/VkBufferImageCopy2.adoc[]