1// Copyright (c) 2014-2020 Khronos Group.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[copies-object_refreshes]]
6== Object Refreshes
7
8Safety critical applications may: need to contend with single event upsets
9(SEUs).
10For a Vulkan object explicitly backed by device memory, such as a
11sname:VkImage or sname:VkBuffer, an application can: bind its backing memory
12to a SEU-safe heap with the ename:VK_MEMORY_HEAP_SEU_SAFE_BIT bit set.
13Alternatively, an application can: also periodically reload the non-SEU-safe
14device memory contents from a known SEU-safe portion of host memory, or
15otherwise periodically regenerate or refresh the contents of non-SEU-safe
16device memory.
17
18However, an implementation may: store implementation-specific internal
19object data in non-SEU-safe memory, and Base Vulkan provides no method to
20determine which object types this applies to or how to refresh their data.
21An application can: query the list of object types that have implementation
22internal object data stored in non-SEU-safe memory using
23flink:vkGetPhysicalDeviceRefreshableObjectTypesKHR, and can: instruct the
24implementation to refresh the internal data of specific objects from a
25backup in SEU-safe memory using the fname:vkCmdRefreshObjectsKHR command.
26
27[open,refpage='vkCmdRefreshObjectsKHR',desc='Execute a pipelined refresh of a list of objects',type='protos']
28--
29To refresh a list of objects as a pipelined operation, call:
30
31include::{generated}/api/protos/vkCmdRefreshObjectsKHR.adoc[]
32
33  * pname:commandBuffer is the command buffer into which the command will be
34    recorded.
35  * pname:pRefreshObjects is a pointer to a slink:VkRefreshObjectListKHR
36    structure specifying the list of objects to refresh.
37
38The access scope for object refreshes falls under the
39ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
40the synchronization scope must: include
41ename:VK_PIPELINE_STAGE_TRANSFER_BIT.
42
43[NOTE]
44.Note
45====
46If an implementation does not store a supplied object's internal data in
47SEU-susceptible memory, it may: ignore the refresh command for that object.
48====
49
50include::{generated}/validity/protos/vkCmdRefreshObjectsKHR.adoc[]
51--
52
53[open,refpage='VkRefreshObjectListKHR',desc='Structure specifying a list of objects to refresh',type='structs']
54--
55The sname:VkRefreshObjectListKHR structure is defined as:
56
57include::{generated}/api/structs/VkRefreshObjectListKHR.adoc[]
58
59  * pname:sType is a elink:VkStructureType value identifying this structure.
60  * pname:pNext is `NULL` or a pointer to a structure extending this
61    structure.
62  * pname:objectCount is the number of objects to refresh.
63  * pname:pObjects is a pointer to an array of slink:VkRefreshObjectKHR
64    structures, defining the objects to refresh.
65
66include::{generated}/validity/structs/VkRefreshObjectListKHR.adoc[]
67--
68
69[open,refpage='VkRefreshObjectKHR',desc='Structure specifying an object to refresh',type='structs']
70--
71The sname:VkRefreshObjectKHR structure is defined as:
72
73include::{generated}/api/structs/VkRefreshObjectKHR.adoc[]
74
75  * pname:objectType is a elink:VkObjectType specifying the type of the
76    object to refresh.
77  * pname:objectHandle is the object to refresh.
78  * pname:flags is a bitmask of tlink:VkRefreshObjectFlagsKHR.
79
80.Valid Usage
81****
82  * [[VUID-VkRefreshObjectKHR-objectHandle-05069]]
83    pname:objectHandle must: be a valid Vulkan handle of the type associated
84    with pname:objectType as defined in the <<debugging-object-types,
85    VkObjectType and Vulkan Handle Relationship>> table
86  * [[VUID-VkRefreshObjectKHR-objectType-05070]]
87    pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN
88****
89
90include::{generated}/validity/structs/VkRefreshObjectKHR.adoc[]
91--
92
93[open,refpage='VkRefreshObjectFlagBitsKHR',desc='Reserved for future use',type='enums',xrefs='VkRefreshObjectKHR']
94--
95include::{generated}/api/enums/VkRefreshObjectFlagBitsKHR.adoc[]
96--
97
98[open,refpage='VkRefreshObjectFlagsKHR',desc='Reserved for future use',type='flags',xrefs='VkRefreshObjectKHR']
99--
100include::{generated}/api/flags/VkRefreshObjectFlagsKHR.adoc[]
101
102tlink:VkRefreshObjectFlagsKHR is a bitmask type for setting a mask, but is
103currently reserved for future use.
104--
105