From 4a45ecf5ccbed53cb1f00fecab4f5251bbad94f5 Mon Sep 17 00:00:00 2001 From: Petr Kraus Date: Mon, 11 Sep 2017 19:04:13 +0200 Subject: [PATCH] Clarify pointer autovalidity and threading 1) State more explicitly in implicit VUs if a "valid" pointer is required 2) For some time Implicit validity is quite explicit in implicit VU sections. Update pointer implicit validity chapter section as such. 3) Sometimes pointer parameter can be ignored. Update implicit pointer validity section as such. 4) Changeing to more forceful language, to clarify memory behind pointers need synchronizing too --- .../vulkan/chapters/VK_KHR_swapchain/wsi.txt | 2 +- doc/specs/vulkan/chapters/cmdbuffers.txt | 2 +- doc/specs/vulkan/chapters/descriptorsets.txt | 18 +++++------ doc/specs/vulkan/chapters/fragops.txt | 2 +- doc/specs/vulkan/chapters/fundamentals.txt | 32 +++++++++++++------ doc/specs/vulkan/chapters/memory.txt | 6 ++-- doc/specs/vulkan/chapters/pipelines.txt | 24 +++++++------- doc/specs/vulkan/chapters/renderpass.txt | 2 +- doc/specs/vulkan/chapters/resources.txt | 4 +-- doc/specs/vulkan/chapters/vertexpostproc.txt | 4 +-- src/spec/validitygenerator.py | 10 +++--- 11 files changed, 59 insertions(+), 47 deletions(-) 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':