layers: Automated checking of validation layer documentation
Addition of vk_layer_documentation_generate.py script to check hand-written vk_validation_layer_details.md doc against the layer source code.
Currently this will verify documented validation checks against checks declared in source headers and verify that API calls in document are actual API calls.
This includes many documentation and layer updates to get everything in synch and allow the script to pass.
diff --git a/layers/draw_state.h b/layers/draw_state.h
index f326c20..a3fc2eb 100644
--- a/layers/draw_state.h
+++ b/layers/draw_state.h
@@ -41,7 +41,7 @@
DRAWSTATE_INVALID_CMD_BUFFER, // Invalid CmdBuffer referenced
DRAWSTATE_VTX_INDEX_OUT_OF_BOUNDS, // binding in vkCmdBindVertexData() too large for PSO's pVertexBindingDescriptions array
DRAWSTATE_INVALID_DYNAMIC_STATE_OBJECT, // Invalid dyn state object
- DRAWSTATE_MISSING_DOT_PROGRAM, // No "dot" program in order to generate png image
+ //DRAWSTATE_MISSING_DOT_PROGRAM, // No "dot" program in order to generate png image
DRAWSTATE_OUT_OF_MEMORY, // malloc failed
DRAWSTATE_DESCRIPTOR_TYPE_MISMATCH, // Type in layout vs. update are not the same
DRAWSTATE_DESCRIPTOR_UPDATE_OUT_OF_BOUNDS, // Descriptors set for update out of bounds for corresponding layout section
diff --git a/layers/mem_tracker.h b/layers/mem_tracker.h
index 31e728a..c572215 100644
--- a/layers/mem_tracker.h
+++ b/layers/mem_tracker.h
@@ -41,7 +41,7 @@
MEMTRACK_MEM_OBJ_CLEAR_EMPTY_BINDINGS, // Clearing bindings on mem obj that doesn't have any bindings
MEMTRACK_MISSING_MEM_BINDINGS, // Trying to retrieve mem bindings, but none found (may be internal error)
MEMTRACK_INVALID_OBJECT, // Attempting to reference generic VK Object that is invalid
- MEMTRACK_DESTROY_OBJECT_ERROR, // Destroying an object that has a memory reference
+ //MEMTRACK_DESTROY_OBJECT_ERROR, // Destroying an object that has a memory reference TODO : Is this still an error? We don't flag it anywhere
MEMTRACK_MEMORY_BINDING_ERROR, // Error during one of many calls that bind memory to object or CB
MEMTRACK_MEMORY_LEAK, // Failure to call vkFreeMemory on Mem Obj prior to DestroyDevice
MEMTRACK_INVALID_STATE, // Memory not in the correct state
diff --git a/layers/object_track.h b/layers/object_track.h
index 9228705..44c8c40 100644
--- a/layers/object_track.h
+++ b/layers/object_track.h
@@ -33,7 +33,6 @@
OBJTRACK_UNKNOWN_OBJECT, // Updating uses of object that's not in global object list
OBJTRACK_INTERNAL_ERROR, // Bug with data tracking within the layer
OBJTRACK_DESTROY_OBJECT_FAILED, // Couldn't find object to be destroyed
- OBJTRACK_OBJECT_TYPE_MISMATCH, // Object did not match corresponding Object Type
OBJTRACK_OBJECT_LEAK, // OBJECT was not correctly freed/destroyed
OBJTRACK_OBJCOUNT_MAX_EXCEEDED, // Request for Object data in excess of max obj count
OBJTRACK_INVALID_FENCE, // Requested status of unsubmitted fence object
diff --git a/layers/vk_validation_layer_details.md b/layers/vk_validation_layer_details.md
index f2b8025..fe3c50c 100644
--- a/layers/vk_validation_layer_details.md
+++ b/layers/vk_validation_layer_details.md
@@ -13,10 +13,10 @@
| Check | Overview | ENUM DRAWSTATE_* | Relevant API | Testname | Notes/TODO |
| ----- | -------- | ---------------- | ------------ | -------- | ---------- |
| Valid Pipeline Layouts | Validates that pipeline layout from bound descriptor set matches the current pipeline layout | PIPELINE_LAYOUT_MISMATCH | vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TBD | None |
-| Validate DbgMarker exensions | Validates that DbgMarker extensions have been enabled before use | DRAWSTATE_INVALID_EXTENSION | vkCmdDbgMarkerBegin vkCmdDbgMarkerEnd | TBD | None |
+| Validate DbgMarker exensions | Validates that DbgMarker extensions have been enabled before use | INVALID_EXTENSION | vkCmdDbgMarkerBegin vkCmdDbgMarkerEnd | TBD | None |
| Valid BeginCommandBuffer level-related parameters | Primary command buffers must specify VK_NULL_HANDLE for RenderPass or Framebuffer parameters, while secondary command buffers must provide non-null parameters | BEGIN_CB_INVALID_STATE | vkBeginCommandBuffer | PrimaryCmdBufferFramebufferAndRenderpass SecondaryCmdBufferFramebufferAndRenderpass | None |
| PSO Bound | Verify that a properly created and valid pipeline object is bound to the CmdBuffer specified in these calls | NO_PIPELINE_BOUND | vkCmdBindDescriptorSets vkCmdBindVertexBuffers | PipelineNotBound | This check is currently more related to DrawState data structures and less about verifying that PSO is bound at all appropriate points in API. For API purposes, need to make sure this is checked at Draw time and any other relevant calls. |
-| Valid DescriptorPool | Verifies that the descriptor set pool object was properly created and is valid | INVALID_POOL | vkResetDescriptorPool, vkAllocDescriptorSets | None | This is just an internal layer data structure check. ParamChecker or ObjectTracker should really catch bad DSPool |
+| Valid DescriptorPool | Verifies that the descriptor set pool object was properly created and is valid | INVALID_POOL | vkResetDescriptorPool vkAllocDescriptorSets | None | This is just an internal layer data structure check. ParamChecker or ObjectTracker should really catch bad DSPool |
| Valid DescriptorSet | Validate that descriptor set was properly created and is currently valid | INVALID_SET | vkCmdBindDescriptorSets | None | Is this needed other places (like Update/Clear descriptors) |
| Valid DescriptorSetLayout | Flag DescriptorSetLayout object that was not properly created | INVALID_LAYOUT | vkAllocDescriptorSets | None | Anywhere else to check this? |
| Valid Pipeline | Flag VkPipeline object that was not properly created | INVALID_PIPELINE | vkCmdBindPipeline | InvalidPipeline | NA |
@@ -26,23 +26,28 @@
| Vtx Buffer Bounds | Check if VBO index too large for PSO Vtx binding count, and that at least one vertex buffer is attached to pipeline object | VTX_INDEX_OUT_OF_BOUNDS | vkCmdBindDescriptorSets vkCmdBindVertexBuffers | VtxBufferBadIndex | NA |
| Cmd Buffer End | Verifies that EndCommandBuffer was called for this cmdBuffer at QueueSubmit time | NO_END_CMD_BUFFER | vkQueueSubmit | NoEndCmdBuffer | NA |
| Cmd Buffer Begin | Check that BeginCommandBuffer was called for this command buffer when binding commands or calling end | NO_BEGIN_CMD_BUFFER | vkEndCommandBuffer vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicBlendState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect vkCmdDispatch vkCmdDispatchIndirect vkCmdCopyBuffer vkCmdCopyImage vkCmdBlitImage vkCmdCopyBufferToImage vkCmdCopyImageToBuffer vkCmdUpdateBuffer vkCmdFillBuffer vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdResolveImage vkCmdSetEvent vkCmdResetEvent vkCmdWaitEvents vkCmdPipelineBarrier vkCmdBeginQuery vkCmdEndQuery vkCmdResetQueryPool vkCmdWriteTimestamp | NoBeginCmdBuffer | NA |
-| Cmd Buffer Submit Count | Verify that ONE_TIME submit cmdbuffer is not submitted multiple times | DRAWSTATE_CMD_BUFFER_SINGLE_SUBMIT_VIOLATION | vkBeginCommandBuffer, vkQueueSubmit | CmdBufferTwoSubmits | NA |
-| DS Pool State at Submit | Flag if QueueSubmit includes a DS Pool under active update (begin called w/o end) | BINDING_DS_NO_END_UPDATE | vkQueueSubmit | DSBoundWithoutEnd | NA |
+| Cmd Buffer Submit Count | Verify that ONE_TIME submit cmdbuffer is not submitted multiple times | CMD_BUFFER_SINGLE_SUBMIT_VIOLATION | vkBeginCommandBuffer, vkQueueSubmit | CmdBufferTwoSubmits | NA |
| Descriptor Type | Verify Descriptor type in bound descriptor set layout matches descriptor type specified in update | DESCRIPTOR_TYPE_MISMATCH | vkUpdateDescriptorSets | DSTypeMismatch | With various DS API updates, need to revisit this code |
| DS Update Size | DS update out of bounds for given layout section | DESCRIPTOR_UPDATE_OUT_OF_BOUNDS | vkUpdateDescriptorSets | DSUpdateOutOfBounds | NA |
| DS Update Index | DS update binding too large for layout count | INVALID_UPDATE_INDEX | vkUpdateDescriptorSets | InvalidDSUpdateIndex | NA |
| DS Update Type | Verifies that structs in DS Update tree are properly created, currenly valid, and of the right type | INVALID_UPDATE_STRUCT | vkUpdateDescriptorSets | InvalidDSUpdateStruct | NA |
| MSAA Sample Count | Verifies that Pipeline, RenderPass, and Subpass sample counts are consistent | NUM_SAMPLES_MISMATCH | vkCmdBindPipeline vkCmdBeginRenderPass vkCmdNextSubpass | NumSamplesMismatch | NA |
-| Dynamic Viewport State Binding | Verify that viewport dynamic states bound to Cmd Buffer at Draw time | VIEWPORT_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | RasterStateNotBound, ViewportStateNotBound, ColorBlendStateNotBound, DepthStencilStateNotBound | Write targeted test |
-| Dynamic State Binding | Verify that raster dynamic states bound to Cmd Buffer at Draw time | RASTER_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | RasterStateNotBound, ViewportStateNotBound, ColorBlendStateNotBound, DepthStencilStateNotBound | Write targeted test |
-| Dynamic State Binding | Verify that if color enabled, the respective dynamic state is also bound | COLOR_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | RasterStateNotBound, ViewportStateNotBound, ColorBlendStateNotBound, DepthStencilStateNotBound | Write targeted test |
-| Dynamic State Binding | Verify that depth enabled, the respective dynamic state is also bound | DEPTH_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | RasterStateNotBound, ViewportStateNotBound, ColorBlendStateNotBound, DepthStencilStateNotBound | Write targeted test |
+| Dynamic Viewport State Binding | Verify that viewport dynamic state bound to Cmd Buffer at Draw time | VIEWPORT_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | ViewportStateNotBound | NA |
+| Dynamic Line Width State Binding | Verify that line width dynamic state bound to Cmd Buffer at when required (TODO : Verify when this is) | LINE_WIDTH_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TODO | Verify this check and Write targeted test |
+| Dynamic Depth Bias State Binding | Verify that depth bias dynamic state bound when depth enabled | DEPTH_BIAS_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TODO | Verify this check and Write targeted test |
+| Dynamic Blend State Binding | Verify that blend dynamic state bound when color blend enabled | BLEND_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TODO | Verify this check and Write targeted test |
+| Dynamic Depth Bounds State Binding | Verify that depth bounds dynamic state bound when depth enabled | DEPTH_BOUNDS_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TODO | Verify this check and Write targeted test |
+| Dynamic Stencil State Binding | Verify that stencil dynamic state bound when depth enabled | STENCIL_NOT_BOUND |vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | TODO | Verify this check and Write targeted test |
| RenderPass misuse | Tests for the following: that BeginRenderPass, ResolveImage, ClearColorImage, ClearDepthStencilImage are not called during an active Renderpass, and that binding compute descriptior sets or pipelines does not take place during an active | INVALID_RENDERPASS_CMD | vkCmdBindPipeline vkCmdBindDescriptorSets vkCmdBlitImage vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdResolveImage vkCmdBeginRenderPass | RenderPassWithinRenderPass | NA |
-| Correct use of RenderPass | Validates that rendering commands are issued inside an active RenderPass | NO_ACTIVE_RENDERPASS | vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicBlendState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdNextSubpass vkCmdEndRenderPass vkCmdExecuteCommands vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | BindPipelineNoRenderPass, VtxBufferNoRenderPass | NA |
-| Valid RenderPass | Flag error if attempt made to Begin/End/Continue a NULL or otherwise invalid RenderPass object | INVALID_RENDERPASS | vkCmdBeginRenderPass, vkCmdEndRenderPass, vkBeginCommandBuffer | NullRenderPass | NA |
+| Correct use of RenderPass | Validates that rendering commands are issued inside an active RenderPass | NO_ACTIVE_RENDERPASS | vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicBlendState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdNextSubpass vkCmdEndRenderPass vkCmdExecuteCommands vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect | BindPipelineNoRenderPass VtxBufferNoRenderPass | NA |
+| Valid RenderPass | Flag error if attempt made to Begin/End/Continue a NULL or otherwise invalid RenderPass object | INVALID_RENDERPASS | vkCmdBeginRenderPass vkCmdEndRenderPass vkBeginCommandBuffer | NullRenderPass | NA |
| DescriptorSet Updated | Warn user if DescriptorSet bound that was never updated | DESCRIPTOR_SET_NOT_UPDATED | vkCmdBindDescriptorSets | DescriptorSetNotUpdated | NA |
| Correct Clear Use | Warn user if CmdClear for Color or DepthStencil issued to Cmd Buffer prior to a Draw Cmd. RenderPass LOAD_OP_CLEAR is preferred in this case. | CLEAR_CMD_BEFORE_DRAW | vkCmdClearColorImage vkCmdClearDepthStencilImage | ClearCmdNoDraw | NA |
-
+| Index Buffer Binding | Verify that an index buffer is bound at the point when an indexed draw is attempted. | INDEX_BUFFER_NOT_BOUND | vkCmdDrawIndexed vkCmdDrawIndexedIndirect | TODO | Implement validation test |
+| NA | Enum used for informational messages | NONE | | NA | None |
+| NA | Enum used for errors in the layer itself. This does not indicate an app issue, but instead a bug in the layer. | INTERNAL_ERROR | | NA | None |
+| NA | Enum used when Drawstate attempts to allocate memory for its own internal use and is unable to. | OUT_OF_MEMORY | | NA | None |
+| NA | Enum used when Drawstate attempts to allocate memory for its own internal use and is unable to. | OUT_OF_MEMORY | | NA | None |
### DrawState Pending Work
Additional checks to be added to DrawState
@@ -82,6 +87,7 @@
| ----- | -------- | ---------------- | ------------ | -------- | ---------- |
| Input Parameters | Pointers in structures are recursively validated to be non-null. Enumerated types are validated against min and max enum values. Structure Types are verified to be correct. | NA | vkQueueSubmit vkAllocMemory vkFlushMappedMemoryRanges vkInvalidateMappedMemoryRanges vkQueueBindSparseBufferMemory vkQueueBindSparseImageOpaqueMemory vkQueueBindSparseImageMemory vkCreateFence vkResetFences vkWaitForFences vkCreateSemaphore vkCreateEvent vkCreateQueryPool vkCreateBuffer vkCreateBufferView vkCreateImage vkGetImageSubresourceLayout vkCreateImageView vkCreateAttachmentView vkCreateShader vkCreatePipelineCache vkMergePipelineCaches vkCreateGraphicsPipelines vkCreateComputePipelines vkCreatePipelineLayout vkCreateSampler vkCreateDescriptorSetLayout( vkCreateDescriptorPool vkAllocDescriptorSets vkFreeDescriptorSets vkUpdateDescriptorSets vkCreateDynamicViewportState vkCreateDynamicLineWidthState vkCreateDynamicDepthBiasState vkCreateDynamicBlendState vkCreateDynamicDepthBoundsState vkCreateDynamicStencilState vkCreateFramebuffer vkCreateRenderPass vkCreateCommandPool vkCreateCommandBuffer vkBeginCommandBuffer vkCmdBindDescriptorSets vkCmdBindVertexBuffers vkCmdCopyBuffer vkCmdCopyImage vkCmdBlitImage vkCmdCopyBufferToImage vkCmdCopyImageToBuffer vkCmdUpdateBuffer vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdResolveImage vkCmdWaitEvents vkCmdPipelineBarrier vkCmdPushConstants vkCmdBeginRenderPass vkCmdExecuteCommands | TBD | NA |
| Call results, Output Parameters | Return values are checked for VK_SUCCESS, returned pointers are checked to be NON-NULL, enumerated types of return values are checked to be within the defined range. | NA | vkEnumeratePhysicalDevices vkGetPhysicalDeviceFeatures vkGetPhysicalDeviceFormatProperties vkGetPhysicalDeviceImageFormatProperties vkGetPhysicalDeviceLimits vkGetPhysicalDeviceProperties vkGetPhysicalDeviceQueueFamilyProperties vkGetPhysicalDeviceMemoryProperties vkGetDeviceQueue vkQueueSubmit vkQueueWaitIdle vkDeviceWaitIdle vkAllocMemory vkFreeMemory vkMapMemory vkUnmapMemory vkFlushMappedMemoryRanges vkInvalidateMappedMemoryRanges vkGetDeviceMemoryCommitment vkBindBufferMemory vkBindImageMemory vkGetBufferMemoryRequirements vkGetImageMemoryRequirements vkGetImageSparseMemoryRequirements vkGetPhysicalDeviceSparseImageFormatProperties vkQueueBindSparseBufferMemory vkQueueBindSparseImageOpaqueMemory vkQueueBindSparseImageMemory vkCreateFence vkDestroyFence vkResetFences vkGetFenceStatus vkWaitForFences vkCreateSemaphore vkDestroySemaphore vkQueueSignalSemaphore vkQueueWaitSemaphore vkCreateEvent vkDestroyEvent vkGetEventStatus vkSetEvent vkResetEvent vkCreateQueryPool vkDestroyQueryPool vkGetQueryPoolResults vkCreateBuffer vkDestroyBuffer vkCreateBufferView vkDestroyBufferView vkCreateImage vkDestroyImage vkGetImageSubresourceLayout vkCreateImageView vkDestroyImageView vkCreateAttachmentView vkDestroyAttachmentView vkDestroyShaderModule vkCreateShader vkDestroyShader vkCreatePipelineCache vkDestroyPipelineCache vkGetPipelineCacheSize vkGetPipelineCacheData vkMergePipelineCaches vkCreateGraphicsPipelines vkCreateComputePipelines vkDestroyPipeline vkCreatePipelineLayout vkDestroyPipelineLayout vkCreateSampler vkDestroySampler vkCreateDescriptorSetLayout vkDestroyDescriptorSetLayout vkCreateDescriptorPool vkDestroyDescriptorPool vkResetDescriptorPool vkAllocDescriptorSets vkFreeDescriptorSets vkUpdateDescriptorSets vkCreateDynamicViewportState vkDestroyDynamicViewportState vkCreateDynamicLineWidthState vkDestroyDynamicLineWidthState vkCreateDynamicDepthBiasState vkDestroyDynamicDepthBiasState vkCreateDynamicBlendState vkDestroyDynamicBlendState vkCreateDynamicDepthBiasState vkDestroyDynamicDepthBiasState vkCreateDynamicStencilState vkDestroyDynamicStencilState vkCreateFramebuffer vkDestroyFramebuffer vkCreateRenderPass vkDestroyRenderPass vkGetRenderAreaGranularity vkCreateCommandPool vkDestroyCommandPool vkResetCommandPool vkCreateCommandBuffer vkDestroyCommandBuffer vkBeginCommandBuffer vkEndCommandBuffer vkResetCommandBuffer vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicBlendState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect vkCmdDispatch vkCmdDispatchIndirect vkCmdCopyBuffer vkCmdCopyImage vkCmdBlitImage vkCmdCopyBufferToImage vkCmdCopyImageToBuffer vkCmdUpdateBuffer vkCmdFillBuffer vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdResolveImage vkCmdSetEvent vkCmdResetEvent vkCmdWaitEvents vkCmdPipelineBarrier vkCmdBeginQuery vkCmdEndQuery vkCmdResetQueryPool vkCmdWriteTimestamp vkCmdCopyQueryPoolResults vkCmdPushConstants vkCmdBeginRenderPass vkCmdNextSubpass vkCmdEndRenderPass vkCmdExecuteCommands | TBD | NA |
+| NA | Enum used for informational messages | NONE | | NA | None |
### ParamChecker Pending Work
Additional work to be done
@@ -134,7 +140,8 @@
| Immutable Memory Binding | Validates that non-sparse memory bindings are immutable, so objects are not re-boundt | REBIND_OBJECT | vkBindBufferMemory, vkBindImageMemory | RebindMemory | NA |
| Image/Buffer Usage bits | Verify correct USAGE bits set based on how Images and Buffers are used | INVALID_USAGE_FLAG | vkCreateImage, vkCreateAttachmentView, vkCreateBuffer, vkCreateBufferView, vkCmdCopyBuffer, vkCmdCopyImage, vkCmdBlitImage, vkCmdCopyBufferToImage, vkCmdCopyImageToBuffer, vkCmdUpdateBuffer, vkCmdFillBuffer | InvalidUsageBits | NA |
| Objects Not Destroyed Warning | Warns if any memory objects have not been freed before their objects are destroyed | MEM_OBJ_CLEAR_EMPTY_BINDINGS | vkDestroyDevice | TBD | NA |
-
+| NA | Enum used for informational messages | NONE | | NA | None |
+| NA | Enum used for errors in the layer itself. This does not indicate an app issue, but instead a bug in the layer. | INTERNAL_ERROR | | NA | None |
### MemTracker Pending Work
@@ -174,6 +181,7 @@
| FS mixed broadcast | Flag error if the fragment shader writes both the legacy gl_FragCoord (which broadcasts to all CBs) and custom FS outputs. | FS_MIXED_BROADCAST | vkCreateGraphicsPipelines | TODO | Reference compiler refuses to compile shaders which do this |
| VI Binding Descriptions | Validate that there is a single vertex input binding description for each binding | INCONSISTENT_VI | vkCreateGraphicsPipelines | CreatePipelineAttribBindingConflict | NA |
| Shader Stage Check | Warns if shader stage is unsupported | UNKNOWN_STAGE | vkCreateGraphicsPipelines | TBD | NA |
+| NA | Enum used for informational messages | NONE | | NA | None |
### ShaderChecker Pending Work
- Additional test cases for variously broken SPIRV images
@@ -190,12 +198,15 @@
| Check | Overview | ENUM OBJTRACK_* | Relevant API | Testname | Notes/TODO |
| ----- | -------- | ---------------- | ------------ | -------- | ---------- |
-| Valid Object | Validates that referenced object was properly created and is currently valid. | UNKNOWN_OBJECT | vkAcquireNextImageWSI vkAllocDescriptorSets vkAllocMemory vkBeginCommandBuffer vkBindBufferMemory vkBindImageMemory vkCmdBeginQuery vkCmdBeginRenderPass vkCmdBindDescriptorSets vkCmdBindDynamicViewportState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicBlendState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindIndexBuffer vkCmdBindPipeline vkCmdBindVertexBuffers vkCmdBlitImage vkCmdClearColorAttachment vkCmdClearColorImage vkCmdClearDepthStencilAttachment vkCmdClearDepthStencilImage vkCmdCopyBuffer vkCmdCopyBufferToImage vkCmdCopyImage vkCmdCopyImageToBuffer vkCmdCopyQueryPoolResults vkCmdDispatch vkCmdDispatchIndirect vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndexedIndirect vkCmdDrawIndirect vkCmdEndQuery vkCmdEndRenderPass vkCmdExecuteCommands vkCmdFillBuffer vkCmdNextSubpass vkCmdPipelineBarrier vkCmdPushConstants vkCmdResetEvent vkCmdResetQueryPool vkCmdResolveImage vkCmdSetEvent vkCmdUpdateBuffer vkCmdWaitEvents vkCmdWriteTimestamp vkCreateAttachmentView vkCreateBuffer vkCreateBufferView vkCreateCommandBuffer vkCreateCommandPool vkCreateComputePipelines vkCreateDescriptorPool vkCreateDescriptorSetLayout vkCreateDynamicViewportState vkCreateDynamicLineWidthState vkCreateDynamicDepthBiasState vkCreateDynamicBlendState vkCreateDynamicDepthBoundsState vkCreateDynamicStencilState vkCreateEvent vkCreateFence vkCreateFramebuffer vkCreateGraphicsPipelines vkCreateImage vkCreateImageView vkCreatePipelineCache vkCreatePipelineLayout vkCreateQueryPool vkCreateRenderPass vkCreateSampler vkCreateSemaphore vkCreateShader vkCreateShaderModule vkCreateSwapChainWSI vkDestroyAttachmentView vkDestroyBuffer vkDestroyBufferView vkDestroyCommandBuffer vkDestroyCommandPool vkDestroyDescriptorPool vkDestroyDescriptorSetLayout vkDestroyDynamicBlendState vkDestroyDynamicLineWidthState vkDestroyDynamicDepthBiasState vkDestroyDynamicDepthBoundsState vkDestroyDynamicStencilState vkDestroyDynamicViewportState vkDestroyEvent vkDestroyFence vkDestroyFramebuffer vkDestroyImage vkDestroyImageView vkDestroyPipeline vkDestroyPipelineCache vkDestroyPipelineLayout vkDestroyQueryPool vkDestroyRenderPass vkDestroySampler vkDestroySemaphore vkDestroyShader vkDestroyShaderModule vkDestroySwapChainWSI vkDeviceWaitIdle vkEndCommandBuffer vkEnumeratePhysicalDevices vkFreeDescriptorSets vkFreeMemory vkFreeMemory vkGetBufferMemoryRequirements vkGetDeviceMemoryCommitment vkGetDeviceQueue vkGetEventStatus vkGetFenceStatus vkGetImageMemoryRequirements vkGetImageSparseMemoryRequirements vkGetImageSubresourceLayout vkGetPhysicalDeviceSurfaceSupportWSI vkGetPipelineCacheData vkGetPipelineCacheSize vkGetQueryPoolResults vkGetRenderAreaGranularity vkInvalidateMappedMemoryRanges vkMapMemory vkMergePipelineCaches vkQueueBindSparseBufferMemory vkQueueSignalSemaphore vkQueueWaitSemaphore vkResetCommandBuffer vkResetCommandPool vkResetDescriptorPool vkResetEvent vkResetFences vkSetEvent vkUnmapMemory vkUpdateDescriptorSets vkWaitForFences | ? | Every VkObject class of parameter will be run through this check. This check may ultimately supersede UNKNOWN_OBJECT |
+| Valid Object | Validates that referenced object was properly created and is currently valid. | INVALID_OBJECT | vkAcquireNextImageWSI vkAllocDescriptorSets vkAllocMemory vkBeginCommandBuffer vkBindBufferMemory vkBindImageMemory vkCmdBeginQuery vkCmdBeginRenderPass vkCmdBindDescriptorSets vkCmdBindDynamicViewportState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicBlendState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindIndexBuffer vkCmdBindPipeline vkCmdBindVertexBuffers vkCmdBlitImage vkCmdClearColorAttachment vkCmdClearColorImage vkCmdClearDepthStencilAttachment vkCmdClearDepthStencilImage vkCmdCopyBuffer vkCmdCopyBufferToImage vkCmdCopyImage vkCmdCopyImageToBuffer vkCmdCopyQueryPoolResults vkCmdDispatch vkCmdDispatchIndirect vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndexedIndirect vkCmdDrawIndirect vkCmdEndQuery vkCmdEndRenderPass vkCmdExecuteCommands vkCmdFillBuffer vkCmdNextSubpass vkCmdPipelineBarrier vkCmdPushConstants vkCmdResetEvent vkCmdResetQueryPool vkCmdResolveImage vkCmdSetEvent vkCmdUpdateBuffer vkCmdWaitEvents vkCmdWriteTimestamp vkCreateAttachmentView vkCreateBuffer vkCreateBufferView vkCreateCommandBuffer vkCreateCommandPool vkCreateComputePipelines vkCreateDescriptorPool vkCreateDescriptorSetLayout vkCreateDynamicViewportState vkCreateDynamicLineWidthState vkCreateDynamicDepthBiasState vkCreateDynamicBlendState vkCreateDynamicDepthBoundsState vkCreateDynamicStencilState vkCreateEvent vkCreateFence vkCreateFramebuffer vkCreateGraphicsPipelines vkCreateImage vkCreateImageView vkCreatePipelineCache vkCreatePipelineLayout vkCreateQueryPool vkCreateRenderPass vkCreateSampler vkCreateSemaphore vkCreateShader vkCreateShaderModule vkCreateSwapChainWSI vkDestroyAttachmentView vkDestroyBuffer vkDestroyBufferView vkDestroyCommandBuffer vkDestroyCommandPool vkDestroyDescriptorPool vkDestroyDescriptorSetLayout vkDestroyDynamicBlendState vkDestroyDynamicLineWidthState vkDestroyDynamicDepthBiasState vkDestroyDynamicDepthBoundsState vkDestroyDynamicStencilState vkDestroyDynamicViewportState vkDestroyEvent vkDestroyFence vkDestroyFramebuffer vkDestroyImage vkDestroyImageView vkDestroyPipeline vkDestroyPipelineCache vkDestroyPipelineLayout vkDestroyQueryPool vkDestroyRenderPass vkDestroySampler vkDestroySemaphore vkDestroyShader vkDestroyShaderModule vkDestroySwapChainWSI vkDeviceWaitIdle vkEndCommandBuffer vkEnumeratePhysicalDevices vkFreeDescriptorSets vkFreeMemory vkFreeMemory vkGetBufferMemoryRequirements vkGetDeviceMemoryCommitment vkGetDeviceQueue vkGetEventStatus vkGetFenceStatus vkGetImageMemoryRequirements vkGetImageSparseMemoryRequirements vkGetImageSubresourceLayout vkGetPhysicalDeviceSurfaceSupportWSI vkGetPipelineCacheData vkGetPipelineCacheSize vkGetQueryPoolResults vkGetRenderAreaGranularity vkInvalidateMappedMemoryRanges vkMapMemory vkMergePipelineCaches vkQueueBindSparseBufferMemory vkQueueSignalSemaphore vkQueueWaitSemaphore vkResetCommandBuffer vkResetCommandPool vkResetDescriptorPool vkResetEvent vkResetFences vkSetEvent vkUnmapMemory vkUpdateDescriptorSets vkWaitForFences | ? | Every VkObject class of parameter will be run through this check. This check may ultimately supersede UNKNOWN_OBJECT |
| Object Cleanup | Verify that object properly destroyed | DESTROY_OBJECT_FAILED | vkDestroyInstance, vkDestroyDevice, vkFreeMemory | ? | NA |
| Objects Leak | When an Instance or Device object is destroyed, validates that all objects belonging to that device/instance have previously been destroyed | OBJECT_LEAK | vkDestroyDevice vkDestroyInstance | ? | NA |
-| Object Count | Flag error if number of objects requested from extenstion functions exceeds max number of actual objects | OBJCOUNT_MAX_EXCEEDED | objTrackGetObjects, objTrackGetObjectsOfType | ? | NA |
+| Object Count | Flag error if number of objects requested from extenstion functions exceeds max number of actual objects | OBJCOUNT_MAX_EXCEEDED | objTrackGetObjects objTrackGetObjectsOfType | ? | NA |
| Valid Fence for Wait | Flag error if waiting on unsubmitted fence object | INVALID_FENCE | vkGetFenceStatus | WaitForUnsubmittedFence | NA |
| Valid Destroy Object | Validates that an object pass into a destroy function was properly created and is currently valid | NONE | vkDestroyInstance vkDestroyDevice vkDestroyFence vkDestroySemaphore vkDestroyEvent vkDestroyQueryPool vkDestroyBuffer vkDestroyBufferView vkDestroyImage vkDestroyImageView vkDestroyAttachmentView vkDestroyShaderModule vkDestroyShader vkDestroyPipelineCache vkDestroyPipeline vkDestroyPipelineLayout vkDestroySampler vkDestroyDescriptorSetLayout vkDestroyDescriptorPool vkDestroyDynamicViewportState vkDestroyDynamicBlendState vkDestroyDynamicLineWidthState vkDestroyDynamicDepthBiasState vkDestroyDynamicDepthBoundsState vkDestroyDynamicStencilState vkDestroyCommandPool vkDestroyCommandBuffer vkDestroyFramebuffer vkDestroyRenderPass vkDestroySwapChainWSI | TBD | These cases need to be moved to a more appropriate error enum |
+| Unknown object | Internal layer errors when it attempts to update use count for an object that's not in its internal tracking datastructures. | UNKNOWN_OBJECT | | NA | This may be irrelevant due to INVALID_OBJECT error, need to look closely and merge this with that error as appropriate. |
+| NA | Enum used for informational messages | NONE | | NA | None |
+| NA | Enum used for errors in the layer itself. This does not indicate an app issue, but instead a bug in the layer. | INTERNAL_ERROR | | NA | None |
### ObjectTracker Pending Work
@@ -234,6 +245,7 @@
| ----- | -------- | ---------------- | ---------------- | -------- | ---------- |
| Thread Collision | Detects and notifies user if multiple threads are modifying thes same object | MULTIPLE_THREADS | vkQueueSubmit vkFreeMemory vkMapMemory vkUnmapMemory vkFlushMappedMemoryRanges vkInvalidateMappedMemoryRanges vkBindBufferMemory vkBindImageMemory vkQueueBindSparseBufferMemory vkQueueBindSparseImageOpaqueMemory vkQueueBindSparseImageMemory vkDestroySemaphore vkQueueSignalSemaphore vkDestroyBuffer vkDestroyImage vkDestroyDescriptorPool vkResetDescriptorPool vkAllocDescriptorSets vkFreeDescriptorSets vkDestroyCommandBuffer vkBeginCommandBuffer vkEndCommandBuffer vkResetCommandBuffer vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicBlendState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect vkCmdDispatch vkCmdDispatchIndirect vkCmdCopyBuffer vkCmdCopyImage vkCmdBlitImage vkCmdCopyBufferToImage vkCmdCopyImageToBuffer vkCmdUpdateBuffer vkCmdFillBuffer vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdResolveImage vkCmdSetEvent vkCmdResetEvent vkCmdWaitEvents vkCmdPipelineBarrier vkCmdBeginQuery vkCmdEndQuery vkCmdResetQueryPool vkCmdWriteTimestamp vkCmdCopyQueryPoolResults vkCmdBeginRenderPass vkCmdNextSubpass vkCmdPushConstants vkCmdEndRenderPass vkCmdExecuteCommands | ??? | NA |
| Thread Reentrancy | Detects cases of a single thread calling Vulkan reentrantly | SINGLE_THREAD_REUSE | vkQueueSubmit vkFreeMemory vkMapMemory vkUnmapMemory vkFlushMappedMemoryRanges vkInvalidateMappedMemoryRanges vkBindBufferMemory vkBindImageMemory vkQueueBindSparseBufferMemory vkQueueBindSparseImageOpaqueMemory vkQueueBindSparseImageMemory vkDestroySemaphore vkQueueSignalSemaphore vkDestroyBuffer vkDestroyImage vkDestroyDescriptorPool vkResetDescriptorPool vkAllocDescriptorSets vkFreeDescriptorSets vkDestroyCommandBuffer vkBeginCommandBuffer vkEndCommandBuffer vkResetCommandBuffer vkCmdBindPipeline vkCmdBindDynamicViewportState vkCmdBindDynamicBlendState vkCmdBindDynamicLineWidthState vkCmdBindDynamicDepthBiasState vkCmdBindDynamicDepthBoundsState vkCmdBindDynamicStencilState vkCmdBindDescriptorSets vkCmdBindIndexBuffer vkCmdBindVertexBuffers vkCmdDraw vkCmdDrawIndexed vkCmdDrawIndirect vkCmdDrawIndexedIndirect vkCmdDispatch vkCmdDispatchIndirect vkCmdCopyBuffer vkCmdCopyImage vkCmdBlitImage vkCmdCopyBufferToImage vkCmdCopyImageToBuffer vkCmdUpdateBuffer vkCmdFillBuffer vkCmdClearColorImage vkCmdClearDepthStencilImage vkCmdClearColorAttachment vkCmdClearDepthStencilAttachment vkCmdResolveImage vkCmdSetEvent vkCmdResetEvent vkCmdWaitEvents vkCmdPipelineBarrier vkCmdBeginQuery vkCmdEndQuery vkCmdResetQueryPool vkCmdWriteTimestamp vkCmdCopyQueryPoolResults vkCmdBeginRenderPass vkCmdNextSubpass vkCmdPushConstants vkCmdEndRenderPass vkCmdExecuteCommands | ??? | NA |
+| NA | Enum used for informational messages | NONE | | NA | None |
### Threading Pending Work
Additional work to be done
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 2582200..f9e3e62 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -87,6 +87,7 @@
COMMAND ln -sf ${CMAKE_CURRENT_SOURCE_DIR}/run_all_tests_with_layers.sh
COMMAND ln -sf ${CMAKE_CURRENT_SOURCE_DIR}/layer_test_suite.py
COMMAND ln -sf ${CMAKE_CURRENT_SOURCE_DIR}/vktracereplay.sh
+ COMMAND ln -sf ${CMAKE_CURRENT_SOURCE_DIR}/vkvalidatelayerdoc.sh
VERBATIM
)
endif()
@@ -96,10 +97,12 @@
FILE(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/_run_all_tests.ps1 RUN_ALL)
FILE(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/_run_all_tests_with_layers.ps1 RUN_ALL_WITH_LAYERS)
FILE(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/_vktracereplay.ps1 VKTRACEREPLAY)
+ FILE(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/_vkvalidatelayerdoc.ps1 VKVALIDATELAYERDOC)
add_custom_target(binary-dir-symlinks ALL
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${RUN_ALL} run_all_tests.ps1
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${RUN_ALL_WITH_LAYERS} run_all_tests_with_layers.ps1
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${VKTRACEREPLAY} vktracereplay.ps1
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different ${VKVALIDATELAYERDOC} vkvalidatelayerdoc.ps1
COMMAND IF NOT EXIST golden mklink /J golden ${GOLDEN}
VERBATIM
)
diff --git a/tests/_run_all_tests.ps1 b/tests/_run_all_tests.ps1
index e17c7ab..53389dd 100755
--- a/tests/_run_all_tests.ps1
+++ b/tests/_run_all_tests.ps1
@@ -18,3 +18,4 @@
& $dPath\vk_render_tests
& $dPath\vk_layer_validation_tests
.\vktracereplay.ps1 "-$dPath"
+.\vkvalidatelayerdoc.ps1
diff --git a/tests/_vkvalidatelayerdoc.ps1 b/tests/_vkvalidatelayerdoc.ps1
new file mode 100644
index 0000000..cdd7150
--- /dev/null
+++ b/tests/_vkvalidatelayerdoc.ps1
@@ -0,0 +1,33 @@
+# Powershell script for running the vktrace trace/replay auto test
+# To run this test:
+# cd <this-dir>
+# powershell C:\src\LoaderAndTools\vktracereplay.ps1 [-Debug]
+
+if ($args[0] -eq "-Debug") {
+ $dPath = "Debug"
+} else {
+ $dPath = "Release"
+}
+
+write-host -background black -foreground green "[ RUN ] " -nonewline
+write-host "vkvalidatelayerdoc.ps1: Validate layer documentation"
+
+# Run doc validation from project root dir
+push-location ..\..
+
+# Validate that layer documentation matches source contents
+python vk_layer_documentation_generate.py --validate
+
+# Report result based on exit code
+if (!$LASTEXITCODE) {
+ write-host -background black -foreground green "[ PASSED ] " -nonewline;
+ $exitstatus = 0
+} else {
+ echo 'Validation of vk_validation_layer_details.md failed'
+ write-host -background black -foreground red "[ FAILED ] " -nonewline;
+ echo '1 FAILED TEST'
+ $exitstatus = 1
+}
+
+pop-location
+exit $exitstatus
diff --git a/tests/run_all_tests.sh b/tests/run_all_tests.sh
index 097b9c1..a0c59b5 100755
--- a/tests/run_all_tests.sh
+++ b/tests/run_all_tests.sh
@@ -27,3 +27,9 @@
# vktracereplay.sh tests vktrace trace and replay
./vktracereplay.sh
+
+# vk_layer_documentation_generate.py is run from the project root dir
+# the --validate option will verify that checks documented in layer header
+# files match those documented in layer/vk_validation_layer_details.md
+./vkvalidatelayerdoc.sh
+
diff --git a/tests/vkvalidatelayerdoc.sh b/tests/vkvalidatelayerdoc.sh
new file mode 100755
index 0000000..e244ed0
--- /dev/null
+++ b/tests/vkvalidatelayerdoc.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+#set -x
+if [ -t 1 ] ; then
+ RED='\033[0;31m'
+ GREEN='\033[0;32m'
+ NC='\033[0m' # No Color
+else
+ RED=''
+ GREEN=''
+ NC=''
+fi
+
+printf "$GREEN[ RUN ]$NC $0\n"
+
+# Run doc validation from project root dir
+pushd ../..
+
+# Validate that layer documentation matches source contents
+./vk_layer_documentation_generate.py --validate
+
+RES=$?
+
+
+if [ $RES -eq 0 ] ; then
+ printf "$GREEN[ PASSED ]$NC 1 test\n"
+ exit 0
+else
+ printf "$RED[ FAILED ]$NC Validation of vk_validation_layer_details.md failed\n"
+ printf "$RED[ FAILED ]$NC 1 test\n"
+ printf "1 TEST FAILED\n"
+ exit 1
+fi
+# Restore original directory
+popd
diff --git a/vk_layer_documentation_generate.py b/vk_layer_documentation_generate.py
new file mode 100755
index 0000000..da18b69
--- /dev/null
+++ b/vk_layer_documentation_generate.py
@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+#
+# VK
+#
+# Copyright (C) 2015 LunarG, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+import argparse
+import os
+import sys
+import vulkan
+import platform
+
+# vk_layer_documentation_generate.py overview
+# This script is intended to generate documentation based on vulkan layers
+# It parses known validation layer headers for details of the validation checks
+# It parses validation layer source files for specific code where checks are implemented
+# structs in a human-readable txt format, as well as utility functions
+# to print enum values as strings
+
+# NOTE : Initially the script is performing validation of a hand-written document
+# Right now it does 3 checks:
+# 1. Verify ENUM codes declared in source are documented
+# 2. Verify ENUM codes in document are declared in source
+# 3. Verify API function names in document are in the actual API header (vulkan.py)
+# Currently script will flag errors in all of these cases
+
+# TODO : Need a formal specification of the syntax for doc generation
+# Initially, these are the basics:
+# 1. Validation checks have unique ENUM values defined in validation layer header
+# 2. ENUM includes comments for 1-line overview of check and more detailed description
+# 3. Actual code implementing checks includes ENUM value in callback
+# 4. Code to test checks should include reference to ENUM
+
+
+# TODO : Need list of known validation layers to use as default input
+# Just a couple of flat lists right now, but may need to make this input file
+# or at least a more dynamic data structure
+layer_inputs = { 'draw_state' : {'header' : 'layers/draw_state.h',
+ 'source' : 'layers/draw_state.cpp',
+ 'generated' : False,
+ 'error_enum' : 'DRAW_STATE_ERROR'},
+ 'mem_tracker' : {'header' : 'layers/mem_tracker.h',
+ 'source' : 'layers/mem_tracker.cpp',
+ 'generated' : False,
+ 'error_enum' : 'MEM_TRACK_ERROR'},
+ 'shader_checker' : {'header' : 'layers/shader_checker.h',
+ 'source' : 'layers/shader_checker.cpp',
+ 'generated' : False,
+ 'error_enum' : 'SHADER_CHECKER_ERROR'},
+ 'threading' : {'header' : 'layers/threading.h',
+ 'source' : 'dbuild/layers/threading.cpp',
+ 'generated' : True,
+ 'error_enum' : 'THREADING_CHECKER_ERROR'},
+ 'object_track' : {'header' : 'layers/object_track.h',
+ 'source' : 'dbuild/layers/object_track.cpp',
+ 'generated' : True,
+ 'error_enum' : 'OBJECT_TRACK_ERROR',},
+ }
+
+builtin_headers = [layer_inputs[ln]['header'] for ln in layer_inputs]
+builtin_source = [layer_inputs[ln]['source'] for ln in layer_inputs]
+
+# List of extensions in layers that are included in documentation, but not in vulkan.py API set
+layer_extension_functions = ['objTrackGetObjects', 'objTrackGetObjectsOfType']
+
+def handle_args():
+ parser = argparse.ArgumentParser(description='Generate layer documenation from source.')
+ parser.add_argument('--in_headers', required=False, default=builtin_headers, help='The input layer header files from which code will be generated.')
+ parser.add_argument('--in_source', required=False, default=builtin_source, help='The input layer source files from which code will be generated.')
+ parser.add_argument('--layer_doc', required=False, default='layers/vk_validation_layer_details.md', help='Existing layer document to be validated against actual layers.')
+ parser.add_argument('--validate', action='store_true', default=False, help='Validate that there are no mismatches between layer documentation and source. This includes cross-checking the validation checks, and making sure documented Vulkan API calls exist.')
+ parser.add_argument('--print_structs', action='store_true', default=False, help='Primarily a debug option that prints out internal data structs used to generate layer docs.')
+ parser.add_argument('--print_doc_checks', action='store_true', default=False, help='Primarily a debug option that prints out all of the checks that are documented.')
+ return parser.parse_args()
+
+# Little helper class for coloring cmd line output
+class bcolors:
+
+ def __init__(self):
+ self.GREEN = '\033[0;32m'
+ self.RED = '\033[0;31m'
+ self.ENDC = '\033[0m'
+ if 'Linux' != platform.system():
+ self.GREEN = ''
+ self.RED = ''
+ self.ENDC = ''
+
+ def green(self):
+ return self.GREEN
+
+ def red(self):
+ return self.RED
+
+ def endc(self):
+ return self.ENDC
+
+# Class to parse the layer source code and store details in internal data structs
+class LayerParser:
+ def __init__(self, header_file_list, source_file_list):
+ self.header_files = header_file_list
+ self.source_files = source_file_list
+ self.layer_dict = {}
+ self.api_dict = {}
+
+ # Parse layer header files into internal dict data structs
+ def parse(self):
+ # For each header file, parse details into dicts
+ # TODO : Should have a global dict element to track overall list of checks
+ store_enum = False
+ for hf in self.header_files:
+ layer_name = os.path.basename(hf).split('.')[0]
+ self.layer_dict[layer_name] = {} # initialize a new dict for this layer
+ self.layer_dict[layer_name]['CHECKS'] = [] # enum of checks is stored in a list
+ #print('Parsing header file %s as layer name %s' % (hf, layer_name))
+ with open(hf) as f:
+ for line in f:
+ if True in [line.strip().startswith(comment) for comment in ['//', '/*']]:
+ #print("Skipping comment line: %s" % line)
+ # For now skipping lines starting w/ comment, may use these to capture
+ # documentation in the future
+ continue
+
+ # Find enums
+ if store_enum:
+ if '}' in line: # we're done with enum definition
+ store_enum = False
+ continue
+ # grab the enum name as a unique check
+ if ',' in line:
+ # TODO : When documentation for a check is contained in the source,
+ # this is where we should also capture that documentation so that
+ # it can then be transformed into desired doc format
+ enum_name = line.split(',')[0].strip()
+ # Flag an error if we have already seen this enum
+ if enum_name in self.layer_dict[layer_name]['CHECKS']:
+ print('ERROR : % layer has duplicate error enum: %s' % (layer_name, enum_name))
+ self.layer_dict[layer_name]['CHECKS'].append(enum_name)
+ # If the line includes 'typedef', 'enum', and the expected enum name, start capturing enums
+ if False not in [ex in line for ex in ['typedef', 'enum', layer_inputs[layer_name]['error_enum']]]:
+ store_enum = True
+
+ # For each source file, parse into dicts
+ for sf in self.source_files:
+ #print('Parsing source file %s' % sf)
+ pass
+ # TODO : In the source file we want to see where checks actually occur
+ # Need to build function tree of checks so that we know all of the
+ # checks that occur under a top-level Vulkan API call
+ # Eventually in the validation we can flag ENUMs that aren't being
+ # used in the source, and we can document source code lines as well
+ # as Vulkan API calls where each specific ENUM check is made
+
+ def print_structs(self):
+ print('This is where I print the data structs')
+ for layer in self.layer_dict:
+ print('Layer %s has %i checks:\n%s' % (layer, len(self.layer_dict[layer]['CHECKS'])-1, "\n\t".join(self.layer_dict[layer]['CHECKS'])))
+
+# Class to parse hand-written md layer documentation into a dict and then validate its contents
+class LayerDoc:
+ def __init__(self, source_file):
+ self.layer_doc_filename = source_file
+ self.txt_color = bcolors()
+ # Main data struct to store info from layer doc
+ self.layer_doc_dict = {}
+ # Comprehensive list of all validation checks recorded in doc
+ self.enum_list = []
+
+ # Parse the contents of doc into data struct
+ def parse(self):
+ layer_name = 'INIT'
+ parse_layer_details = False
+ detail_trigger = '| Check | '
+ parse_pending_work = False
+ pending_trigger = ' Pending Work'
+ parse_overview = False
+ overview_trigger = ' Overview'
+ enum_prefix = ''
+
+ with open(self.layer_doc_filename) as f:
+ for line in f:
+ if parse_pending_work:
+ if '.' in line and line.strip()[0].isdigit():
+ todo_item = line.split('.')[1].strip()
+ self.layer_doc_dict[layer_name]['pending'].append(todo_item)
+ if pending_trigger in line and '##' in line:
+ parse_layer_details = False
+ parse_pending_work = True
+ parse_overview = False
+ self.layer_doc_dict[layer_name]['pending'] = []
+ if parse_layer_details:
+ # Grab details but skip the fomat line with a bunch of '-' chars
+ if '|' in line and line.count('-') < 20:
+ detail_sections = line.split('|')
+ #print("Details elements from line %s: %s" % (line, detail_sections))
+ check_name = '%s%s' % (enum_prefix, detail_sections[3].strip())
+ if '_NA' in check_name:
+ # TODO : Should clean up these NA checks in the doc, skipping them for now
+ continue
+ self.enum_list.append(check_name)
+ self.layer_doc_dict[layer_name][check_name] = {}
+ self.layer_doc_dict[layer_name][check_name]['summary_txt'] = detail_sections[1].strip()
+ self.layer_doc_dict[layer_name][check_name]['details_txt'] = detail_sections[2].strip()
+ self.layer_doc_dict[layer_name][check_name]['api_list'] = detail_sections[4].split()
+ self.layer_doc_dict[layer_name][check_name]['tests'] = detail_sections[5].split()
+ self.layer_doc_dict[layer_name][check_name]['notes'] = detail_sections[6].strip()
+ # strip any unwanted commas from api and test names
+ self.layer_doc_dict[layer_name][check_name]['api_list'] = [a.strip(',') for a in self.layer_doc_dict[layer_name][check_name]['api_list']]
+ self.layer_doc_dict[layer_name][check_name]['tests'] = [a.strip(',') for a in self.layer_doc_dict[layer_name][check_name]['tests']]
+ # Trigger details parsing when we have table header
+ if detail_trigger in line:
+ parse_layer_details = True
+ parse_pending_work = False
+ parse_overview = False
+ enum_txt = line.split('|')[3]
+ if '*' in enum_txt:
+ enum_prefix = enum_txt.split()[-1].strip('*').strip()
+ #print('prefix: %s' % enum_prefix)
+ if parse_overview:
+ self.layer_doc_dict[layer_name]['overview'] += line
+ if overview_trigger in line and '##' in line:
+ parse_layer_details = False
+ parse_pending_work = False
+ parse_overview = True
+ layer_name = line.split()[1]
+ self.layer_doc_dict[layer_name] = {}
+ self.layer_doc_dict[layer_name]['overview'] = ''
+
+ # Verify that checks and api references in layer doc match reality
+ # Report API calls from doc that are not found in API
+ # Report checks from doc that are not in actual layers
+ # Report checks from layers that are not captured in doc
+ def validate(self, layer_dict):
+ # Count number of errors found and return it
+ errors_found = 0
+ # First we'll go through the doc datastructures and flag any issues
+ for chk in self.enum_list:
+ doc_layer_found = False
+ for real_layer in layer_dict:
+ if chk in layer_dict[real_layer]['CHECKS']:
+ #print('Found actual layer check %s in doc' % (chk))
+ doc_layer_found = True
+ continue
+ if not doc_layer_found:
+ print(self.txt_color.red() + 'Actual layers do not contain documented check: %s' % (chk) + self.txt_color.endc())
+ errors_found += 1
+ # Now go through API names in doc and verify they're real
+ # First we're going to transform proto names from vulkan.py into single list
+ core_api_names = [p.name for p in vulkan.core.protos]
+ wsi_s_names = [p.name for p in vulkan.wsi_swapchain.protos]
+ wsi_ds_names = [p.name for p in vulkan.wsi_device_swapchain.protos]
+ dbg_rpt_names = [p.name for p in vulkan.debug_report_lunarg.protos]
+ dbg_mrk_names = [p.name for p in vulkan.debug_marker_lunarg.protos]
+ api_names = core_api_names + wsi_s_names + wsi_ds_names + dbg_rpt_names + dbg_mrk_names
+ for ln in self.layer_doc_dict:
+ for chk in self.layer_doc_dict[ln]:
+ if chk in ['overview', 'pending']:
+ continue
+ for api in self.layer_doc_dict[ln][chk]['api_list']:
+ if api[2:] not in api_names and api not in layer_extension_functions:
+ print(self.txt_color.red() + 'Doc references invalid function: %s' % (api) + self.txt_color.endc())
+ errors_found += 1
+ # Now go through all of the actual checks in the layers and make sure they're covered in the doc
+ for ln in layer_dict:
+ for chk in layer_dict[ln]['CHECKS']:
+ if chk not in self.enum_list:
+ print(self.txt_color.red() + 'Doc is missing check: %s' % (chk) + self.txt_color.endc())
+ errors_found += 1
+
+ return errors_found
+
+ # Print all of the checks captured in the doc
+ def print_checks(self):
+ print('Checks captured in doc:\n%s' % ('\n\t'.join(self.enum_list)))
+
+def main(argv=None):
+ # Parse args
+ opts = handle_args()
+ # Create parser for layer files
+ layer_parser = LayerParser(opts.in_headers, opts.in_source)
+ # Parse files into internal data structs
+ layer_parser.parse()
+
+ # Generate requested types of output
+ if opts.print_structs: # Print details of internal data structs
+ layer_parser.print_structs()
+
+ layer_doc = LayerDoc(opts.layer_doc)
+ layer_doc.parse()
+ if opts.print_doc_checks:
+ layer_doc.print_checks()
+
+ if opts.validate:
+ num_errors = layer_doc.validate(layer_parser.layer_dict)
+ if (0 == num_errors):
+ txt_color = bcolors()
+ print(txt_color.green() + 'No mismatches found between %s and implementation' % (os.path.basename(opts.layer_doc)) + txt_color.endc())
+ else:
+ return num_errors
+ return 0
+
+if __name__ == "__main__":
+ sys.exit(main())
+