status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
This commit is contained in:
Petr Kraus 2017-09-11 19:04:13 +02:00
parent 52d809dd04
commit 4a45ecf5cc
11 changed files with 59 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
View File

@ -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,

2
doc/specs/vulkan/chapters/cmdbuffers.txt
View File

@ -504,7 +504,7 @@ recorded into it, becomes <<commandbuffers-lifecycle, invalid>>.
All elements of pname:pCommandBuffers must: not be in the
<<commandbuffers-lifecycle, pending state>>
* [[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`
****

18
doc/specs/vulkan/chapters/descriptorsets.txt
View File

@ -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

2
doc/specs/vulkan/chapters/fragops.txt
View File

@ -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:

32
doc/specs/vulkan/chapters/fundamentals.txt
View File

@ -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
<<fundamentals-objectmodel-lifetime-acquire,ownership temporarily acquired>>
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

6
doc/specs/vulkan/chapters/memory.txt
View File

@ -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

24
doc/specs/vulkan/chapters/pipelines.txt
View File

@ -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[]

2
doc/specs/vulkan/chapters/renderpass.txt
View File

@ -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]]

4
doc/specs/vulkan/chapters/resources.txt
View File

@ -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,

4
doc/specs/vulkan/chapters/vertexpostproc.txt
View File

@ -607,8 +607,8 @@ replace the current state for the viewport index [eq]#pname:firstViewport
If the <<features-features-multiViewport,multiple viewports>> 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[]

10
src/spec/validitygenerator.py
View File

@ -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':