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