Debugging

To aid developers in tracking down errors in the application’s use of Vulkan, particularly in combination with an external debugger or profiler, debugging extensions may be available.

VkObjectTypeSpecify an enumeration to track object handle types

If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter.

Debug Utilities

Vulkan provides flexible debugging utilities for debugging an application.

The Object Debug Annotation section describes how to associate either a name or binary data with a specific Vulkan object.

The Queue Labels section describes how to annotate and group the work submitted to a queue.

The Command Buffer Labels section describes how to associate logical elements of the scene with commands in a VkCommandBuffer.

The Debug Messengers section describes how to create debug messenger objects associated with an application supplied callback to capture debug messages from a variety of Vulkan components.

Object Debug Annotation

It can be useful for an application to provide its own content relative to a specific Vulkan object.

The following commands allow application developers to associate application-defined information with Vulkan objects. These commands are device-level commands but they may reference instance-level objects (such as VkInstance) and physical device-level objects (such as VkPhysicalDevice) with a few restrictions: * The data for the corresponding object may still be available after the VkDevice used in the corresponding API call to set it is destroyed, but access to this data is not guaranteed and should be avoided. * Subsequent calls to change the data of the same object across multiple VkDevice objects, may result in the data being changed to the most recent version for all VkDevice objects and not just the VkDevice used in the most recent API call.

Object Naming

vkSetDebugUtilsObjectNameEXTGive an application-defined name to an object
VkDebugUtilsObjectNameInfoEXTSpecify parameters of a name to give to an object

Object Data Association

In addition to setting a name for an object, debugging and validation layers may have uses for additional binary data on a per-object basis that have no other place in the Vulkan API.

For example, a VkShaderModule could have additional debugging data attached to it to aid in offline shader tracing.

Additional data can be attached to an object by calling vkSetDebugUtilsObjectTagEXT as defined below.

vkSetDebugUtilsObjectTagEXTAttach arbitrary data to an object
VkDebugUtilsObjectTagInfoEXTSpecify parameters of a tag to attach to an object

Queue Labels

All Vulkan work is submitted using queues. It is possible for an application to use multiple queues, each containing multiple command buffers, when performing work. It can be useful to identify which queue, or even where in a queue, something has occurred.

To begin identifying a region using a debug label inside a queue, you may use the vkQueueBeginDebugUtilsLabelEXT command.

Then, when the region of interest has passed, you may end the label region using vkQueueEndDebugUtilsLabelEXT.

Additionally, a single debug label may be inserted at any time using vkQueueInsertDebugUtilsLabelEXT.

vkQueueBeginDebugUtilsLabelEXTOpen a queue debug label region
VkDebugUtilsLabelEXTSpecify parameters of a label region
vkQueueEndDebugUtilsLabelEXTClose a queue debug label region
vkQueueInsertDebugUtilsLabelEXTInsert a label into a queue

Command Buffer Labels

Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.

To identify the beginning of a debug label region in a command buffer, vkCmdBeginDebugUtilsLabelEXT can be used as defined below.

To indicate the end of a debug label region in a command buffer, vkCmdEndDebugUtilsLabelEXT can be used.

To insert a single command buffer debug label inside of a command buffer, vkCmdInsertDebugUtilsLabelEXT can be used as defined below.

vkCmdBeginDebugUtilsLabelEXTOpen a command buffer debug label region
vkCmdEndDebugUtilsLabelEXTClose a command buffer label region
vkCmdInsertDebugUtilsLabelEXTInsert a label into a command buffer

Debug Messengers

Vulkan allows an application to register multiple callbacks with any Vulkan component wishing to report debug information. Some callbacks may log the information to a file, others may cause a debug break point or other application-defined behavior. A primary producer of callback messages are the validation layers. An application can register callbacks even when no validation layers are enabled, but they will only be called for the Vulkan loader and, if implemented, other layer and driver events.

VkDebugUtilsMessengerEXTOpaque handle to a debug messenger object
vkCreateDebugUtilsMessengerEXTCreate a debug messenger object
VkDebugUtilsMessengerCreateInfoEXTStructure specifying parameters of a newly created debug messenger
VkDebugUtilsMessengerCreateFlagsEXTReserved for future use
VkDebugUtilsMessageSeverityFlagBitsEXTBitmask specifying which severities of events cause a debug messenger callback
VkDebugUtilsMessageSeverityFlagsEXTBitmask of VkDebugUtilsMessageSeverityFlagBitsEXT
VkDebugUtilsMessageTypeFlagBitsEXTBitmask specifying which types of events cause a debug messenger callback
VkDebugUtilsMessageTypeFlagsEXTBitmask of VkDebugUtilsMessageTypeFlagBitsEXT
PFN_vkDebugUtilsMessengerCallbackEXTApplication-defined debug messenger callback function
VkDebugUtilsMessengerCallbackDataEXTStructure specifying parameters returned to the callback
VkDebugUtilsMessengerCallbackDataFlagsEXTReserved for future use
VkDeviceAddressBindingCallbackDataEXTStructure specifying parameters returned to the callback
VkDeviceAddressBindingFlagBitsEXTBitmask specifying the additional information about a binding event
VkDeviceAddressBindingFlagsEXTBitmask of VkDeviceAddressBindingFlagBitsEXT
VkDeviceAddressBindingTypeEXTEnum describing a change in device address bindings
vkSubmitDebugUtilsMessageEXTInject a message into a debug stream
vkDestroyDebugUtilsMessengerEXTDestroy a debug messenger object

Debug Markers

Debug markers provide a flexible way for debugging and validation layers to receive annotation and debug information.

The Object Annotation section describes how to associate a name or binary data with a Vulkan object.

The Command Buffer Markers section describes how to associate logical elements of the scene with commands in the command buffer.

Object Annotation

The commands in this section allow application developers to associate application-defined information with Vulkan objects at will.

vkDebugMarkerSetObjectNameEXTGive an application-defined name to an object
VkDebugMarkerObjectNameInfoEXTSpecify parameters of a name to give to an object
vkDebugMarkerSetObjectTagEXTAttach arbitrary data to an object
VkDebugMarkerObjectTagInfoEXTSpecify parameters of a tag to attach to an object

Command Buffer Markers

Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.

The marker commands vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT define regions of a series of commands that are grouped together, and they can be nested to create a hierarchy. The vkCmdDebugMarkerInsertEXT command allows insertion of a single label within a command buffer.

vkCmdDebugMarkerBeginEXTOpen a command buffer marker region
VkDebugMarkerMarkerInfoEXTSpecify parameters of a command buffer marker region
vkCmdDebugMarkerEndEXTClose a command buffer marker region
vkCmdDebugMarkerInsertEXTInsert a marker label into a command buffer

Debug Report Callbacks

VkDebugReportCallbackEXTOpaque handle to a debug report callback object
vkCreateDebugReportCallbackEXTCreate a debug report callback object
VkDebugReportCallbackCreateInfoEXTStructure specifying parameters of a newly created debug report callback
VkDebugReportFlagBitsEXTBitmask specifying events which cause a debug report callback
VkDebugReportFlagsEXTBitmask of VkDebugReportFlagBitsEXT
PFN_vkDebugReportCallbackEXTApplication-defined debug report callback function
VkDebugReportObjectTypeEXTSpecify the type of an object handle
vkDebugReportMessageEXTInject a message into a debug stream
vkDestroyDebugReportCallbackEXTDestroy a debug report callback object

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.

vkCmdSetCheckpointNVInsert diagnostic checkpoint in command stream

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

vkGetQueueCheckpointData2NVRetrieve diagnostic checkpoint data
VkCheckpointData2NVReturn structure for command buffer checkpoint data
vkGetQueueCheckpointDataNVRetrieve diagnostic checkpoint data
VkCheckpointDataNVReturn structure for command buffer checkpoint data

Device Fault Diagnosis

vkGetDeviceFaultInfoEXTReports diagnostic fault information on the specified logical device
VkDeviceFaultCountsEXTStructure specifying device fault information
VkDeviceFaultInfoEXTStructure specifying device fault information
VkDeviceFaultAddressInfoEXTStructure specifying GPU virtual address information
VkDeviceFaultAddressTypeEXTPage fault access types
VkDeviceFaultVendorInfoEXTStructure specifying vendor-specific fault information

Vendor Binary Crash Dumps

Applications can store the vendor-specific binary crash dump data retrieved by calling vkGetDeviceFaultInfoEXT for later analysis using external tools.

However, the format of this data may depend on the vendor ID, device ID, driver version, and other details of the device. To enable external applications to identify the original device from which a crash dump was generated, the initial bytes written to VkDeviceFaultInfoEXT::pVendorBinaryData must begin with a valid crash dump header.

VkDeviceFaultVendorBinaryHeaderVersionOneEXTStructure describing the layout of the vendor binary crash dump header
VkDeviceFaultVendorBinaryHeaderVersionEXTEncode vendor binary crash dump version

Active Tooling Information

vkGetPhysicalDeviceToolPropertiesReports properties of tools active on the specified physical device
VkPhysicalDeviceToolPropertiesStructure providing information about an active tool
VkToolPurposeFlagBitsBitmask specifying the purposes of an active tool
VkToolPurposeFlagsBitmask of VkToolPurposeFlagBits

Frame Boundary

VkFrameBoundaryEXTAdd frame boundary information to queue submissions
VkFrameBoundaryFlagBitsEXTBitmask specifying whether a queue submission is the last one for a given frame

Note that in the presence of timeline semaphores, the last queue submission might not be the last one to be submitted, as timeline semaphores allow for wait-before-signal submissions. In the context of frame boundary, the queue submission that should be done flagged as the last one is the one that is meant to be executed last, even if it may not be the last one to be submitted.

VkFrameBoundaryFlagsEXTBitmask of VkFrameBoundaryFlagBitsEXT