// Copyright (c) 2014-2020 Khronos Group.
//
// SPDX-License-Identifier: CC-BY-4.0

[[copies-object_refreshes]]
== Object Refreshes

Safety critical applications may: need to contend with single event upsets
(SEUs).
For a Vulkan object explicitly backed by device memory, such as a
sname:VkImage or sname:VkBuffer, an application can: bind its backing memory
to a SEU-safe heap with the ename:VK_MEMORY_HEAP_SEU_SAFE_BIT bit set.
Alternatively, an application can: also periodically reload the non-SEU-safe
device memory contents from a known SEU-safe portion of host memory, or
otherwise periodically regenerate or refresh the contents of non-SEU-safe
device memory.

However, an implementation may: store implementation-specific internal
object data in non-SEU-safe memory, and Base Vulkan provides no method to
determine which object types this applies to or how to refresh their data.
An application can: query the list of object types that have implementation
internal object data stored in non-SEU-safe memory using
flink:vkGetPhysicalDeviceRefreshableObjectTypesKHR, and can: instruct the
implementation to refresh the internal data of specific objects from a
backup in SEU-safe memory using the fname:vkCmdRefreshObjectsKHR command.

[open,refpage='vkCmdRefreshObjectsKHR',desc='Execute a pipelined refresh of a list of objects',type='protos']
--
To refresh a list of objects as a pipelined operation, call:

include::{generated}/api/protos/vkCmdRefreshObjectsKHR.adoc[]

  * pname:commandBuffer is the command buffer into which the command will be
    recorded.
  * pname:pRefreshObjects is a pointer to a slink:VkRefreshObjectListKHR
    structure specifying the list of objects to refresh.

The access scope for object refreshes falls under the
ename:VK_ACCESS_TRANSFER_WRITE_BIT, and the pipeline stages for identifying
the synchronization scope must: include
ename:VK_PIPELINE_STAGE_TRANSFER_BIT.

[NOTE]
.Note
====
If an implementation does not store a supplied object's internal data in
SEU-susceptible memory, it may: ignore the refresh command for that object.
====

include::{generated}/validity/protos/vkCmdRefreshObjectsKHR.adoc[]
--

[open,refpage='VkRefreshObjectListKHR',desc='Structure specifying a list of objects to refresh',type='structs']
--
The sname:VkRefreshObjectListKHR structure is defined as:

include::{generated}/api/structs/VkRefreshObjectListKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:objectCount is the number of objects to refresh.
  * pname:pObjects is a pointer to an array of slink:VkRefreshObjectKHR
    structures, defining the objects to refresh.

include::{generated}/validity/structs/VkRefreshObjectListKHR.adoc[]
--

[open,refpage='VkRefreshObjectKHR',desc='Structure specifying an object to refresh',type='structs']
--
The sname:VkRefreshObjectKHR structure is defined as:

include::{generated}/api/structs/VkRefreshObjectKHR.adoc[]

  * pname:objectType is a elink:VkObjectType specifying the type of the
    object to refresh.
  * pname:objectHandle is the object to refresh.
  * pname:flags is a bitmask of tlink:VkRefreshObjectFlagsKHR.

.Valid Usage
****
  * [[VUID-VkRefreshObjectKHR-objectHandle-05069]]
    pname:objectHandle must: be a valid Vulkan handle of the type associated
    with pname:objectType as defined in the <<debugging-object-types,
    VkObjectType and Vulkan Handle Relationship>> table
  * [[VUID-VkRefreshObjectKHR-objectType-05070]]
    pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN
****

include::{generated}/validity/structs/VkRefreshObjectKHR.adoc[]
--

[open,refpage='VkRefreshObjectFlagBitsKHR',desc='Reserved for future use',type='enums',xrefs='VkRefreshObjectKHR']
--
include::{generated}/api/enums/VkRefreshObjectFlagBitsKHR.adoc[]
--

[open,refpage='VkRefreshObjectFlagsKHR',desc='Reserved for future use',type='flags',xrefs='VkRefreshObjectKHR']
--
include::{generated}/api/flags/VkRefreshObjectFlagsKHR.adoc[]

tlink:VkRefreshObjectFlagsKHR is a bitmask type for setting a mask, but is
currently reserved for future use.
--