summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPetr Kraus <petr_kraus@email.cz>2017-09-11 19:04:13 +0200
committerPetr Kraus <petr_kraus@email.cz>2017-10-14 02:42:50 +0200
commit4a45ecf5ccbed53cb1f00fecab4f5251bbad94f5 (patch)
treef95dc500ad3d78f9f3f5e0b47acf27963640368a
parent52d809dd04be4b063adb715eb5a2114e30a9f6d4 (diff)
downloadvulkan-spec-4a45ecf5ccbed53cb1f00fecab4f5251bbad94f5.zip
vulkan-spec-4a45ecf5ccbed53cb1f00fecab4f5251bbad94f5.tar.xz
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
-rw-r--r--doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt2
-rw-r--r--doc/specs/vulkan/chapters/cmdbuffers.txt2
-rw-r--r--doc/specs/vulkan/chapters/descriptorsets.txt18
-rw-r--r--doc/specs/vulkan/chapters/fragops.txt2
-rw-r--r--doc/specs/vulkan/chapters/fundamentals.txt32
-rw-r--r--doc/specs/vulkan/chapters/memory.txt6
-rw-r--r--doc/specs/vulkan/chapters/pipelines.txt24
-rw-r--r--doc/specs/vulkan/chapters/renderpass.txt2
-rw-r--r--doc/specs/vulkan/chapters/resources.txt4
-rw-r--r--doc/specs/vulkan/chapters/vertexpostproc.txt4
-rw-r--r--src/spec/validitygenerator.py10
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 b61c440..8727ed1 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 f4bdf6f..88fb9ed 100644
--- a/doc/specs/vulkan/chapters/cmdbuffers.txt
+++ b/doc/specs/vulkan/chapters/cmdbuffers.txt
@@ -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`
****
diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt
index 0457e75..302becc 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 771fa5c..30b87d3 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 dddc4a3..cd3698a 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
+<<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
diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt
index 61a724e..dba2379 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 d33f0ba..f56d21b 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 3879827..da4a641 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 902ebc2..b83838f 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 b5ee8e2..896f29e 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 <<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[]
diff --git a/src/spec/validitygenerator.py b/src/spec/validitygenerator.py
index aefdb08..6908123 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':