== Device Loss Debugging

=== 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.

Each diagnostic checkpoint command is executed at two pipeline stages:
ename:VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, and
ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.
If the device is lost, the application can: call
slink:vkGetQueueCheckpointDataNV to retrieve checkpoint data associated with
both pipeline stages, indicating the range of diagnostic checkpoints that
are currently in the execution pipeline on the device.

[open,refpage='vkCmdSetCheckpointNV',desc='insert diagnostic checkpoint in command stream',type='protos']
--

Device diagnostic checkpoints are inserted into the command stream by
calling slink:vkCmdSetCheckpointNV.

include::../../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::../../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.

[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
slink:vkGetQueueCheckpointDataNV to retrieve information on the most recent
diagnostic checkpoints that were executed by the device.

include::../../api/protos/vkGetQueueCheckpointDataNV.txt[]

  * pname:queue is the elink: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::../../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::../../api/structs/VkCheckpointDataNV.txt[]

  * pname:sType is the type of this structure
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:stage indicates 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.

include::../../validity/structs/VkCheckpointDataNV.txt[]

Note that the stages at which a checkpoint marker can: be executed are
implementation-defined and can: be queried by calling
slink:vkGetPhysicalDeviceQueueFamilyProperties2.

--