vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_EXT_device_fault

Description

Name

VK_EXT_device_fault - device extension

VK_EXT_device_fault

Name String
VK_EXT_device_fault
Extension Type
Device extension
Registered Extension Number
342
Revision
2
Ratification Status
Not ratified
Extension and Version Dependencies
VK_KHR_get_physical_device_properties2
Contact
  • Ralph Potter r_potter
Extension Proposal
VK_EXT_device_fault

Other Extension Metadata

Last Modified Date
2021-03-10
IP Status
No known IP claims.
Contributors
  • Ralph Potter, Samsung
  • Stuart Smith, AMD
  • Jan-Harald Fredriksen, ARM
  • Mark Bellamy, ARM
  • Andrew Ellem, Google
  • Alex Walters, IMG
  • Jeff Bolz, NVIDIA
  • Baldur Karlsson, Valve

Description

Device loss can be triggered by a variety of issues, including invalid API usage, implementation errors, or hardware failures.

This extension introduces a new command: getDeviceFaultInfoEXT, which may be called subsequent to a ERROR_DEVICE_LOST error code having been returned by the implementation. This command allows developers to query for additional information on GPU faults which may have caused device loss, and to generate binary crash dumps, which may be loaded into external tools for further diagnosis.

New Commands

New Structures

New Enums

New Enum Constants

Version History

  • Revision 2, 2023-04-05 (Ralph Potter)

    • Restored two missing members to the XML definition of VkDeviceFaultVendorBinaryHeaderVersionOneEXT. No functional change to the specification.
  • Revision 1, 2020-10-19 (Ralph Potter)

    • Initial revision

See Also

DeviceFaultAddressInfoEXT, DeviceFaultAddressTypeEXT, DeviceFaultCountsEXT, DeviceFaultInfoEXT, DeviceFaultVendorBinaryHeaderVersionEXT, DeviceFaultVendorBinaryHeaderVersionOneEXT, DeviceFaultVendorInfoEXT, PhysicalDeviceFaultFeaturesEXT, getDeviceFaultInfoEXT

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

getDeviceFaultInfoEXT Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the logical device from which to query the diagnostic fault information.

-> io (Result, DeviceFaultCountsEXT, DeviceFaultInfoEXT) 

vkGetDeviceFaultInfoEXT - Reports diagnostic fault information on the specified logical device

Description

If pFaultInfo is NULL, then the counts of corresponding additional fault information structures available are returned in the addressInfoCount and vendorInfoCount members of pFaultCounts. Additionally, the size of any vendor-specific binary crash dump is returned in the vendorBinarySize member of pFaultCounts.

If pFaultInfo is not NULL, pFaultCounts must point to a DeviceFaultCountsEXT structure with each structure count or size member (addressInfoCount, vendorInfoCount, vendorBinarySize) set by the user to the number of elements in the corresponding output array member of pFaultInfo (pAddressInfos and pVendorInfos), or to the size of the output buffer in bytes (pVendorBinaryData). On return, each structure count member is overwritten with the number of structures actually written to the corresponding output array member of pFaultInfo. Similarly, vendorBinarySize is overwritten with the number of bytes actually written to the pVendorBinaryData member of pFaultInfo.

If the vendor-specific crash dumps feature is not enabled, then implementations must set pFaultCounts->vendorBinarySize to zero and must not modify pFaultInfo->pVendorBinaryData.

If any pFaultCounts structure count member is less than the number of corresponding fault properties available, at most structure count (addressInfoCount, vendorInfoCount) elements will be written to the associated pFaultInfo output array. Similarly, if vendorBinarySize is less than the size in bytes of the available crash dump data, at most vendorBinarySize elements will be written to pVendorBinaryData.

If pFaultInfo is NULL, then subsequent calls to getDeviceFaultInfoEXT for the same device must return identical values in the addressInfoCount, vendorInfoCount and vendorBinarySize members of pFaultCounts.

If pFaultInfo is not NULL, then subsequent calls to getDeviceFaultInfoEXT for the same device must return identical values in the output members of pFaultInfo (pAddressInfos, pVendorInfos, pVendorBinaryData), up to the limits described by the structure count and buffer size members of pFaultCounts (addressInfoCount, vendorInfoCount, vendorBinarySize). If the sizes of the output members of pFaultInfo increase for a subsequent call to getDeviceFaultInfoEXT, then supplementary information may be returned in the additional available space.

If any pFaultCounts structure count member is smaller than the number of corresponding fault properties available, or if pFaultCounts->vendorBinarySize is smaller than the size in bytes of the generated binary crash dump data, INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available properties were returned.

If pFaultCounts->vendorBinarySize is less than what is necessary to store the binary crash dump header, nothing will be written to pFaultInfo->pVendorBinaryData and zero will be written to pFaultCounts->vendorBinarySize.

Valid Usage

  • device must be in the lost state
  • If the value referenced by pFaultCounts->addressInfoCount is not 0, and pFaultInfo->pAddressInfos is not NULL, pFaultInfo->pAddressInfos must be a valid pointer to an array of pFaultCounts->addressInfoCount DeviceFaultAddressInfoEXT structures
  • If the value referenced by pFaultCounts->vendorInfoCount is not 0, and pFaultInfo->pVendorInfos is not NULL, pFaultInfo->pVendorInfos must be a valid pointer to an array of pFaultCounts->vendorInfoCount DeviceFaultVendorInfoEXT structures
  • If the value referenced by pFaultCounts->vendorBinarySize is not 0, and pFaultInfo->pVendorBinaryData is not NULL, pFaultInfo->pVendorBinaryData must be a valid pointer to an array of pFaultCounts->vendorBinarySize bytes

Valid Usage (Implicit)

  • device must be a valid Device handle

Return Codes

Success
Failure

See Also

VK_EXT_device_fault, Device, DeviceFaultCountsEXT, DeviceFaultInfoEXT

data PhysicalDeviceFaultFeaturesEXT Source #

VkPhysicalDeviceFaultFeaturesEXT - Structure indicating support for device fault reporting

Members

The members of the PhysicalDeviceFaultFeaturesEXT structure describe the following features:

Description

If the PhysicalDeviceFaultFeaturesEXT structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceFaultFeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_device_fault, Bool32, StructureType

Constructors

PhysicalDeviceFaultFeaturesEXT 

Fields

  • deviceFault :: Bool

    deviceFault indicates that the implementation supports the reporting of device fault information.

  • deviceFaultVendorBinary :: Bool

    deviceFaultVendorBinary indicates that the implementation supports the generation of vendor-specific binary crash dumps. These may provide additional information when imported into vendor-specific external tools.

Instances

Instances details
Storable PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Eq PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero PhysicalDeviceFaultFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

data DeviceFaultAddressInfoEXT Source #

VkDeviceFaultAddressInfoEXT - Structure specifying GPU virtual address information

Description

The combination of reportedAddress and addressPrecision allow the possible range of addresses to be calculated, such that:

lower_address = (pInfo->reportedAddress & ~(pInfo->addressPrecision-1))
upper_address = (pInfo->reportedAddress |  (pInfo->addressPrecision-1))

Note

It is valid for the reportedAddress to contain a more precise address than indicated by addressPrecision. In this case, the value of reportedAddress should be treated as an additional hint as to the value of the address that triggered the page fault, or to the value of an instruction pointer.

Valid Usage (Implicit)

See Also

VK_EXT_device_fault, DeviceAddress, DeviceFaultAddressTypeEXT, DeviceFaultInfoEXT, DeviceSize

Constructors

DeviceFaultAddressInfoEXT 

Fields

Instances

Instances details
Storable DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Eq DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultAddressInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

data DeviceFaultVendorInfoEXT Source #

VkDeviceFaultVendorInfoEXT - Structure specifying vendor-specific fault information

See Also

VK_EXT_device_fault, DeviceFaultInfoEXT

Constructors

DeviceFaultVendorInfoEXT 

Fields

Instances

Instances details
Storable DeviceFaultVendorInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultVendorInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct DeviceFaultVendorInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct DeviceFaultVendorInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultVendorInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

data DeviceFaultCountsEXT Source #

VkDeviceFaultCountsEXT - Structure specifying device fault information

Valid Usage (Implicit)

See Also

VK_EXT_device_fault, DeviceSize, StructureType, getDeviceFaultInfoEXT

Constructors

DeviceFaultCountsEXT 

Fields

Instances

Instances details
Storable DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Eq DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultCountsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

data DeviceFaultInfoEXT Source #

VkDeviceFaultInfoEXT - Structure specifying device fault information

Description

An implementation should populate as many members of DeviceFaultInfoEXT as possible, given the information available at the time of the fault and the constraints of the implementation itself.

Due to hardware limitations, pAddressInfos describes ranges of GPU virtual address space, rather than precise addresses. The precise memory address accessed or the precise value of the instruction pointer must lie within the region described.

Note

Each element of pAddressInfos describes either:

  • A memory access which may have triggered a page fault and may have contributed to device loss
  • The value of an active instruction pointer at the time a fault occurred. This value may be indicative of the active pipeline or shader at the time of device loss

Comparison of the GPU virtual addresses described by pAddressInfos to GPU virtual address ranges reported by the VK_EXT_device_address_binding_report extension may allow applications to correlate between these addresses and Vulkan objects. Applications should be aware that these addresses may also correspond to resources internal to an implementation, which will not be reported via the VK_EXT_device_address_binding_report extension.

Valid Usage (Implicit)

See Also

VK_EXT_device_fault, DeviceFaultAddressInfoEXT, DeviceFaultVendorInfoEXT, StructureType, getDeviceFaultInfoEXT

Constructors

DeviceFaultInfoEXT 

Fields

Instances

Instances details
Storable DeviceFaultInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct DeviceFaultInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct DeviceFaultInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

data DeviceFaultVendorBinaryHeaderVersionOneEXT Source #

VkDeviceFaultVendorBinaryHeaderVersionOneEXT - Structure describing the layout of the vendor binary crash dump header

Description

Unlike most structures declared by the Vulkan API, all fields of this structure are written with the least significant byte first, regardless of host byte-order.

The C language specification does not define the packing of structure members. This layout assumes tight structure member packing, with members laid out in the order listed in the structure, and the intended size of the structure is 56 bytes. If a compiler produces code that diverges from that pattern, applications must employ another method to set values at the correct offsets.

Valid Usage (Implicit)

See Also

VK_EXT_device_fault, DeviceFaultVendorBinaryHeaderVersionEXT

Constructors

DeviceFaultVendorBinaryHeaderVersionOneEXT 

Fields

Instances

Instances details
Storable DeviceFaultVendorBinaryHeaderVersionOneEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultVendorBinaryHeaderVersionOneEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

FromCStruct DeviceFaultVendorBinaryHeaderVersionOneEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

ToCStruct DeviceFaultVendorBinaryHeaderVersionOneEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultVendorBinaryHeaderVersionOneEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

newtype DeviceFaultAddressTypeEXT Source #

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

Note

The instruction pointer values recorded may not identify the specific instruction(s) that triggered the fault. The relationship between the instruction pointer reported and triggering instruction will be vendor-specific.

See Also

VK_EXT_device_fault, DeviceFaultAddressInfoEXT

Bundled Patterns

pattern DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that DeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.

pattern DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that DeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.

pattern DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that DeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.

pattern DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.

pattern DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT specifies an instruction pointer value at the time the fault occurred. This may or may not be related to a fault.

pattern DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.

pattern DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT :: DeviceFaultAddressTypeEXT

DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

Instances

Instances details
Storable DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Read DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Eq DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Ord DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultAddressTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

newtype DeviceFaultVendorBinaryHeaderVersionEXT Source #

VkDeviceFaultVendorBinaryHeaderVersionEXT - Encode vendor binary crash dump version

See Also

VK_EXT_device_fault, DeviceFaultVendorBinaryHeaderVersionOneEXT, getDeviceFaultInfoEXT

Instances

Instances details
Storable DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Read DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Show DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Eq DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Ord DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

Zero DeviceFaultVendorBinaryHeaderVersionEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_fault

pattern EXT_DEVICE_FAULT_SPEC_VERSION :: forall a. Integral a => a Source #

type EXT_DEVICE_FAULT_EXTENSION_NAME = "VK_EXT_device_fault" Source #

pattern EXT_DEVICE_FAULT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #