// Copyright (c) 2018-2020 NVIDIA Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

== Device Loss Debugging


[[device-diagnostic-checkpoints]]
=== Device Diagnostic Checkpoints

Device execution progress can: be tracked for the purposes of debugging a
device loss by annotating the command stream with application-defined
diagnostic checkpoints.

[open,refpage='vkCmdSetCheckpointNV',desc='Insert diagnostic checkpoint in command stream',type='protos']
--
Device diagnostic checkpoints are inserted into the command stream by
calling flink:vkCmdSetCheckpointNV.

include::{generated}/api/protos/vkCmdSetCheckpointNV.txt[]

  * pname:commandBuffer is the command buffer that will receive the marker
  * pname:pCheckpointMarker is an opaque application-provided value that
    will be associated with the checkpoint.

include::{generated}/validity/protos/vkCmdSetCheckpointNV.txt[]
--

Note that pname:pCheckpointMarker is treated as an opaque value.
It does not need to be a valid pointer and will not be dereferenced by the
implementation.

ifdef::VK_KHR_synchronization2[]
[open,refpage='vkGetQueueCheckpointData2NV',desc='Retrieve diagnostic checkpoint data',type='protos']
--
If the device encounters an error during execution, the implementation will
return a ename:VK_ERROR_DEVICE_LOST error to the application at some point
during host execution.
When this happens, the application can: call
flink:vkGetQueueCheckpointData2NV to retrieve information on the most recent
diagnostic checkpoints that were executed by the device.

include::{generated}/api/protos/vkGetQueueCheckpointData2NV.txt[]

  * pname:queue is the slink:VkQueue object the caller would like to
    retrieve checkpoint data for
  * pname:pCheckpointDataCount is a pointer to an integer related to the
    number of checkpoint markers available or queried, as described below.
  * pname:pCheckpointData is either `NULL` or a pointer to an array of
    sname:VkCheckpointData2NV structures.

If pname:pCheckpointData is `NULL`, then the number of checkpoint markers
available is returned in pname:pCheckpointDataCount.
Otherwise, pname:pCheckpointDataCount must: point to a variable set by the
user to the number of elements in the pname:pCheckpointData array, and on
return the variable is overwritten with the number of structures actually
written to pname:pCheckpointData.

If pname:pCheckpointDataCount is less than the number of checkpoint markers
available, at most pname:pCheckpointDataCount structures will be written.

.Valid Usage
****
  * [[VUID-vkGetQueueCheckpointData2NV-queue-03892]]
    The device that pname:queue belongs to must: be in the lost state
****

include::{generated}/validity/protos/vkGetQueueCheckpointData2NV.txt[]
--

[open,refpage='VkCheckpointData2NV',desc='Return structure for command buffer checkpoint data',type='structs']
--
The slink:VkCheckpointData2NV structure is defined as:

include::{generated}/api/structs/VkCheckpointData2NV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:stage indicates a single pipeline stage which the checkpoint
    marker data refers to.
  * pname:pCheckpointMarker contains the value of the last checkpoint marker
    executed in the stage that pname:stage refers to.

include::{generated}/validity/structs/VkCheckpointData2NV.txt[]

The stages at which a checkpoint marker can: be executed are
implementation-defined and can: be queried by calling
flink:vkGetPhysicalDeviceQueueFamilyProperties2.
--
endif::VK_KHR_synchronization2[]

[open,refpage='vkGetQueueCheckpointDataNV',desc='Retrieve diagnostic checkpoint data',type='protos']
--
If the device encounters an error during execution, the implementation will
return a ename:VK_ERROR_DEVICE_LOST error to the application at a certain
point during host execution.
When this happens, the application can: call
flink:vkGetQueueCheckpointDataNV to retrieve information on the most recent
diagnostic checkpoints that were executed by the device.

include::{generated}/api/protos/vkGetQueueCheckpointDataNV.txt[]

  * pname:queue is the slink:VkQueue object the caller would like to
    retrieve checkpoint data for
  * pname:pCheckpointDataCount is a pointer to an integer related to the
    number of checkpoint markers available or queried, as described below.
  * pname:pCheckpointData is either `NULL` or a pointer to an array of
    sname:VkCheckpointDataNV structures.

If pname:pCheckpointData is `NULL`, then the number of checkpoint markers
available is returned in pname:pCheckpointDataCount.

Otherwise, pname:pCheckpointDataCount must: point to a variable set by the
user to the number of elements in the pname:pCheckpointData array, and on
return the variable is overwritten with the number of structures actually
written to pname:pCheckpointData.

If pname:pCheckpointDataCount is less than the number of checkpoint markers
available, at most pname:pCheckpointDataCount structures will be written.

.Valid Usage
****
  * [[VUID-vkGetQueueCheckpointDataNV-queue-02025]]
    The device that pname:queue belongs to must: be in the lost state
****

include::{generated}/validity/protos/vkGetQueueCheckpointDataNV.txt[]
--

[open,refpage='VkCheckpointDataNV',desc='Return structure for command buffer checkpoint data',type='structs']
--
The slink:VkCheckpointDataNV structure is defined as:

include::{generated}/api/structs/VkCheckpointDataNV.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:stage is a ename:VkPipelineStageFlagBits value specifying which
    pipeline stage the checkpoint marker data refers to.
  * pname:pCheckpointMarker contains the value of the last checkpoint marker
    executed in the stage that pname:stage refers to.

The stages at which a checkpoint marker can: be executed are
implementation-defined and can: be queried by calling
flink:vkGetPhysicalDeviceQueueFamilyProperties2.

include::{generated}/validity/structs/VkCheckpointDataNV.txt[]
--