VK_EXT_device_address_binding_report(3)

# VK_EXT_device_address_binding_report(3) Manual Page

## Name

VK_EXT_device_address_binding_report - device extension

Loading… please wait.

## Registered Extension Number

355

## Revision

1

## Ratification Status

Not ratified

## Extension and Version Dependencies

VK_KHR_get_physical_device_properties2
and
VK_EXT_debug_utils

## Special Uses

- Debugging tools

- Developer tools

## Contact

- Ralph Potter r_potter

## Other Extension Metadata

Last Modified Date

  2020-11-23

Interactions and External Dependencies

  - This extension requires `VK_EXT_debug_utils`

Contributors

  - Ralph Potter, Samsung

  - Spencer Fricke, Samsung

  - Jan-Harald Fredriksen, ARM

  - Andrew Ellem, Google

  - Alex Walters, IMG

  - Jeff Bolz, NVIDIA

## Description

This extension enables applications to track the binding of regions of the GPU virtual address space, and to associate those regions with Vulkan objects. This extension is primarily intended to aid in crash postmortem, where applications may wish to map a faulting GPU address to a Vulkan object.

For example, a page fault triggered by accessing an address located within a region of the GPU virtual address space that was previously reported as bound and then unbound may indicate a use-after-free error. Similarly, faults generated by accessing virtual addresses outside the limits of a bound region of GPU virtual address space may indicate indexing beyond the bounds of a resource.

## New Structures

- Extending VkDebugUtilsMessengerCallbackDataEXT:

  - VkDeviceAddressBindingCallbackDataEXT

- Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:

  - VkPhysicalDeviceAddressBindingReportFeaturesEXT

## New Enums

- VkDeviceAddressBindingFlagBitsEXT

- VkDeviceAddressBindingTypeEXT

## New Bitmasks

- VkDeviceAddressBindingFlagsEXT

## New Enum Constants

- `VK_EXT_DEVICE_ADDRESS_BINDING_REPORT_EXTENSION_NAME`

- `VK_EXT_DEVICE_ADDRESS_BINDING_REPORT_SPEC_VERSION`

- Extending VkDebugUtilsMessageTypeFlagBitsEXT:

  - `VK_DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_DEVICE_ADDRESS_BINDING_CALLBACK_DATA_EXT`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ADDRESS_BINDING_REPORT_FEATURES_EXT`

## Issues

1.) Should this extend VK_EXT_debug_utils or VK_EXT_device_memory_report?

RESOLVED: Extend VK_EXT_debug_utils. VK_EXT_device_memory_report focuses on memory allocations and would not normally trigger callbacks in all of the situations where VK_EXT_device_address_binding_report is expected to.

2.) Should this extension cover all Vulkan object types, or only resources such as buffers and images?

RESOLVED: The extension covers all Vulkan objects, and is not restricted to objects backed by VkDeviceMemory objects.

3.) Should reallocation be identified explicitly, or as a unbind/bind pair?

RESOLVED: Reallocation should be represented as an unbind/bind pair.

4.) Can multiple Vulkan objects share an overlapping virtual address range?

RESOLVED: Yes. This can be expected to occur due to resources aliasing.

5.) Can a single Vulkan object be associated with multiple virtual address ranges concurrently?

RESOLVED: Yes. These should be reported via multiple calls to the reporting callback.

6.) Should the virtual address ranges associated with internal allocations such as memory pools be reported?

RESOLVED: Virtual address ranges associated with internal allocations should only be reported when they become associated with a specific Vulkan object. In the case of internal pool allocations, a bind event should be reported when resources from the pool are assigned to a Vulkan object, and an unbind event should be reported when those resources are returned to the pool. Implementations should not report the binding or unbinding of virtual address ranges for which there are no related API objects visible to the application developer.

7.) Can an implementation report binding a virtual address range at VkImage or VkImageView creation, rather than in response to vkBindImageMemory?

RESOLVED: Yes. Virtual address range binding should be reported at the appropriate point at which it occurs within the implementation. This extension does not mandate when that should occur, and applications should anticipate receiving callback events at any point after registering callbacks.

8.) Can reporting of binding/unbinding be deferred until a resource is referenced by an executing command buffer?

RESOLVED: Changes to the virtual address ranges associated with a Vulkan object should be reported as close as possible to where they occur within the implementation. If virtual address binding is deferred, then the callback should also be deferred to match.

9.) Do bind/unbind callbacks have to form matched pairs? Can a large region be bound, and then subregions unbound, resulting in fragmentation?

RESOLVED: Splitting of virtual address regions, and unmatched bind/unbind callbacks may occur. Developers should anticipate that sparse memory may exhibit this behaviour.

10.) The specification mandates that a callback must be triggered whenever a GPU virtual address range associated with any Vulkan object is bound or unbound. Do we need queries or properties indicating which Vulkan objects will report binding modifications?

RESOLVED: No. This extension is not intended to mandate how and when implementations bind virtual ranges to objects. Adding queries or properties would constrain implementations, which might otherwise vary how virtual address bindings occur based on usage.

11.) Should vkAllocateMemory and vkFreeMemory trigger reporting callbacks?

RESOLVED: If an implementation binds a GPU virtual address range when vkAllocateMemory is called, then the callbacks must be triggered associating the virtual address range with the VkDeviceMemory object. If the device memory is subsequently bound to a buffer or image via vkBind*Memory, the callbacks should be triggered a second time, reporting the association between virtual address range and the buffer/image.

## Version History

- Revision 1, 2020-09-23 (Ralph Potter)

  - Internal revisions

## See Also

VkDeviceAddressBindingCallbackDataEXT, VkDeviceAddressBindingFlagBitsEXT, VkDeviceAddressBindingFlagsEXT, VkDeviceAddressBindingTypeEXT, VkPhysicalDeviceAddressBindingReportFeaturesEXT

## 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.

## Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0