Vulkan.Extensions.VK_KHR_device_fault

vkGetDeviceFaultReportsKHR - Reports fault information for the specified device

Description

If at least one fault report is available when getDeviceFaultReportsKHR is called, then getDeviceFaultReportsKHR returns immediately. If no faults have occurred at the time getDeviceFaultReportsKHR is called, then getDeviceFaultReportsKHR will block and wait until a fault occurs and a report becomes available or until the timeout has expired, whichever is sooner.

If timeout is zero, then getDeviceFaultReportsKHR does not wait, but simply returns the current fault count and reports. TIMEOUT will be returned in this case if no faults have occurred, even though no actual wait was performed.

If a fault has occurred before the timeout has expired, getDeviceFaultReportsKHR returns SUCCESS. Otherwise, getDeviceFaultReportsKHR returns TIMEOUT after the timeout has expired.

If pFaultInfo is NULL, then the number of fault reports available is returned in pFaultCount. Otherwise, pFaultCount must point to a variable set by the application to the number of elements in the pFaultInfo array, and on return the variable is overwritten with the number of handles actually written to pFaultInfo. If pFaultCount is less than the number of fault reports available, at most pFaultCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available fault reports were returned.

If more than one fault report is available, they will be returned in order of occurrence via pFaultInfo.

Each individual fault report is returned exactly once.

getDeviceFaultReportsKHR() may be invoked in parallel on different threads, in which case each invocation for a given device will return a unique set of reports. No fault report being returned to more than one invocation.

Valid Usage (Implicit)

• device must be a valid Device handle

• pFaultCounts must be a valid pointer to a uint32_t value

• If pFaultInfo is not NULL, pFaultInfo must be a valid pointer to an array of pFaultCounts DeviceFaultInfoKHR structures

• If pFaultInfo is not NULL, the value referenced by pFaultCounts must be greater than 0

Return Codes

Success

• INCOMPLETE

• SUCCESS

• TIMEOUT

Failure

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_device_fault, Device, DeviceFaultInfoKHR

vkGetDeviceFaultDebugInfoKHR - Retrieve vendor-specific crash dump data for the specified logical device

Description

If pDebugInfo->pVendorBinaryData is NULL, then the size of any vendor-specific binary crash dump is returned in pDebugInfo->vendorBinarySize.

If the pDebugInfo->pVendorBinaryData is not NULL then it must point to a buffer of size pDebugInfo->vendorBinarySize bytes.

On return, pDebugInfo->vendorBinarySize will be overwritten with the number of bytes actually written to the pDebugInfo->pVendorBinaryData.

If pDebugInfo->vendorBinaryData is not NULL, then subsequent calls to getDeviceFaultDebugInfoKHR for the same device must return identical binary values in the pDebugInfo->pVendorBinaryData buffer up to the limit defined by pDebugInfo->vendorBinarySize.

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

Return Codes

Success

• INCOMPLETE

• SUCCESS

Failure

• ERROR_NOT_ENOUGH_SPACE_KHR

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_device_fault, Device, DeviceFaultDebugInfoKHR

VkDeviceFaultAddressInfoKHR - 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))

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.

See Also

VK_EXT_device_fault, VK_KHR_device_fault, DeviceAddress, DeviceFaultAddressTypeKHR, DeviceFaultInfoEXT, DeviceFaultInfoKHR, DeviceSize

VkDeviceFaultVendorInfoKHR - Structure specifying vendor-specific fault information

See Also

VK_EXT_device_fault, VK_KHR_device_fault, DeviceFaultInfoEXT, DeviceFaultInfoKHR

VkDeviceFaultInfoKHR - Structure specifying device fault information

Description

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

A single error may generate multiple instances of DeviceFaultInfoKHR. For example, multiple page faults may be generated, with the faultAddress member of each instance identifying a different memory address. In this case, all instances of DeviceFaultInfoKHR should share the same groupID where the implementation can reasonably ascertain this association.

Due to hardware limitations, faultAddressInfo and instructionAddressInfo describe 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.

Each DeviceFaultInfoKHR reported may (depending on the flags set) provide:

• 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 faultAddressInfo or instructionAddressInfo 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_KHR_device_fault, DeviceFaultAddressInfoKHR, DeviceFaultFlagsKHR, DeviceFaultVendorInfoKHR, StructureType, getDeviceFaultReportsKHR

VkDeviceFaultDebugInfoKHR - Structure allowing retrieval of the vendor binary crash dump

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DEVICE_FAULT_DEBUG_INFO_KHR

• pNext must be NULL or a pointer to a valid instance of DeviceFaultShaderAbortMessageInfoKHR

• The sType value of each structure in the pNext chain must be unique

See Also

VK_KHR_device_fault, StructureType, getDeviceFaultDebugInfoKHR

VkDeviceFaultVendorBinaryHeaderVersionOneKHR - 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, VK_KHR_device_fault, DeviceFaultVendorBinaryHeaderVersionKHR

VkPhysicalDeviceFaultFeaturesKHR - Structure indicating support for device fault reporting

Members

This structure describes the following features:

Description

In exceptional circumstances, some implementations may mask faults and attempt to recover from an error. In such circumstances, the device is not lost and further work can be submitted to the device. When such faults occur, the contents of all resources being written to at the time of the fault are undefined.

If the PhysicalDeviceFaultFeaturesKHR 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. If the application wishes to use a Device with any features described by PhysicalDeviceFaultFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_KHR_device_fault, Bool32, StructureType

VkPhysicalDeviceFaultPropertiesKHR - Structure describing fault reporting properties for the physical device

Members

The members of the PhysicalDeviceFaultPropertiesKHR structure describe the following:

Description

If the PhysicalDeviceFaultPropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

• PhysicalDeviceProperties2

See Also

VK_KHR_device_fault, StructureType

VkDeviceFaultFlagBitsKHR - Bits which may be set in a VkDeviceFaultFlagsKHR bitmask

Description

• DEVICE_FAULT_FLAG_DEVICE_LOST_KHR specifies that the fault has resulted in a device lost condition. No subsequent entries will be returned for this device.

• DEVICE_FAULT_FLAG_MEMORY_ADDRESS_KHR specifies that the fault has associated memory access address information which is stored in the faultAddressInfo field (see DeviceFaultAddressInfoKHR).

• DEVICE_FAULT_FLAG_INSTRUCTION_ADDRESS_KHR specifies that the fault has an associated instruction address which is stored in the instructionAddressInfo field (see DeviceFaultAddressInfoKHR).

• DEVICE_FAULT_FLAG_VENDOR_KHR specifies that the fault has associated vendor information stored in the vendorInfo field (see DeviceFaultVendorInfoKHR).

• DEVICE_FAULT_FLAG_WATCHDOG_TIMEOUT_KHR specifies that the fault was the result of a GPU timeout. Further information may be made available using other platform specific extensions via the pNext chain of the DeviceFaultInfoKHR structure.

• DEVICE_FAULT_FLAG_OVERFLOW_KHR specifies that prior faults have occurred, but information about them is no longer available. This typically indicates that faults are occurring more rapidly than the calling application is able to read them back.

See Also

VK_KHR_device_fault, DeviceFaultFlagsKHR

VkDeviceFaultAddressTypeKHR - Page fault access types

Description

• DEVICE_FAULT_ADDRESS_TYPE_NONE_KHR specifies that DeviceFaultAddressInfoKHR does not describe a page fault, or an instruction address.

• DEVICE_FAULT_ADDRESS_TYPE_READ_INVALID_KHR specifies that DeviceFaultAddressInfoKHR describes a page fault triggered by an invalid read operation.

• DEVICE_FAULT_ADDRESS_TYPE_WRITE_INVALID_KHR specifies that DeviceFaultAddressInfoKHR describes a page fault triggered by an invalid write operation.

• DEVICE_FAULT_ADDRESS_TYPE_EXECUTE_INVALID_KHR specifies that DeviceFaultAddressInfoKHR describes a page fault triggered by an attempt to execute non-executable memory.

• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_UNKNOWN_KHR 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_KHR specifies an instruction pointer value associated with an invalid instruction fault.

• DEVICE_FAULT_ADDRESS_TYPE_INSTRUCTION_POINTER_FAULT_KHR specifies an instruction pointer value associated with a fault.

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, VK_KHR_device_fault, DeviceFaultAddressInfoKHR

VkDeviceFaultVendorBinaryHeaderVersionKHR - Encode vendor binary crash dump version

Description

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

See Also

VK_EXT_device_fault, VK_KHR_device_fault, DeviceFaultVendorBinaryHeaderVersionOneKHR, getDeviceFaultInfoEXT