| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
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
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Requires
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
Extending
DeviceCreateInfo:Extending
PhysicalDeviceFeatures2,DeviceCreateInfo:
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
- data PhysicalDeviceDeviceMemoryReportFeaturesEXT = PhysicalDeviceDeviceMemoryReportFeaturesEXT {}
- data DeviceDeviceMemoryReportCreateInfoEXT = DeviceDeviceMemoryReportCreateInfoEXT {}
- data DeviceMemoryReportCallbackDataEXT = DeviceMemoryReportCallbackDataEXT {}
- newtype DeviceMemoryReportFlagsEXT = DeviceMemoryReportFlagsEXT Flags
- newtype DeviceMemoryReportEventTypeEXT where
- DeviceMemoryReportEventTypeEXT Int32
- pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT :: DeviceMemoryReportEventTypeEXT
- pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT :: DeviceMemoryReportEventTypeEXT
- pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT :: DeviceMemoryReportEventTypeEXT
- pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT :: DeviceMemoryReportEventTypeEXT
- pattern DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT :: DeviceMemoryReportEventTypeEXT
- type PFN_vkDeviceMemoryReportCallbackEXT = FunPtr FN_vkDeviceMemoryReportCallbackEXT
- type FN_vkDeviceMemoryReportCallbackEXT = ("pCallbackData" ::: Ptr DeviceMemoryReportCallbackDataEXT) -> ("pUserData" ::: Ptr ()) -> IO ()
- type EXT_DEVICE_MEMORY_REPORT_SPEC_VERSION = 2
- pattern EXT_DEVICE_MEMORY_REPORT_SPEC_VERSION :: forall a. Integral a => a
- type EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME = "VK_EXT_device_memory_report"
- pattern EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
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
Constructors
| PhysicalDeviceDeviceMemoryReportFeaturesEXT | |
Fields | |
Instances
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
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
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
Constructors
| DeviceMemoryReportFlagsEXT Flags |
Instances
newtype DeviceMemoryReportEventTypeEXT Source #
VkDeviceMemoryReportEventTypeEXT - Events that can occur on a device memory object
See Also
VK_EXT_device_memory_report,
DeviceMemoryReportCallbackDataEXT
Constructors
| DeviceMemoryReportEventTypeEXT Int32 |
Bundled Patterns
Instances
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_SPEC_VERSION = 2 Source #
pattern EXT_DEVICE_MEMORY_REPORT_SPEC_VERSION :: forall a. Integral a => a Source #
type EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME = "VK_EXT_device_memory_report" Source #
pattern EXT_DEVICE_MEMORY_REPORT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #