diff --git a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt index b61c4400..8727ed18 100644 --- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt +++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt @@ -299,7 +299,7 @@ ifdef::VK_KHR_shared_presentable_image[] endif::VK_KHR_shared_presentable_image[] * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01277]] If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, - pname:pQueueFamilyIndices must: be a pointer to an array of + pname:pQueueFamilyIndices must: be a valid pointer to an array of pname:queueFamilyIndexCount basetype:uint32_t values * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]] If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt index f4bdf6f4..88fb9ede 100644 --- a/doc/specs/vulkan/chapters/cmdbuffers.txt +++ b/doc/specs/vulkan/chapters/cmdbuffers.txt @@ -504,7 +504,7 @@ recorded into it, becomes <>. All elements of pname:pCommandBuffers must: not be in the <> * [[VUID-vkFreeCommandBuffers-pCommandBuffers-00048]] - pname:pCommandBuffers must: be a pointer to an array of + pname:pCommandBuffers must: be a valid pointer to an array of pname:commandBufferCount sname:VkCommandBuffer handles, each element of which must: either be a valid handle or `NULL` **** diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt index 0457e75f..302beccc 100644 --- a/doc/specs/vulkan/chapters/descriptorsets.txt +++ b/doc/specs/vulkan/chapters/descriptorsets.txt @@ -747,7 +747,7 @@ avoid wasted memory. If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and pname:descriptorCount is not `0` and pname:pImmutableSamplers is not - `NULL`, pname:pImmutableSamplers must: be a pointer to an array of + `NULL`, pname:pImmutableSamplers must: be a valid pointer to an array of pname:descriptorCount valid sname:VkSampler handles * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-00283]] If pname:descriptorCount is not `0`, pname:stageFlags must: be a valid @@ -1665,7 +1665,7 @@ in pname:pDescriptorSets are invalid. All submitted commands that refer to any element of pname:pDescriptorSets must: have completed execution * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00310]] - pname:pDescriptorSets must: be a pointer to an array of + pname:pDescriptorSets must: be a valid pointer to an array of pname:descriptorSetCount sname:VkDescriptorSet handles, each element of which must: either be a valid handle or dlink:VK_NULL_HANDLE * [[VUID-vkFreeDescriptorSets-pDescriptorSets-00311]] @@ -1838,19 +1838,19 @@ bindings as needed to update all pname:descriptorCount descriptors. ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, pname:pImageInfo must: be a - pointer to an array of pname:descriptorCount valid + valid pointer to an array of pname:descriptorCount valid sname:VkDescriptorImageInfo structures * [[VUID-VkWriteDescriptorSet-descriptorType-00323]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER or ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER, pname:pTexelBufferView - must: be a pointer to an array of pname:descriptorCount valid + must: be a valid pointer to an array of pname:descriptorCount valid sname:VkBufferView handles * [[VUID-VkWriteDescriptorSet-descriptorType-00324]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER, ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, pname:pBufferInfo must: - be a pointer to an array of pname:descriptorCount valid + be a valid pointer to an array of pname:descriptorCount valid sname:VkDescriptorBufferInfo structures * [[VUID-VkWriteDescriptorSet-descriptorType-00325]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER or @@ -2434,8 +2434,8 @@ include::../api/protos/vkUpdateDescriptorSetWithTemplateKHR.txt[] .Valid Usage **** * [[VUID-vkUpdateDescriptorSetWithTemplateKHR-pData-01685]] - pname:pData must: be a pointer to a memory that contains one or more - valid instances of slink:VkDescriptorImageInfo, + pname:pData must: be a valid pointer to a memory that contains one or + more valid instances of slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined by pname:descriptorUpdateTemplate when it was created with flink:vkCreateDescriptorUpdateTemplateKHR @@ -2768,8 +2768,8 @@ include::../api/protos/vkCmdPushDescriptorSetWithTemplateKHR.txt[] update template must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] - pname:pData must: be a pointer to a memory that contains one or more - valid instances of slink:VkDescriptorImageInfo, + pname:pData must: be a valid pointer to a memory that contains one or + more valid instances of slink:VkDescriptorImageInfo, slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined by pname:descriptorUpdateTemplate when it was created with flink:vkCreateDescriptorUpdateTemplateKHR diff --git a/doc/specs/vulkan/chapters/fragops.txt b/doc/specs/vulkan/chapters/fragops.txt index 771fa5c6..30b87d30 100644 --- a/doc/specs/vulkan/chapters/fragops.txt +++ b/doc/specs/vulkan/chapters/fragops.txt @@ -134,7 +134,7 @@ pname:discardRectangleCount)#. sname:VkPhysicalDeviceDiscardRectanglePropertiesEXT::pname:maxDiscardRectangles, inclusive * [[VUID-vkCmdSetDiscardRectangleEXT-pDiscardRectangles-00586]] - pname:pDiscardRectangles must: be a pointer to an array of + pname:pDiscardRectangles must: be a valid pointer to an array of pname:discardRectangleCount valid sname:VkRect2D structures * [[VUID-vkCmdSetDiscardRectangleEXT-x-00587]] The pname:x and pname:y members of pname:offset in sname:VkRect2D must: diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt index dddc4a3c..cd3698a3 100644 --- a/doc/specs/vulkan/chapters/fundamentals.txt +++ b/doc/specs/vulkan/chapters/fundamentals.txt @@ -268,10 +268,12 @@ frees. It is an application's responsibility to track the lifetime of Vulkan objects, and not to destroy them while they are still in use. -Application-owned memory is immediately consumed by any Vulkan command it is -passed into. -The application can: alter or free this memory as soon as the commands that -consume it have returned. +[[fundamentals-objectmodel-lifetime-acquire]] +The ownership of application-owned memory is immediately acquired by any +Vulkan command it is passed into. +Ownership of such memory must: be released back to the application at the +end of the duration of the command, so that the application can: alter or +free this memory as soon as all the commands that acquired it have returned. The following object types are consumed when they are passed into a Vulkan command and not further accessed by the objects they are used to create. @@ -600,6 +602,16 @@ library) perform memory barriers as a part of mutual exclusion, so mutexing Vulkan objects via these primitives will have the desired effect. ==== +Similarly the application must: avoid any potential data hazard of +application-owned memory that has its +<> +by a Vulkan command. +While the ownership of application-owned memory remains acquired by a +command the implementation may: read the memory at any point, and it may: +write non-code:const qualified memory at any point. +Parameters referring to non-code:const qualified application-owned memory +are not marked explicitly as _externally synchronized_ in the specification. + Many object types are _immutable_, meaning the objects cannot: change once they have been created. These types of objects never need external synchronization, except that they @@ -754,13 +766,13 @@ commands, which will silently ignore these values. [[fundamentals-validusage-pointers]] ==== Valid Usage for Pointers -Any parameter that is a pointer must: either be a valid pointer, or if -_explicitly called out in the specification_, can: be `NULL`. -A pointer is valid if it points at memory containing values of the number -and type(s) expected by the command, and all fundamental types accessed -through the pointer (e.g. as elements of an array or as members of a -structure) satisfy the alignment requirements of the host processor. +Any parameter that is a pointer must: be a _valid pointer_ only if it is +explicitly called out by a Valid Usage statement. +A pointer is "`valid`" if it points at memory containing values of the +number and type(s) expected by the command, and all fundamental types +accessed through the pointer (e.g. as elements of an array or as members of +a structure) satisfy the alignment requirements of the host processor. [[fundamentals-validusage-strings]] ==== Valid Usage for Strings diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt index 61a724ea..dba2379d 100644 --- a/doc/specs/vulkan/chapters/memory.txt +++ b/doc/specs/vulkan/chapters/memory.txt @@ -60,13 +60,13 @@ include::../api/structs/VkAllocationCallbacks.txt[] .Valid Usage **** * [[VUID-VkAllocationCallbacks-pfnAllocation-00632]] - pname:pfnAllocation must: be a pointer to a valid user-defined + pname:pfnAllocation must: be a valid pointer to a valid user-defined tlink:PFN_vkAllocationFunction * [[VUID-VkAllocationCallbacks-pfnReallocation-00633]] - pname:pfnReallocation must: be a pointer to a valid user-defined + pname:pfnReallocation must: be a valid pointer to a valid user-defined tlink:PFN_vkReallocationFunction * [[VUID-VkAllocationCallbacks-pfnFree-00634]] - pname:pfnFree must: be a pointer to a valid user-defined + pname:pfnFree must: be a valid pointer to a valid user-defined tlink:PFN_vkFreeFunction * [[VUID-VkAllocationCallbacks-pfnInternalAllocation-00635]] If either of pname:pfnInternalAllocation or pname:pfnInternalFree is not diff --git a/doc/specs/vulkan/chapters/pipelines.txt b/doc/specs/vulkan/chapters/pipelines.txt index d33f0ba0..f56d21b6 100644 --- a/doc/specs/vulkan/chapters/pipelines.txt +++ b/doc/specs/vulkan/chapters/pipelines.txt @@ -523,7 +523,7 @@ endif::VK_NV_glsl_shader[] * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]] If pname:pStages includes a tessellation control shader stage and a tessellation evaluation shader stage, pname:pTessellationState must: be - a pointer to a valid sname:VkPipelineTessellationStateCreateInfo + a valid pointer to a valid sname:VkPipelineTessellationStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]] If pname:pStages includes tessellation shader stages, the shader code of @@ -616,12 +616,12 @@ endif::VK_KHR_maintenance2[] * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]] If no element of the pname:pDynamicStates member of pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT, the pname:pViewports member of - pname:pViewportState must: be a pointer to an array of + pname:pViewportState must: be a valid pointer to an array of pname:pViewportState::pname:viewportCount sname:VkViewport structures * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]] If no element of the pname:pDynamicStates member of pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR, the pname:pScissors member of - pname:pViewportState must: be a pointer to an array of + pname:pViewportState must: be a valid pointer to an array of pname:pViewportState::pname:scissorCount sname:VkRect2D structures * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]] If the wide lines feature is not enabled, and no element of the @@ -630,21 +630,21 @@ endif::VK_KHR_maintenance2[] pname:pRasterizationState must: be `1.0` * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750]] If the pname:rasterizerDiscardEnable member of pname:pRasterizationState - is ename:VK_FALSE, pname:pViewportState must: be a pointer to a valid - sname:VkPipelineViewportStateCreateInfo structure + is ename:VK_FALSE, pname:pViewportState must: be a valid pointer to a + valid sname:VkPipelineViewportStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]] If the pname:rasterizerDiscardEnable member of pname:pRasterizationState - is ename:VK_FALSE, pname:pMultisampleState must: be a pointer to a valid - sname:VkPipelineMultisampleStateCreateInfo structure + is ename:VK_FALSE, pname:pMultisampleState must: be a valid pointer to a + valid sname:VkPipelineMultisampleStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00752]] If the pname:rasterizerDiscardEnable member of pname:pRasterizationState is ename:VK_FALSE, and pname:subpass uses a depth/stencil attachment, - pname:pDepthStencilState must: be a pointer to a valid + pname:pDepthStencilState must: be a valid pointer to a valid sname:VkPipelineDepthStencilStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00753]] If the pname:rasterizerDiscardEnable member of pname:pRasterizationState is ename:VK_FALSE, and pname:subpass uses color attachments, - pname:pColorBlendState must: be a pointer to a valid + pname:pColorBlendState must: be a valid pointer to a valid sname:VkPipelineColorBlendStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]] If the depth bias clamping feature is not enabled, no element of the @@ -1390,9 +1390,9 @@ slink:VkSpecializationMapEntry. The pname:size member of each element of pname:pMapEntries must: be less than or equal to pname:dataSize minus pname:offset * [[VUID-VkSpecializationInfo-mapEntryCount-00775]] - If pname:mapEntryCount is not `0`, pname:pMapEntries must: be a pointer - to an array of pname:mapEntryCount valid sname:VkSpecializationMapEntry - structures + If pname:mapEntryCount is not `0`, pname:pMapEntries must: be a valid + pointer to an array of pname:mapEntryCount valid + sname:VkSpecializationMapEntry structures **** include::../validity/structs/VkSpecializationInfo.txt[] diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt index 3879827e..da4a6419 100644 --- a/doc/specs/vulkan/chapters/renderpass.txt +++ b/doc/specs/vulkan/chapters/renderpass.txt @@ -1750,7 +1750,7 @@ pass. pname:stencilLoadOp, if the attachment has a depth/stencil format) of ename:VK_ATTACHMENT_LOAD_OP_CLEAR * [[VUID-VkRenderPassBeginInfo-clearValueCount-00903]] - If pname:clearValueCount is not `0`, pname:pClearValues must: be a + If pname:clearValueCount is not `0`, pname:pClearValues must: be a valid pointer to an array of pname:clearValueCount valid sname:VkClearValue unions * [[VUID-VkRenderPassBeginInfo-renderPass-00904]] diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt index 902ebc20..b83838ff 100644 --- a/doc/specs/vulkan/chapters/resources.txt +++ b/doc/specs/vulkan/chapters/resources.txt @@ -95,7 +95,7 @@ endif::editing-notes[] pname:size must: be greater than `0` * [[VUID-VkBufferCreateInfo-sharingMode-00913]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, - pname:pQueueFamilyIndices must: be a pointer to an array of + pname:pQueueFamilyIndices must: be a valid pointer to an array of pname:queueFamilyIndexCount basetype:uint32_t values * [[VUID-VkBufferCreateInfo-sharingMode-00914]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, @@ -602,7 +602,7 @@ endif::VK_KHR_maintenance2[] values passed to the corresponding parameters. * [[VUID-VkImageCreateInfo-sharingMode-00941]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, - pname:pQueueFamilyIndices must: be a pointer to an array of + pname:pQueueFamilyIndices must: be a valid pointer to an array of pname:queueFamilyIndexCount basetype:uint32_t values * [[VUID-VkImageCreateInfo-sharingMode-00942]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, diff --git a/doc/specs/vulkan/chapters/vertexpostproc.txt b/doc/specs/vulkan/chapters/vertexpostproc.txt index b5ee8e26..896f29e2 100644 --- a/doc/specs/vulkan/chapters/vertexpostproc.txt +++ b/doc/specs/vulkan/chapters/vertexpostproc.txt @@ -607,8 +607,8 @@ replace the current state for the viewport index [eq]#pname:firstViewport If the <> feature is not enabled, pname:viewportCount must: be `1` * [[VUID-vkCmdSetViewport-pViewports-01226]] - pname:pViewports must: be a pointer to an array of pname:viewportCount - valid sname:VkViewport structures + pname:pViewports must: be a valid pointer to an array of + pname:viewportCount valid sname:VkViewport structures **** include::../validity/protos/vkCmdSetViewport.txt[] diff --git a/src/spec/validitygenerator.py b/src/spec/validitygenerator.py index aefdb08d..69081233 100644 --- a/src/spec/validitygenerator.py +++ b/src/spec/validitygenerator.py @@ -348,9 +348,9 @@ class ValidityOutputGenerator(OutputGenerator): if (lengths[0]) == 'null-terminated': asciidoc += 'a null-terminated ' elif (lengths[0]) == '1': - asciidoc += 'a pointer to ' + asciidoc += 'a valid pointer to ' else: - asciidoc += 'a pointer to an array of ' + asciidoc += 'a valid pointer to an array of ' # Handle equations, which are currently denoted with latex if 'latexmath:' in lengths[0]: @@ -363,9 +363,9 @@ class ValidityOutputGenerator(OutputGenerator): if (length) == 'null-terminated': # This should always be the last thing. If it ever isn't for some bizarre reason, then this will need some massaging. asciidoc += 'null-terminated ' elif (length) == '1': - asciidoc += 'pointers to ' + asciidoc += 'valid pointers to ' else: - asciidoc += 'pointers to arrays of ' + asciidoc += 'valid pointers to arrays of ' # Handle equations, which are currently denoted with latex if 'latexmath:' in length: asciidoc += length @@ -416,7 +416,7 @@ class ValidityOutputGenerator(OutputGenerator): # Could be multi-level pointers (e.g. ppData - pointer to a pointer). Handle that. asciidoc += 'a ' for i in range(0, pointercount): - asciidoc += 'pointer to a ' + asciidoc += 'valid pointer to a ' # Handle void* and pointers to it if paramtype.text == 'void':