vkGetDeviceFaultReportsKHR(3)

Name

vkGetDeviceFaultReportsKHR - Reports fault information for the specified device

C Specification

To retrieve diagnostic information about faults call:

// Provided by VK_KHR_device_fault
VkResult vkGetDeviceFaultReportsKHR(
    VkDevice                                    device,
    uint64_t                                    timeout,
    uint32_t*                                   pFaultCounts,
    VkDeviceFaultInfoKHR*                       pFaultInfo);

Parameters

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

  • timeout is the timeout period in units of nanoseconds. timeout is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

  • pFaultCount is a pointer to an integer related to the number of fault reports available or queried, as described below.

  • pFaultInfo is NULL or a pointer to an array of VkDeviceFaultInfoKHR structures in which fault information is returned.

Description

If at least one fault report is available when vkGetDeviceFaultReportsKHR is called, then vkGetDeviceFaultReportsKHR returns immediately. If no faults have occurred at the time vkGetDeviceFaultReportsKHR is called, then vkGetDeviceFaultReportsKHR 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 vkGetDeviceFaultReportsKHR does not wait, but simply returns the current fault count and reports. VK_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, vkGetDeviceFaultReportsKHR returns VK_SUCCESS. Otherwise, vkGetDeviceFaultReportsKHR returns VK_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 VK_INCOMPLETE will be returned instead of VK_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.

vkGetDeviceFaultReportsKHR() 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)

  • VUID-vkGetDeviceFaultReportsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetDeviceFaultReportsKHR-pFaultCounts-parameter
    pFaultCounts must be a valid pointer to a uint32_t value

  • VUID-vkGetDeviceFaultReportsKHR-pFaultInfo-parameter
    If pFaultInfo is not NULL, pFaultInfo must be a valid pointer to an array of pFaultCounts VkDeviceFaultInfoKHR structures

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

Return Codes
Success
Failure

See Also

VK_KHR_device_fault, VkDevice, VkDeviceFaultInfoKHR

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.