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