• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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