95 lines
3.7 KiB
Plaintext
95 lines
3.7 KiB
Plaintext
== 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
|
|
flink: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 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.
|
|
|
|
[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 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::{generated}/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
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties2.
|
|
|
|
--
|