1// Copyright 2015-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[debugging]] 6= Debugging 7 8To aid developers in tracking down errors in the application's use of 9Vulkan, particularly in combination with an external debugger or profiler, 10_debugging extensions_ may be available. 11 12[open,refpage='VkObjectType',desc='Specify an enumeration to track object handle types',type='enums'] 13-- 14The elink:VkObjectType enumeration defines values, each of which corresponds 15to a specific Vulkan handle type. 16These values can: be used to associate debug information with a particular 17type of object through one or more extensions. 18 19include::{generated}/api/enums/VkObjectType.adoc[] 20 21[[debugging-object-types]] 22.`VkObjectType` and Vulkan Handle Relationship 23[width="80%",cols="<35,<23",options="header"] 24|==== 25| elink:VkObjectType | Vulkan Handle Type 26| ename:VK_OBJECT_TYPE_UNKNOWN | Unknown/Undefined Handle 27| ename:VK_OBJECT_TYPE_INSTANCE | slink:VkInstance 28| ename:VK_OBJECT_TYPE_PHYSICAL_DEVICE | slink:VkPhysicalDevice 29| ename:VK_OBJECT_TYPE_DEVICE | slink:VkDevice 30| ename:VK_OBJECT_TYPE_QUEUE | slink:VkQueue 31| ename:VK_OBJECT_TYPE_SEMAPHORE | slink:VkSemaphore 32| ename:VK_OBJECT_TYPE_COMMAND_BUFFER | slink:VkCommandBuffer 33| ename:VK_OBJECT_TYPE_FENCE | slink:VkFence 34| ename:VK_OBJECT_TYPE_DEVICE_MEMORY | slink:VkDeviceMemory 35| ename:VK_OBJECT_TYPE_BUFFER | slink:VkBuffer 36| ename:VK_OBJECT_TYPE_IMAGE | slink:VkImage 37| ename:VK_OBJECT_TYPE_EVENT | slink:VkEvent 38| ename:VK_OBJECT_TYPE_QUERY_POOL | slink:VkQueryPool 39| ename:VK_OBJECT_TYPE_BUFFER_VIEW | slink:VkBufferView 40| ename:VK_OBJECT_TYPE_IMAGE_VIEW | slink:VkImageView 41ifndef::VKSC_VERSION_1_0[] 42| ename:VK_OBJECT_TYPE_SHADER_MODULE | slink:VkShaderModule 43endif::VKSC_VERSION_1_0[] 44| ename:VK_OBJECT_TYPE_PIPELINE_CACHE | slink:VkPipelineCache 45| ename:VK_OBJECT_TYPE_PIPELINE_LAYOUT | slink:VkPipelineLayout 46| ename:VK_OBJECT_TYPE_RENDER_PASS | slink:VkRenderPass 47| ename:VK_OBJECT_TYPE_PIPELINE | slink:VkPipeline 48| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT | slink:VkDescriptorSetLayout 49| ename:VK_OBJECT_TYPE_SAMPLER | slink:VkSampler 50| ename:VK_OBJECT_TYPE_DESCRIPTOR_POOL | slink:VkDescriptorPool 51| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET | slink:VkDescriptorSet 52| ename:VK_OBJECT_TYPE_FRAMEBUFFER | slink:VkFramebuffer 53| ename:VK_OBJECT_TYPE_COMMAND_POOL | slink:VkCommandPool 54ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 55| ename:VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION | slink:VkSamplerYcbcrConversion 56endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 57ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 58ifndef::VKSC_VERSION_1_0[] 59| ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE | slink:VkDescriptorUpdateTemplate 60endif::VKSC_VERSION_1_0[] 61endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 62ifdef::VK_VERSION_1_3,VK_EXT_private_data[] 63| ename:VK_OBJECT_TYPE_PRIVATE_DATA_SLOT | slink:VkPrivateDataSlot 64endif::VK_VERSION_1_3,VK_EXT_private_data[] 65ifdef::VK_KHR_surface[] 66| ename:VK_OBJECT_TYPE_SURFACE_KHR | slink:VkSurfaceKHR 67endif::VK_KHR_surface[] 68ifdef::VK_KHR_swapchain[] 69| ename:VK_OBJECT_TYPE_SWAPCHAIN_KHR | slink:VkSwapchainKHR 70endif::VK_KHR_swapchain[] 71ifdef::VK_KHR_display[] 72| ename:VK_OBJECT_TYPE_DISPLAY_KHR | slink:VkDisplayKHR 73| ename:VK_OBJECT_TYPE_DISPLAY_MODE_KHR | slink:VkDisplayModeKHR 74endif::VK_KHR_display[] 75ifdef::VK_EXT_debug_report[] 76| ename:VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT | slink:VkDebugReportCallbackEXT 77endif::VK_EXT_debug_report[] 78ifdef::VK_KHR_video_queue[] 79| ename:VK_OBJECT_TYPE_VIDEO_SESSION_KHR | slink:VkVideoSessionKHR 80| ename:VK_OBJECT_TYPE_VIDEO_SESSION_PARAMETERS_KHR | slink:VkVideoSessionParametersKHR 81endif::VK_KHR_video_queue[] 82ifdef::VK_EXT_debug_utils[] 83| ename:VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT | slink:VkDebugUtilsMessengerEXT 84endif::VK_EXT_debug_utils[] 85ifdef::VK_KHR_acceleration_structure[] 86| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR | slink:VkAccelerationStructureKHR 87endif::VK_KHR_acceleration_structure[] 88ifdef::VK_EXT_validation_cache[] 89| ename:VK_OBJECT_TYPE_VALIDATION_CACHE_EXT | slink:VkValidationCacheEXT 90endif::VK_EXT_validation_cache[] 91ifdef::VK_NV_ray_tracing[] 92| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV | slink:VkAccelerationStructureNV 93endif::VK_NV_ray_tracing[] 94ifdef::VK_INTEL_performance_query[] 95| ename:VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL | slink:VkPerformanceConfigurationINTEL 96endif::VK_INTEL_performance_query[] 97ifdef::VK_KHR_deferred_host_operations[] 98| ename:VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR | slink:VkDeferredOperationKHR 99endif::VK_KHR_deferred_host_operations[] 100ifdef::VK_NV_device_generated_commands[] 101| ename:VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NV | slink:VkIndirectCommandsLayoutNV 102endif::VK_NV_device_generated_commands[] 103ifdef::VK_FUCHSIA_buffer_collection[] 104| ename:VK_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA | slink:VkBufferCollectionFUCHSIA 105endif::VK_FUCHSIA_buffer_collection[] 106ifdef::VK_EXT_opacity_micromap[] 107| ename:VK_OBJECT_TYPE_MICROMAP_EXT | slink:VkMicromapEXT 108endif::VK_EXT_opacity_micromap[] 109ifdef::VK_NV_optical_flow[] 110| ename:VK_OBJECT_TYPE_OPTICAL_FLOW_SESSION_NV | slink:VkOpticalFlowSessionNV 111endif::VK_NV_optical_flow[] 112ifdef::VK_EXT_shader_object[] 113| ename:VK_OBJECT_TYPE_SHADER_EXT | slink:VkShaderEXT 114endif::VK_EXT_shader_object[] 115|==== 116-- 117 118If this Specification was generated with any such extensions included, they 119will be described in the remainder of this chapter. 120 121ifdef::VK_EXT_debug_utils[] 122include::{chapters}/VK_EXT_debug_utils.adoc[] 123endif::VK_EXT_debug_utils[] 124 125ifdef::VK_EXT_debug_marker[] 126include::{chapters}/VK_EXT_debug_marker.adoc[] 127endif::VK_EXT_debug_marker[] 128 129ifdef::VK_EXT_debug_report[] 130include::{chapters}/VK_EXT_debug_report.adoc[] 131endif::VK_EXT_debug_report[] 132 133ifdef::VK_NV_device_diagnostic_checkpoints,VK_EXT_device_fault[] 134== Device Loss Debugging 135endif::VK_NV_device_diagnostic_checkpoints,VK_EXT_device_fault[] 136 137ifdef::VK_NV_device_diagnostic_checkpoints[] 138include::{chapters}/VK_NV_device_diagnostic_checkpoints/device_diagnostic_checkpoints.adoc[] 139endif::VK_NV_device_diagnostic_checkpoints[] 140 141ifdef::VKSC_VERSION_1_0[] 142include::{chapters}/fault_handling.adoc[] 143endif::VKSC_VERSION_1_0[] 144 145ifdef::VK_EXT_device_fault[] 146=== Device Fault Diagnosis 147 148[open,refpage='vkGetDeviceFaultInfoEXT',desc='Reports diagnostic fault information on the specified logical device',type='protos'] 149-- 150To retrieve diagnostic information about faults that may: have caused device 151loss, call: 152 153include::{generated}/api/protos/vkGetDeviceFaultInfoEXT.adoc[] 154 155 * pname:device is the logical device from which to query the diagnostic 156 fault information. 157 * pname:pFaultCounts is a pointer to a slink:VkDeviceFaultCountsEXT 158 structure in which counts for structures describing additional fault 159 information are returned. 160 * pname:pFaultInfo is `NULL` or a pointer to a slink:VkDeviceFaultInfoEXT 161 structure in which fault information is returned. 162 163If pname:pFaultInfo is `NULL`, then the counts of corresponding additional 164fault information structures available are returned in the 165pname:addressInfoCount and pname:vendorInfoCount members of 166pname:pFaultCounts. 167Additionally, the size of any vendor-specific binary crash dump is returned 168in the pname:vendorBinarySize member of pname:pFaultCounts. 169 170If pname:pFaultInfo is not `NULL`, pname:pFaultCounts must: point to a 171slink:VkDeviceFaultCountsEXT structure with each structure count or size 172member (pname:addressInfoCount, pname:vendorInfoCount, 173pname:vendorBinarySize) set by the user to the number of elements in the 174corresponding output array member of pname:pFaultInfo (pname:pAddressInfos 175and pname:pVendorInfos), or to the size of the output buffer in bytes 176(pname:pVendorBinaryData). 177On return, each structure count member is overwritten with the number of 178structures actually written to the corresponding output array member of 179pname:pFaultInfo. 180Similarly, pname:vendorBinarySize is overwritten with the number of bytes 181actually written to the pname:pVendorBinaryData member of pname:pFaultInfo. 182 183If the <<features-deviceFaultVendorBinary, vendor-specific crash dumps>> 184feature is not enabled, then implementations must: set 185pname:pFaultCounts\->vendorBinarySize to zero and must: not modify 186pname:pFaultInfo\->pVendorBinaryData. 187 188If any pname:pFaultCounts structure count member is less than the number of 189corresponding fault properties available, at most structure count 190(pname:addressInfoCount, pname:vendorInfoCount) elements will be written to 191the associated pname:pFaultInfo output array. 192Similarly, if pname:vendorBinarySize is less than the size in bytes of the 193available crash dump data, at most pname:vendorBinarySize elements will be 194written to pname:pVendorBinaryData. 195 196If pname:pFaultInfo is `NULL`, then subsequent calls to 197flink:vkGetDeviceFaultInfoEXT for the same pname:device must: return 198identical values in the pname:addressInfoCount, pname:vendorInfoCount and 199pname:vendorBinarySize members of pname:pFaultCounts. 200 201If pname:pFaultInfo is not `NULL`, then subsequent calls to 202flink:vkGetDeviceFaultInfoEXT for the same pname:device must: return 203identical values in the output members of pname:pFaultInfo 204(pname:pAddressInfos, pname:pVendorInfos, pname:pVendorBinaryData), up to 205the limits described by the structure count and buffer size members of 206pname:pFaultCounts (pname:addressInfoCount, pname:vendorInfoCount, 207pname:vendorBinarySize). 208If the sizes of the output members of pname:pFaultInfo increase for a 209subsequent call to flink:vkGetDeviceFaultInfoEXT, then supplementary 210information may: be returned in the additional available space. 211 212If any pname:pFaultCounts structure count member is smaller than the number 213of corresponding fault properties available, or if 214pname:pFaultCounts\->vendorBinarySize is smaller than the size in bytes of 215the generated binary crash dump data, ename:VK_INCOMPLETE will be returned 216instead of ename:VK_SUCCESS, to indicate that not all the available 217properties were returned. 218 219If pname:pFaultCounts\->vendorBinarySize is less than what is necessary to 220store the <<vendor-binary-crash-dumps, binary crash dump header>>, nothing 221will be written to pname:pFaultInfo\->pVendorBinaryData and zero will be 222written to pname:pFaultCounts\->vendorBinarySize. 223 224.Valid Usage 225**** 226 * [[VUID-vkGetDeviceFaultInfoEXT-device-07336]] 227 pname:device must: be in the _lost_ state 228 * [[VUID-vkGetDeviceFaultInfoEXT-pFaultCounts-07337]] 229 If the value referenced by pname:pFaultCounts->addressInfoCount is not 230 `0`, and pname:pFaultInfo->pAddressInfos is not `NULL`, 231 pname:pFaultInfo->pAddressInfos must be a valid pointer to an array of 232 pname:pFaultCounts->addressInfoCount slink:VkDeviceFaultAddressInfoEXT 233 structures 234 * [[VUID-vkGetDeviceFaultInfoEXT-pFaultCounts-07338]] 235 If the value referenced by pname:pFaultCounts->vendorInfoCount is not 236 `0`, and pname:pFaultInfo->pVendorInfos is not `NULL`, 237 pname:pFaultInfo->pVendorInfos must be a valid pointer to an array of 238 pname:pFaultCounts->vendorInfoCount slink:VkDeviceFaultVendorInfoEXT 239 structures 240 * [[VUID-vkGetDeviceFaultInfoEXT-pFaultCounts-07339]] 241 If the value referenced by pname:pFaultCounts->vendorBinarySize is not 242 `0`, and pname:pFaultInfo->pVendorBinaryData is not `NULL`, 243 pname:pFaultInfo->pVendorBinaryData must be a valid pointer to an array 244 of pname:pFaultCounts->vendorBinarySize bytes 245**** 246 247include::{generated}/validity/protos/vkGetDeviceFaultInfoEXT.adoc[] 248-- 249 250[open,refpage='VkDeviceFaultCountsEXT',desc='Structure specifying device fault information',type='structs'] 251-- 252The sname:VkDeviceFaultCountsEXT structure is defined as: 253 254include::{generated}/api/structs/VkDeviceFaultCountsEXT.adoc[] 255 256 * pname:sType is a elink:VkStructureType value identifying this structure. 257 * pname:pNext is `NULL` or a pointer to a structure extending this 258 structure. 259 * pname:addressInfoCount is the number of 260 slink:VkDeviceFaultAddressInfoEXT structures describing either memory 261 accesses which may: have caused a page fault, or the addresses of active 262 instructions at the time of the fault. 263 * pname:vendorInfoCount is the number of slink:VkDeviceFaultVendorInfoEXT 264 structures describing vendor-specific fault information. 265 * pname:vendorBinarySize is the size in bytes of a vendor-specific binary 266 crash dump, which may provide additional information when imported into 267 external tools. 268 269include::{generated}/validity/structs/VkDeviceFaultCountsEXT.adoc[] 270-- 271 272[open,refpage='VkDeviceFaultInfoEXT',desc='Structure specifying device fault information',type='structs'] 273-- 274The sname:VkDeviceFaultInfoEXT structure is defined as: 275 276include::{generated}/api/structs/VkDeviceFaultInfoEXT.adoc[] 277 278 * pname:sType is a elink:VkStructureType value identifying this structure. 279 * pname:pNext is `NULL` or a pointer to a structure extending this 280 structure. 281 * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char 282 containing a null-terminated UTF-8 string which is a human readable 283 description of the fault. 284 * pname:pAddressInfos is `NULL` or a pointer to an array of 285 slink:VkDeviceFaultAddressInfoEXT structures describing either memory 286 accesses which may: have caused a page fault, or describing active 287 instruction pointers at the time of the fault. 288 If not `NULL`, each element of pname:pAddressInfos describes the a 289 bounded region of GPU virtual address space containing either the GPU 290 virtual address accessed, or the value of an active instruction pointer. 291 * pname:pVendorInfos is `NULL` or a pointer to an array of 292 slink:VkDeviceFaultVendorInfoEXT structures describing vendor-specific 293 fault information. 294 * pname:pVendorBinaryData is `NULL` or a pointer to pname:vendorBinarySize 295 number of bytes of data, which will be populated with a vendor-specific 296 binary crash dump, as described in <<vendor-binary-crash-dumps, Vendor 297 Binary Crash Dumps>>. 298 299An implementation should: populate as many members of 300slink:VkDeviceFaultInfoEXT as possible, given the information available at 301the time of the fault and the constraints of the implementation itself. 302 303Due to hardware limitations, pname:pAddressInfos describes ranges of GPU 304virtual address space, rather than precise addresses. 305The precise memory address accessed or the precise value of the instruction 306pointer must: lie within the region described. 307 308ifdef::VK_EXT_device_address_binding_report[] 309[NOTE] 310.Note 311==== 312Each element of pname:pAddressInfos describes either: 313 314 * A memory access which may have triggered a page fault and may have 315 contributed to device loss 316 * The value of an active instruction pointer at the time a fault occurred. 317 This value may be indicative of the active pipeline or shader at the 318 time of device loss 319 320Comparison of the GPU virtual addresses described by pname:pAddressInfos to 321GPU virtual address ranges reported by the 322`apiext:VK_EXT_device_address_binding_report` extension may allow 323applications to correlate between these addresses and Vulkan objects. 324Applications should be aware that these addresses may also correspond to 325resources internal to an implementation, which will not be reported via the 326`apiext:VK_EXT_device_address_binding_report` extension. 327==== 328endif::VK_EXT_device_address_binding_report[] 329 330include::{generated}/validity/structs/VkDeviceFaultInfoEXT.adoc[] 331-- 332 333[open,refpage='VkDeviceFaultAddressInfoEXT',desc='Structure specifying GPU virtual address information',type='structs'] 334-- 335The sname:VkDeviceFaultAddressInfoEXT structure is defined as: 336 337include::{generated}/api/structs/VkDeviceFaultAddressInfoEXT.adoc[] 338 339 * pname:addressType is either the type of memory operation that triggered 340 a page fault, or the type of association between an instruction pointer 341 and a fault. 342 * pname:reportedAddress is the GPU virtual address recorded by the device. 343 * pname:addressPrecision is a power of two value that specifies how 344 precisely the device can report the address. 345 346The combination of pname:reportedAddress and pname:addressPrecision allow 347the possible range of addresses to be calculated, such that: 348 349[source,c++] 350---- 351lower_address = (pInfo->reportedAddress & ~(pInfo->addressPrecision-1)) 352upper_address = (pInfo->reportedAddress | (pInfo->addressPrecision-1)) 353---- 354 355[NOTE] 356.Note 357==== 358It is valid for the pname:reportedAddress to contain a more precise address 359than indicated by pname:addressPrecision. 360In this case, the value of pname:reportedAddress should be treated as an 361additional hint as to the value of the address that triggered the page 362fault, or to the value of an instruction pointer. 363==== 364 365include::{generated}/validity/structs/VkDeviceFaultAddressInfoEXT.adoc[] 366-- 367 368[open,refpage='VkDeviceFaultAddressTypeEXT',desc='Page fault access types',type='enums'] 369-- 370Possible values of slink:VkDeviceFaultAddressInfoEXT::pname:addressType are: 371 372include::{generated}/api/enums/VkDeviceFaultAddressTypeEXT.adoc[] 373 374 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that 375 slink:VkDeviceFaultAddressInfoEXT does not describe a page fault, or an 376 instruction address. 377 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that 378 slink:VkDeviceFaultAddressInfoEXT describes a page fault triggered by an 379 invalid read operation. 380 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that 381 slink:VkDeviceFaultAddressInfoEXT describes a page fault triggered by an 382 invalid write operation. 383 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page 384 fault triggered by an attempt to execute non-executable memory. 385 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT 386 specifies an instruction pointer value at the time the fault occurred. 387 This may or may not be related to a fault. 388 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT 389 specifies an instruction pointer value associated with an invalid 390 instruction fault. 391 * ename:VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT 392 specifies an instruction pointer value associated with a fault. 393 394[NOTE] 395.Note 396==== 397The instruction pointer values recorded may not identify the specific 398instruction(s) that triggered the fault. 399The relationship between the instruction pointer reported and triggering 400instruction will be vendor-specific. 401==== 402-- 403 404[open,refpage='VkDeviceFaultVendorInfoEXT',desc='Structure specifying vendor-specific fault information',type='structs'] 405-- 406The sname:VkDeviceFaultVendorInfoEXT structure is defined as: 407 408include::{generated}/api/structs/VkDeviceFaultVendorInfoEXT.adoc[] 409 410 * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char 411 containing a null-terminated UTF-8 string which is a human readable 412 description of the fault. 413 * pname:vendorFaultCode is the vendor-specific fault code for this fault. 414 * pname:vendorFaultData is the vendor-specific fault data associated with 415 this fault. 416 417include::{generated}/validity/structs/VkDeviceFaultVendorInfoEXT.adoc[] 418-- 419 420 421[[vendor-binary-crash-dumps]] 422==== Vendor Binary Crash Dumps 423 424Applications can: store the vendor-specific binary crash dump data retrieved 425by calling flink:vkGetDeviceFaultInfoEXT for later analysis using external 426tools. 427 428However, the format of this data may: depend on the vendor ID, device ID, 429driver version, and other details of the device. 430To enable external applications to identify the original device from which a 431crash dump was generated, the initial bytes written to 432sname:VkDeviceFaultInfoEXT::pname:pVendorBinaryData must: begin with a valid 433crash dump header. 434 435[open,refpage='VkDeviceFaultVendorBinaryHeaderVersionOneEXT',desc='Structure describing the layout of the vendor binary crash dump header',type='structs'] 436-- 437Version one of the crash dump header is defined as: 438 439include::{generated}/api/structs/VkDeviceFaultVendorBinaryHeaderVersionOneEXT.adoc[] 440 441 * pname:headerSize is the length in bytes of the crash dump header. 442 * pname:headerVersion is a elink:VkDeviceFaultVendorBinaryHeaderVersionEXT 443 enum value specifying the version of the header. 444 A consumer of the crash dump should: use the header version to interpret 445 the remainder of the header. 446 * pname:vendorID is the sname:VkPhysicalDeviceProperties::pname:vendorID 447 of the implementation. 448 * pname:deviceID is the sname:VkPhysicalDeviceProperties::pname:deviceID 449 of the implementation. 450 * pname:driverVersion is the 451 sname:VkPhysicalDeviceProperties::pname:driverVersion of the 452 implementation. 453 * pname:pipelineCacheUUID is an array of ename:VK_UUID_SIZE code:uint8_t 454 values matching the 455 sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID property of 456 the implementation. 457 * pname:applicationNameOffset is zero, or an offset from the base address 458 of the crash dump header to a null-terminated UTF-8 string containing 459 the name of the application. 460 If pname:applicationNameOffset is non-zero, this string must: match the 461 application name specified via 462 slink:VkApplicationInfo::pname:pApplicationName during instance 463 creation. 464 * pname:applicationVersion must: be zero or the value specified by 465 slink:VkApplicationInfo::pname:applicationVersion during instance 466 creation. 467 * pname:engineNameOffset is zero, or an offset from the base address of 468 the crash dump header to a null-terminated UTF-8 string containing the 469 name of the engine (if any) used to create the application. 470 If pname:engineNameOffset is non-zero, this string must: match the 471 engine name specified via slink:VkApplicationInfo::pname:pEngineName 472 during instance creation. 473 * pname:engineVersion must: be zero or the value specified by 474 slink:VkApplicationInfo::pname:engineVersion during instance creation. 475 * pname:apiVersion must: be zero or the value specified by 476 slink:VkApplicationInfo::pname:apiVersion during instance creation. 477 478Unlike most structures declared by the Vulkan API, all fields of this 479structure are written with the least significant byte first, regardless of 480host byte-order. 481 482The C language specification does not define the packing of structure 483members. 484This layout assumes tight structure member packing, with members laid out in 485the order listed in the structure, and the intended size of the structure is 48656 bytes. 487If a compiler produces code that diverges from that pattern, applications 488must: employ another method to set values at the correct offsets. 489 490.Valid Usage 491**** 492 * [[VUID-VkDeviceFaultVendorBinaryHeaderVersionOneEXT-headerSize-07340]] 493 pname:headerSize must: be 56 494 * [[VUID-VkDeviceFaultVendorBinaryHeaderVersionOneEXT-headerVersion-07341]] 495 pname:headerVersion must: be 496 ename:VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT 497**** 498 499include::{generated}/validity/structs/VkDeviceFaultVendorBinaryHeaderVersionOneEXT.adoc[] 500-- 501 502[open,refpage='VkDeviceFaultVendorBinaryHeaderVersionEXT',desc='Encode vendor binary crash dump version',type='enums',xrefs='vkGetDeviceFaultInfoEXT'] 503-- 504Possible values of the pname:headerVersion value of the crash dump header 505are: 506 507include::{generated}/api/enums/VkDeviceFaultVendorBinaryHeaderVersionEXT.adoc[] 508 509 * ename:VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT specifies 510 version one of the binary crash dump header. 511-- 512endif::VK_EXT_device_fault[] 513 514 515ifdef::VK_VERSION_1_3,VK_EXT_tooling_info[] 516[[debugging-tooling-info]] 517== Active Tooling Information 518 519[open,refpage='vkGetPhysicalDeviceToolProperties',desc='Reports properties of tools active on the specified physical device',type='protos',alias='vkGetPhysicalDeviceToolPropertiesEXT'] 520-- 521Information about tools providing debugging, profiling, or similar services, 522active for a given physical device, can be obtained by calling: 523 524ifdef::VK_VERSION_1_3[] 525include::{generated}/api/protos/vkGetPhysicalDeviceToolProperties.adoc[] 526endif::VK_VERSION_1_3[] 527 528ifdef::VK_VERSION_1_3+VK_EXT_tooling_info[or the equivalent command] 529 530ifdef::VK_EXT_tooling_info[] 531include::{generated}/api/protos/vkGetPhysicalDeviceToolPropertiesEXT.adoc[] 532endif::VK_EXT_tooling_info[] 533 534 * pname:physicalDevice is the handle to the physical device to query for 535 active tools. 536 * pname:pToolCount is a pointer to an integer describing the number of 537 tools active on pname:physicalDevice. 538 * pname:pToolProperties is either `NULL` or a pointer to an array of 539 slink:VkPhysicalDeviceToolProperties structures. 540 541If pname:pToolProperties is `NULL`, then the number of tools currently 542active on pname:physicalDevice is returned in pname:pToolCount. 543Otherwise, pname:pToolCount must: point to a variable set by the user to the 544number of elements in the pname:pToolProperties array, and on return the 545variable is overwritten with the number of structures actually written to 546pname:pToolProperties. 547If pname:pToolCount is less than the number of currently active tools, at 548most pname:pToolCount structures will be written. 549 550The count and properties of active tools may: change in response to events 551outside the scope of the specification. 552An application should: assume these properties might change at any given 553time. 554 555include::{generated}/validity/protos/vkGetPhysicalDeviceToolProperties.adoc[] 556-- 557 558[open,refpage='VkPhysicalDeviceToolProperties',desc='Structure providing information about an active tool',type='structs',alias='VkPhysicalDeviceToolPropertiesEXT'] 559-- 560The slink:VkPhysicalDeviceToolProperties structure is defined as: 561 562include::{generated}/api/structs/VkPhysicalDeviceToolProperties.adoc[] 563 564ifdef::VK_EXT_tooling_info[] 565or the equivalent 566 567include::{generated}/api/structs/VkPhysicalDeviceToolPropertiesEXT.adoc[] 568endif::VK_EXT_tooling_info[] 569 570 * pname:sType is a elink:VkStructureType value identifying this structure. 571 * pname:pNext is `NULL` or a pointer to a structure extending this 572 structure. 573 * pname:name is a null-terminated UTF-8 string containing the name of the 574 tool. 575 * pname:version is a null-terminated UTF-8 string containing the version 576 of the tool. 577 * pname:purposes is a bitmask of elink:VkToolPurposeFlagBits which is 578 populated with purposes supported by the tool. 579 * pname:description is a null-terminated UTF-8 string containing a 580 description of the tool. 581 * pname:layer is a null-terminated UTF-8 string containing the name of the 582 layer implementing the tool, if the tool is implemented in a layer - 583 otherwise it may: be an empty string. 584 585include::{generated}/validity/structs/VkPhysicalDeviceToolProperties.adoc[] 586-- 587 588[open,refpage='VkToolPurposeFlagBits',desc='Bitmask specifying the purposes of an active tool',type='enums',alias='VkToolPurposeFlagBitsEXT'] 589-- 590Bits which can: be set in 591slink:VkPhysicalDeviceToolProperties::pname:purposes, specifying the 592purposes of an active tool, are: 593 594include::{generated}/api/enums/VkToolPurposeFlagBits.adoc[] 595 596ifdef::VK_EXT_tooling_info[] 597or the equivalent 598 599include::{generated}/api/enums/VkToolPurposeFlagBitsEXT.adoc[] 600endif::VK_EXT_tooling_info[] 601 602 * ename:VK_TOOL_PURPOSE_VALIDATION_BIT specifies that the tool provides 603 validation of API usage. 604 * ename:VK_TOOL_PURPOSE_PROFILING_BIT specifies that the tool provides 605 profiling of API usage. 606 * ename:VK_TOOL_PURPOSE_TRACING_BIT specifies that the tool is capturing 607 data about the application's API usage, including anything from simple 608 logging to capturing data for later replay. 609 * ename:VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT specifies that the tool 610 provides additional API features/extensions on top of the underlying 611 implementation. 612 * ename:VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT specifies that the tool 613 modifies the API features/limits/extensions presented to the 614 application. 615ifdef::VK_EXT_debug_report,VK_EXT_debug_utils[] 616 * ename:VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT specifies that the tool 617 reports additional information to the application via callbacks 618 specified by 619ifdef::VK_EXT_debug_report[] 620 flink:vkCreateDebugReportCallbackEXT 621endif::VK_EXT_debug_report[] 622ifdef::VK_EXT_debug_report+VK_EXT_debug_utils[] 623 or 624endif::VK_EXT_debug_report+VK_EXT_debug_utils[] 625ifdef::VK_EXT_debug_utils[] 626 flink:vkCreateDebugUtilsMessengerEXT 627endif::VK_EXT_debug_utils[] 628endif::VK_EXT_debug_report,VK_EXT_debug_utils[] 629ifdef::VK_EXT_debug_marker,VK_EXT_debug_utils[] 630 * ename:VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT specifies that the tool 631 consumes 632ifdef::VK_EXT_debug_marker[] 633 <<debugging-debug-markers,debug markers>> 634endif::VK_EXT_debug_marker[] 635ifdef::VK_EXT_debug_marker+VK_EXT_debug_utils[] 636 or 637endif::VK_EXT_debug_marker+VK_EXT_debug_utils[] 638ifdef::VK_EXT_debug_utils[] 639 <<debugging-object-debug-annotation,object debug annotation>>, 640 <<debugging-queue-labels, queue labels>>, or 641 <<debugging-command-buffer-labels, command buffer labels>> 642endif::VK_EXT_debug_utils[] 643endif::VK_EXT_debug_marker,VK_EXT_debug_utils[] 644-- 645 646[open,refpage='VkToolPurposeFlags',desc='Bitmask of VkToolPurposeFlagBits',type='flags',alias='VkToolPurposeFlagsEXT'] 647-- 648include::{generated}/api/flags/VkToolPurposeFlags.adoc[] 649 650ifdef::VK_EXT_tooling_info[] 651or the equivalent 652 653include::{generated}/api/flags/VkToolPurposeFlagsEXT.adoc[] 654endif::VK_EXT_tooling_info[] 655 656tlink:VkToolPurposeFlags is a bitmask type for setting a mask of zero or 657more elink:VkToolPurposeFlagBits. 658-- 659endif::VK_VERSION_1_3,VK_EXT_tooling_info[] 660 661 662ifdef::VK_EXT_frame_boundary[] 663== Frame Boundary 664 665[open,refpage='VkFrameBoundaryEXT',desc='Add frame boundary information to queue submissions',type='structs'] 666-- 667The sname:VkFrameBoundaryEXT structure is defined as: 668 669include::{generated}/api/structs/VkFrameBoundaryEXT.adoc[] 670 671 * pname:sType is a elink:VkStructureType value identifying this structure. 672 * pname:pNext is `NULL` or a pointer to a structure extending this 673 structure. 674 * pname:flags is a bitmask of elink:VkFrameBoundaryFlagBitsEXT that can 675 flag the last submission of a frame identifier. 676 * pname:frameID is the frame identifier. 677 * pname:imageCount is the number of images that store frame results. 678 * pname:pImages is a pointer to an array of VkImage objects with 679 imageCount entries. 680 * pname:bufferCount is the number of buffers the store the frame results. 681 * pname:pBuffers is a pointer to an array of VkBuffer objects with 682 bufferCount entries. 683 * pname:tagName is a numerical identifier for tag data. 684 * pname:tagSize is the number of bytes of tag data. 685 * pname:pTag is a pointer to an array of pname:tagSize bytes containing 686 tag data. 687 688The application can: associate frame boundary information to a queue 689submission call by adding a sname:VkFrameBoundaryEXT structure to the 690pname:pNext chain of <<devsandqueues-submission,queue submission>>, 691ifdef::VK_KHR_swapchain[slink:VkPresentInfoKHR,] 692or slink:VkBindSparseInfo. 693 694The frame identifier is used to associate one or more queue submission to a 695frame, it is thus meant to be unique within a frame lifetime, i.e. it is 696possible (but not recommended) to reuse frame identifiers, as long as any 697two frames with any chance of having overlapping queue submissions (as in 698the example above) use two different frame identifiers. 699 700[NOTE] 701.Note 702==== 703Since the concept of frame is application-dependent, there is no way to 704validate the use of frame identifier. 705It is good practice to use a monotonically increasing counter as the frame 706identifier and not reuse identifiers between frames. 707==== 708 709The pname:pImages and pname:pBuffers arrays contain a list of images and 710buffers which store the "end result" of the frame. 711As the concept of frame is application-dependent, not all frames may: 712produce their results in images or buffers, yet this is a sufficiently 713common case to be handled by sname:VkFrameBoundaryEXT. 714Note that no extra information, such as image layout is being provided, 715since the images are meant to be used by tools which would already be 716tracking this required information. 717ifdef::VK_KHR_swapchain[] 718Having the possibility of passing a list of end-result images makes 719sname:VkFrameBoundaryEXT as expressive as flink:vkQueuePresentKHR, which is 720often the default frame boundary delimiter. 721endif::VK_KHR_swapchain[] 722 723The application can: also associate arbitrary extra information via tag data 724using pname:tagName, pname:tagSize and pname:pTag. 725This extra information is typically tool-specific. 726 727include::{generated}/validity/structs/VkFrameBoundaryEXT.adoc[] 728-- 729 730[open,refpage='VkFrameBoundaryFlagBitsEXT',desc='Bitmask specifying whether a queue submission is the last one for a given frame',type='enums'] 731-- 732The bit which can: be set in slink:VkFrameBoundaryEXT::pname:flags is: 733 734include::{generated}/api/enums/VkFrameBoundaryFlagBitsEXT.adoc[] 735 736 * ename:VK_FRAME_BOUNDARY_FRAME_END_BIT_EXT specifies that this queue 737 submission is the last one for this frame, i.e. once this queue 738 submission has terminated, then the work for this frame is completed. 739-- 740 741ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 742Note that in the presence of timeline semaphores, the last queue submission 743might not be the last one to be submitted, as timeline semaphores allow for 744wait-before-signal submissions. 745In the context of frame boundary, the queue submission that should be done 746flagged as the last one is the one that is meant to be executed last, even 747if it may: not be the last one to be submitted. 748endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 749 750[open,refpage='VkFrameBoundaryFlagsEXT',desc='Bitmask of VkFrameBoundaryFlagBitsEXT',type='flags'] 751-- 752include::{generated}/api/flags/VkFrameBoundaryFlagsEXT.adoc[] 753 754tlink:VkFrameBoundaryFlagsEXT is a bitmask type for setting a mask of zero 755or more elink:VkFrameBoundaryFlagBitsEXT. 756-- 757 758endif::VK_EXT_frame_boundary[] 759