Package org.lwjgl.vulkan

Class EXTDeviceFault

java.lang.Object

org.lwjgl.vulkan.EXTDeviceFault

public class EXTDeviceFault
extends Object

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.

Name String

VK_EXT_device_fault

Extension Type

Device extension

Registered Extension Number

342

Revision

2

Extension and Version Dependencies

VK_KHR_get_physical_device_properties2 or Version 1.1

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

Field Summary

Fields

Modifier and Type	Field	Description
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT	VkDeviceFaultAddressTypeEXT - Page fault access types
static final int	VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT	VkDeviceFaultVendorBinaryHeaderVersionEXT - Encode vendor binary crash dump version
static final String	VK_EXT_DEVICE_FAULT_EXTENSION_NAME	The extension name.
static final int	VK_EXT_DEVICE_FAULT_SPEC_VERSION	The extension specification version.
static final int	VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT	Extends VkStructureType.
static final int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nvkGetDeviceFaultInfoEXT(org.lwjgl.vulkan.VkDevice device, long pFaultCounts, long pFaultInfo)	Unsafe version of: GetDeviceFaultInfoEXT
static int	vkGetDeviceFaultInfoEXT(org.lwjgl.vulkan.VkDevice device, VkDeviceFaultCountsEXT pFaultCounts, @Nullable VkDeviceFaultInfoEXT pFaultInfo)	Reports diagnostic fault information on the specified logical device.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

VK_EXT_DEVICE_FAULT_SPEC_VERSION

public static final int VK_EXT_DEVICE_FAULT_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

VK_EXT_DEVICE_FAULT_EXTENSION_NAME

public static final String VK_EXT_DEVICE_FAULT_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT

public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT

public static final int VK_STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT

public static final int VK_STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_PHYSICAL_DEVICE_FAULT_FEATURES_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_COUNTS_EXT
• STRUCTURE_TYPE_DEVICE_FAULT_INFO_EXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT

public static final int VK_DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT

VkDeviceFaultAddressTypeEXT - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_EXT specifies that VkDeviceFaultAddressInfoEXT does not describe a page fault, or an instruction address.
• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid read operation.
• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_EXT specifies that VkDeviceFaultAddressInfoEXT describes a page fault triggered by an invalid write operation.
• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_EXT describes a page fault triggered by an attempt to execute non-executable memory.
• 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.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_INVALID_EXT specifies an instruction pointer value associated with an invalid instruction fault.
• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_EXT specifies an instruction pointer value associated with a fault.

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

VkDeviceFaultAddressInfoEXT

See Also:

• Constant Field Values

VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT

public static final int VK_DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT

VkDeviceFaultVendorBinaryHeaderVersionEXT - Encode vendor binary crash dump version

Description

• DEVICE_FAULT_VENDOR_BINARY_HEADER_VERSION_ONE_EXT specifies version one of the binary crash dump header.

See Also

VkDeviceFaultVendorBinaryHeaderVersionOneEXT, GetDeviceFaultInfoEXT

See Also:

• Constant Field Values

Method Details

nvkGetDeviceFaultInfoEXT

public static int nvkGetDeviceFaultInfoEXT(org.lwjgl.vulkan.VkDevice device,
 long pFaultCounts,
 long pFaultInfo)

Unsafe version of: GetDeviceFaultInfoEXT

vkGetDeviceFaultInfoEXT

public static int vkGetDeviceFaultInfoEXT(org.lwjgl.vulkan.VkDevice device,
 VkDeviceFaultCountsEXT pFaultCounts,
 @Nullable VkDeviceFaultInfoEXT pFaultInfo)

Reports diagnostic fault information on the specified logical device.

C Specification

To retrieve diagnostic information about faults that may have caused device loss, call:

 VkResult vkGetDeviceFaultInfoEXT(
     VkDevice                                    device,
     VkDeviceFaultCountsEXT*                     pFaultCounts,
     VkDeviceFaultInfoEXT*                       pFaultInfo);

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 VkDeviceFaultCountsEXT structure with each structure count or size member (addressInfoCount, vendorInfoCount, vendorBinarySize) set by the application 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 VkDeviceFaultAddressInfoEXT 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 VkDeviceFaultVendorInfoEXT 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 VkDevice handle
• pFaultCounts must be a valid pointer to a VkDeviceFaultCountsEXT structure
• If pFaultInfo is not NULL, pFaultInfo must be a valid pointer to a VkDeviceFaultInfoEXT structure

Return Codes

On success, this command returns

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY

See Also

VkDeviceFaultCountsEXT, VkDeviceFaultInfoEXT

Parameters:

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

pFaultCounts - a pointer to a VkDeviceFaultCountsEXT structure in which counts for structures describing additional fault information are returned.

pFaultInfo - NULL or a pointer to a VkDeviceFaultInfoEXT structure in which fault information is returned.