C Specification

To query the number of current faults and obtain the fault data, call vkGetFaultData.

// Provided by VKSC_VERSION_1_0
VkResult vkGetFaultData(
    VkDevice                                    device,
    VkFaultQueryBehavior                        faultQueryBehavior,
    VkBool32*                                   pUnrecordedFaults,
    uint32_t*                                   pFaultCount,
    VkFaultData*                                pFaults);

Parameters

  • device is the logical device to obtain faults from.

  • faultQueryBehavior is a VkFaultQueryBehavior that specifies the types of faults to obtain from the implementation, and how those faults should be handled.

  • pUnrecordedFaults is a return boolean that specifies if the logged fault information is incomplete and does not contain entries for all faults that have been detected by the implementation and may be reported via vkGetFaultData.

  • pFaultCount is a pointer to an integer that specifies the number of fault entries.

  • pFaults is either NULL or a pointer to an array of pFaultCount VkFaultData structures to be updated with the recorded fault data.

Description

Access to fault data is internally synchronized, meaning vkGetFaultData can be called from multiple threads simultaneously.

The implementation must not record more than maxQueryFaultCount faults to be reported by vkGetFaultData.

pUnrecordedFaults is set to VK_TRUE if the implementation has detected one or more faults since the last successful retrieval of fault data using this command, but was unable to record fault information for all faults. Otherwise, pUnrecordedFaults is set to VK_FALSE.

If pFaults is NULL, then the number of faults with the specified faultQueryBehavior characteristics associated with device is returned in pFaultCount, and pUnrecordedFaults is set as indicated above. Otherwise, pFaultCount must point to a variable set by the user to the number of elements in the pFaults array, and on return the variable is overwritten with the number of faults actually written to pFaults. If pFaultCount is less than the number of recorded device faults with the specified faultQueryBehavior characteristics, at most pFaultCount faults will be written, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available faults were returned.

On success, the fault information stored by the implementation for the faults that were returned will be handled as specified by faultQueryBehavior.

For each filled pFaults entry, if pNext is not NULL, the implementation will fill in any implementation-specific structures applicable to that fault that are included in the pNext chain.

Note

In order to simplify the application logic, an application could have a static allocation sized to maxQueryFaultCount which it passes in to each call of vkGetFaultData. This allows an application to obtain all the faults available at this time in a single call to vkGetFaultData. Furthermore, under this usage pattern, the command will never return VK_INCOMPLETE.

If VkPhysicalDeviceVulkanSC10Properties::deviceNoDynamicHostAllocations is VK_TRUE, vkGetFaultData must not return VK_ERROR_OUT_OF_HOST_MEMORY.

Valid Usage

  • VUID-vkGetFaultData-pFaultCount-05020
    pFaultCount must be less than or equal to maxQueryFaultCount

Valid Usage (Implicit)

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

  • VUID-vkGetFaultData-faultQueryBehavior-parameter
    faultQueryBehavior must be a valid VkFaultQueryBehavior value

  • VUID-vkGetFaultData-pUnrecordedFaults-parameter
    pUnrecordedFaults must be a valid pointer to a VkBool32 value

  • VUID-vkGetFaultData-pFaultCount-parameter
    pFaultCount must be a valid pointer to a uint32_t value

  • VUID-vkGetFaultData-pFaults-parameter
    If the value referenced by pFaultCount is not 0, and pFaults is not NULL, pFaults must be a valid pointer to an array of pFaultCount VkFaultData structures

Return Codes
On success, this command returns

  • VK_SUCCESS

  • VK_INCOMPLETE

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VKSC_VERSION_1_0, VkBool32, VkDevice, VkFaultData, VkFaultQueryBehavior

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.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0