| // 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[] |
| -- |
