summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJon Leech <devrel@oddhack.org>2017-10-26 16:19:38 -0700
committerGitHub <noreply@github.com>2017-10-26 16:19:38 -0700
commitebbc2b66d482a88055ddf06fbee5edebfdf906f7 (patch)
tree2539bc60d6bb2560482e128523c49d74b1da4324
parent38d4064bb4fb315eaa2bcec50b392f69e0cdc003 (diff)
parent4a45ecf5ccbed53cb1f00fecab4f5251bbad94f5 (diff)
downloadvulkan-spec-ebbc2b66d482a88055ddf06fbee5edebfdf906f7.zip
vulkan-spec-ebbc2b66d482a88055ddf06fbee5edebfdf906f7.tar.xz
Merge pull request #547 from krOoze/pointer_implicit_validity
Clarify pointer autovalidity and threading
-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 5109ba0..d101a15 100644
--- a/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
+++ b/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
@@ -303,7 +303,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 9bfc398..a6cff27 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 6fcedbe..d2dd2b9 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 6e14a1a..4827609 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 d92a07d..97e25bf 100644
--- a/doc/specs/vulkan/chapters/renderpass.txt
+++ b/doc/specs/vulkan/chapters/renderpass.txt
@@ -1753,7 +1753,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 4ab97c0..af9622b 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 962a791..7f2a35f 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':