vulkan-3.26.2: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_EXT_device_memory_report

Description

Name

VK_EXT_device_memory_report - device extension

VK_EXT_device_memory_report

Name String
VK_EXT_device_memory_report
Extension Type
Device extension
Registered Extension Number
285
Revision
2
Ratification Status
Not ratified
Extension and Version Dependencies
VK_KHR_get_physical_device_properties2
Special Use
Contact

Other Extension Metadata

Last Modified Date
2021-01-06
IP Status
No known IP claims.
Contributors
  • Yiwei Zhang, Google
  • Jesse Hall, Google

Description

This device extension allows registration of device memory event callbacks upon device creation, so that applications or middleware can obtain detailed information about memory usage and how memory is associated with Vulkan objects. This extension exposes the actual underlying device memory usage, including allocations that are not normally visible to the application, such as memory consumed by createGraphicsPipelines. It is intended primarily for use by debug tooling rather than for production applications.

New Structures

New Function Pointers

New Enums

New Bitmasks

New Enum Constants

Issues

1) Should this be better expressed as an extension to VK_EXT_debug_utils and its general-purpose messenger construct?

RESOLVED: No. The intended lifecycle is quite different. We want to make this extension tied to the device’s lifecycle. Each ICD just handles its own implementation of this extension, and this extension will only be directly exposed from the ICD. So we can avoid the extra implementation complexity used to accommodate the flexibility of VK_EXT_debug_utils extension.

2) Can we extend and use the existing internal allocation callbacks instead of adding the new callback structure in this extension?

RESOLVED: No. Our memory reporting layer that combines this information with other memory information it collects directly (e.g. bindings of resources to DeviceMemory) would have to intercept all entry points that take a AllocationCallbacks parameter and inject its own pfnInternalAllocation and pfnInternalFree. That may be doable for the extensions we know about, but not for ones we do not. The proposal would work fine in the face of most unknown extensions. But even for ones we know about, since apps can provide a different set of callbacks and userdata and those can be retained by the driver and used later (esp. for pool object, but not just those), we would have to dynamically allocate the interception trampoline every time. That is getting to be an unreasonably large amount of complexity and (possibly) overhead.

We are interested in both alloc/free and import/unimport. The latter is fairly important for tracking (and avoiding double-counting) of swapchain images (still true with “native swapchains” based on external memory) and media/camera interop. Though we might be able to handle this with additional InternalAllocationType values, for import/export we do want to be able to tie this to the external resource, which is one thing that the memoryObjectId is for.

The internal alloc/free callbacks are not extensible except via new InternalAllocationType values. The DeviceMemoryReportCallbackDataEXT in this extension is extensible. That was deliberate: there is a real possibility we will want to get extra information in the future. As one example, currently this reports only physical allocations, but we believe there are interesting cases for tracking how populated that VA region is.

The callbacks are clearly specified as only callable within the context of a call from the app into Vulkan. We believe there are some cases where drivers can allocate device memory asynchronously. This was one of the sticky issues that derailed the internal device memory allocation reporting design (which is essentially what this extension is trying to do) leading up to 1.0.

AllocationCallbacks is described in a section called “Host memory” and the intro to it is very explicitly about host memory. The other callbacks are all inherently about host memory. But this extension is very focused on device memory.

3) Should the callback be reporting which heap is used?

RESOLVED: Yes. It is important for non-UMA systems to have all the device memory allocations attributed to the corresponding device memory heaps. For internally-allocated device memory, heapIndex will always correspond to an advertised heap, rather than having a magic value indicating a non-advertised heap. Drivers can advertise heaps that do not have any corresponding memory types if they need to.

4) Should we use an array of callback for the layers to intercept instead of chaining multiple of the DeviceDeviceMemoryReportCreateInfoEXT structures in the pNext of DeviceCreateInfo?

RESOLVED No. The pointer to the DeviceDeviceMemoryReportCreateInfoEXT structure itself is const and you cannot just cast it away. Thus we cannot update the callback array inside the structure. In addition, we cannot drop this pNext chain either, so making a copy of this whole structure does not work either.

5) Should we track bulk allocations shared among multiple objects?

RESOLVED No. Take the shader heap as an example. Some implementations will let multiple Pipeline objects share the same shader heap. We are not asking the implementation to report OBJECT_TYPE_PIPELINE along with a NULL_HANDLE for this bulk allocation. Instead, this bulk allocation is considered as a layer below what this extension is interested in. Later, when the actual Pipeline objects are created by suballocating from the bulk allocation, we ask the implementation to report the valid handles of the Pipeline objects along with the actual suballocated sizes and different memoryObjectId.

6) Can we require the callbacks to be always called in the same thread with the Vulkan commands?

RESOLVED No. Some implementations might choose to multiplex work from multiple application threads into a single backend thread and perform JIT allocations as a part of that flow. Since this behavior is theoretically legit, we cannot require the callbacks to be always called in the same thread with the Vulkan commands, and the note is to remind the applications to handle this case properly.

7) Should we add an additional “allocation failed” event type with things like size and heap index reported?

RESOLVED Yes. This fits in well with the callback infrastructure added in this extension, and implementation touches the same code and has the same overheads as the rest of the extension. It could help debugging things like getting an ERROR_OUT_OF_HOST_MEMORY error when ending a command buffer. Right now the allocation failure could have happened anywhere during recording, and a callback would be really useful to understand where and why.

Version History

  • Revision 1, 2020-08-26 (Yiwei Zhang)

    • Initial version
  • Revision 2, 2021-01-06 (Yiwei Zhang)

    • Minor description update

See Also

PFN_vkDeviceMemoryReportCallbackEXT, DeviceDeviceMemoryReportCreateInfoEXT, DeviceMemoryReportCallbackDataEXT, DeviceMemoryReportEventTypeEXT, DeviceMemoryReportFlagsEXT, PhysicalDeviceDeviceMemoryReportFeaturesEXT

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.

Synopsis

Documentation

data PhysicalDeviceDeviceMemoryReportFeaturesEXT Source #

VkPhysicalDeviceDeviceMemoryReportFeaturesEXT - Structure describing whether device memory report callback can be supported by an implementation

Members

This structure describes the following feature:

Description

If the PhysicalDeviceDeviceMemoryReportFeaturesEXT 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. PhysicalDeviceDeviceMemoryReportFeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_device_memory_report, Bool32, StructureType

Constructors

PhysicalDeviceDeviceMemoryReportFeaturesEXT 

Fields

  • deviceMemoryReport :: Bool

    deviceMemoryReport indicates whether the implementation supports the ability to register device memory report callbacks.

Instances

Instances details
Storable PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Show PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Eq PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

FromCStruct PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

ToCStruct PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Zero PhysicalDeviceDeviceMemoryReportFeaturesEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

data DeviceDeviceMemoryReportCreateInfoEXT Source #

VkDeviceDeviceMemoryReportCreateInfoEXT - Register device memory report callbacks for a Vulkan device

Description

The callback may be called from multiple threads simultaneously.

The callback must be called only once by the implementation when a DeviceMemoryReportEventTypeEXT event occurs.

Note

The callback could be called from a background thread other than the thread calling the Vulkan commands.

Valid Usage (Implicit)

See Also

PFN_vkDeviceMemoryReportCallbackEXT, VK_EXT_device_memory_report, DeviceMemoryReportFlagsEXT, StructureType

Constructors

DeviceDeviceMemoryReportCreateInfoEXT 

Fields

Instances

Instances details
Storable DeviceDeviceMemoryReportCreateInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Show DeviceDeviceMemoryReportCreateInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

FromCStruct DeviceDeviceMemoryReportCreateInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

ToCStruct DeviceDeviceMemoryReportCreateInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Zero DeviceDeviceMemoryReportCreateInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

data DeviceMemoryReportCallbackDataEXT Source #

VkDeviceMemoryReportCallbackDataEXT - Structure specifying parameters returned to the callback

Description

memoryObjectId is used to avoid double-counting on the same memory object.

If an internally-allocated device memory object or a DeviceMemory cannot be exported, memoryObjectId must be unique in the Device.

If an internally-allocated device memory object or a DeviceMemory supports being exported, memoryObjectId must be unique system wide.

If an internal device memory object or a DeviceMemory is backed by an imported external memory object, memoryObjectId must be unique system wide.

Note

This structure should only be considered valid during the lifetime of the triggered callback.

For DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, objectHandle usually will not yet exist when the application or tool receives the callback. objectHandle will only exist when the create or allocate call that triggered the event returns, and if the allocation or import ends up failing objectHandle will not ever exist.

Valid Usage (Implicit)

See Also

VK_EXT_device_memory_report, DeviceMemoryReportEventTypeEXT, DeviceMemoryReportFlagsEXT, DeviceSize, ObjectType, StructureType

Constructors

DeviceMemoryReportCallbackDataEXT 

Fields

Instances

Instances details
Storable DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Show DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Eq DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

FromCStruct DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

ToCStruct DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Zero DeviceMemoryReportCallbackDataEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

newtype DeviceMemoryReportFlagsEXT Source #

VkDeviceMemoryReportFlagsEXT - Reserved for future use

Description

DeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

VK_EXT_device_memory_report, DeviceDeviceMemoryReportCreateInfoEXT, DeviceMemoryReportCallbackDataEXT

Instances

Instances details
Storable DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Bits DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Methods

(.&.) :: DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT #

(.|.) :: DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT #

xor :: DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT #

complement :: DeviceMemoryReportFlagsEXT -> DeviceMemoryReportFlagsEXT #

shift :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

rotate :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

zeroBits :: DeviceMemoryReportFlagsEXT #

bit :: Int -> DeviceMemoryReportFlagsEXT #

setBit :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

clearBit :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

complementBit :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

testBit :: DeviceMemoryReportFlagsEXT -> Int -> Bool #

bitSizeMaybe :: DeviceMemoryReportFlagsEXT -> Maybe Int #

bitSize :: DeviceMemoryReportFlagsEXT -> Int #

isSigned :: DeviceMemoryReportFlagsEXT -> Bool #

shiftL :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

unsafeShiftL :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

shiftR :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

unsafeShiftR :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

rotateL :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

rotateR :: DeviceMemoryReportFlagsEXT -> Int -> DeviceMemoryReportFlagsEXT #

popCount :: DeviceMemoryReportFlagsEXT -> Int #

FiniteBits DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Read DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Show DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Eq DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Ord DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Zero DeviceMemoryReportFlagsEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

newtype DeviceMemoryReportEventTypeEXT Source #

VkDeviceMemoryReportEventTypeEXT - Events that can occur on a device memory object

See Also

VK_EXT_device_memory_report, DeviceMemoryReportCallbackDataEXT

Bundled Patterns

pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT :: DeviceMemoryReportEventTypeEXT

DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this event corresponds to the allocation of an internal device memory object or a DeviceMemory.

pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT :: DeviceMemoryReportEventTypeEXT

DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event corresponds to the deallocation of an internally-allocated device memory object or a DeviceMemory.

pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT :: DeviceMemoryReportEventTypeEXT

DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event corresponds to the import of an external memory object.

pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT :: DeviceMemoryReportEventTypeEXT

DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this event is the release of an imported external memory object.

pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT :: DeviceMemoryReportEventTypeEXT

DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies this event corresponds to the failed allocation of an internal device memory object or a DeviceMemory.

Instances

Instances details
Storable DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Read DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Show DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Eq DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Ord DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

Zero DeviceMemoryReportEventTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_device_memory_report

type PFN_vkDeviceMemoryReportCallbackEXT = FunPtr FN_vkDeviceMemoryReportCallbackEXT Source #

PFN_vkDeviceMemoryReportCallbackEXT - Application-defined device memory report callback function

Description

The callback must not make calls to any Vulkan commands.

See Also

VK_EXT_device_memory_report, DeviceDeviceMemoryReportCreateInfoEXT

type FN_vkDeviceMemoryReportCallbackEXT = ("pCallbackData" ::: Ptr DeviceMemoryReportCallbackDataEXT) -> ("pUserData" ::: Ptr ()) -> IO () Source #

type EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME = "VK_EXT_device_memory_report" Source #