HORIZON HASKELLDocslts/ghc-9.14.x3e2d5682026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 3e2d568 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_EXT_external_memory_host

Name

VK_EXT_external_memory_host - device extension

VK_EXT_external_memory_host

Name String

VK_EXT_external_memory_host

Extension Type

Device extension

Registered Extension Number

179

Revision

1

Ratification Status

Ratified

Extension and Version Dependencies

VK_KHR_external_memory

or

Vulkan Version 1.1

Contact

Other Extension Metadata

Last Modified Date

2017-11-10

IP Status

No known IP claims.

Contributors

  • Jaakko Konttinen, AMD

  • David Mao, AMD

  • Daniel Rakos, AMD

  • Tobias Hector, Imagination Technologies

  • Faith Ekstrand, Intel

  • James Jones, NVIDIA

Description

This extension enables an application to import host allocations and host mapped foreign device memory to Vulkan memory objects.

New Commands

New Structures

New Enum Constants

Issues

1) What memory type has to be used to import host pointers?

RESOLVED: Depends on the implementation. Applications have to use the new getMemoryHostPointerPropertiesEXT command to query the supported memory types for a particular host pointer. The reported memory types may include memory types that come from a memory heap that is otherwise not usable for regular memory object allocation and thus such a heap’s size may be zero.

2) Can the application still access the contents of the host allocation after importing?

RESOLVED: Yes. However, usual synchronization requirements apply.

3) Can the application free the host allocation?

RESOLVED: No, it violates valid usage conditions. Using the memory object imported from a host allocation that is already freed thus results in undefined behavior.

4) Is mapMemory expected to return the same host address which was specified when importing it to the memory object?

RESOLVED: No. Implementations are allowed to return the same address but it is not required. Some implementations might return a different virtual mapping of the allocation, although the same physical pages will be used.

5) Is there any limitation on the alignment of the host pointer and/or size?

RESOLVED: Yes. Both the address and the size have to be an integer multiple of minImportedHostPointerAlignment. In addition, some platforms and foreign devices may have additional restrictions.

6) Can the same host allocation be imported multiple times into a given physical device?

RESOLVED: No, at least not guaranteed by this extension. Some platforms do not allow locking the same physical pages for device access multiple times, so attempting to do it may result in undefined behavior.

7) Does this extension support exporting the new handle type?

RESOLVED: No.

8) Should we include the possibility to import host mapped foreign device memory using this API?

RESOLVED: Yes, through a separate handle type. Implementations are still allowed to support only one of the handle types introduced by this extension by not returning import support for a particular handle type as returned in ExternalMemoryPropertiesKHR.

Version History

  • Revision 1, 2017-11-10 (Daniel Rakos)

    • Internal revisions

See Also

No cross-references are available

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.

  • 5 types
  • 1 value
  • Packagevulkan-3.27
  • Exports8
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_EXT_external_memory_host.hs
valuegetMemoryHostPointerPropertiesEXT
  1. :: MonadIO io
  2. => Device

    device is the logical device that will be importing pHostPointer.

  3. -> ExternalMemoryHandleTypeFlagBits

    handleType is a ExternalMemoryHandleTypeFlagBits value specifying the type of the handle pHostPointer.

  4. -> "hostPointer" ::: Ptr ()

    pHostPointer is the host pointer to import from.

  5. -> io MemoryHostPointerPropertiesEXT
#

vkGetMemoryHostPointerPropertiesEXT - Get properties of external memory host pointer

Valid Usage

Valid Usage (Implicit)

  • device must be a valid Device handle

Return Codes

Success
Failure

See Also

VK_EXT_external_memory_host, Device, ExternalMemoryHandleTypeFlagBits, MemoryHostPointerPropertiesEXT

datadata ImportMemoryHostPointerInfoEXT
#

VkImportMemoryHostPointerInfoEXT - Import memory from a host pointer

Description

Importing memory from a host pointer shares ownership of the memory between the host and the Vulkan implementation. The application can continue to access the memory through the host pointer but it is the application’s responsibility to synchronize device and non-device access to the payload as defined in Host Access to Device Memory Objects.

Applications can import the same payload into multiple instances of Vulkan and multiple times into a given Vulkan instance. However, implementations may fail to import the same payload multiple times into a given physical device due to platform constraints.

Importing memory from a particular host pointer may not be possible due to additional platform-specific restrictions beyond the scope of this specification in which case the implementation must fail the memory import operation with the error code ERROR_INVALID_EXTERNAL_HANDLE_KHR.

Whether device memory objects imported from a host pointer hold a reference to their payload is undefined. As such, the application must ensure that the imported memory range remains valid and accessible for the lifetime of the imported memory object.

Implementations may support importing host pointers for memory types which are not host-visible. In this case, after a successful call to allocateMemory, the memory range imported from pHostPointer must not be accessed by the application until the DeviceMemory has been destroyed. Memory contents for the host memory becomes undefined on import, and is left undefined after the DeviceMemory has been destroyed. Applications must also not access host memory which is mapped to the same physical memory as pHostPointer, but mapped to a different host pointer while the DeviceMemory handle is valid. Implementations running on general-purpose operating systems should not support importing host pointers for memory types which are not host-visible.

Using host pointers to back non-host visible allocations is a platform-specific use case, and applications should not attempt to do this unless instructed by the platform.

Valid Usage

Valid Usage (Implicit)

Structure Chaining

Extends the structure

See Also

VK_EXT_external_memory_host, ExternalMemoryHandleTypeFlagBits, StructureType

Constructors

Instances5Show, Storable, FromCStruct, ToCStruct, Zero
datadata MemoryHostPointerPropertiesEXT
#

VkMemoryHostPointerPropertiesEXT - Properties of external memory host pointer

Description

The value returned by memoryTypeBits should only include bits that identify memory types which are host visible. Implementations may include bits that identify memory types which are not host visible. Behavior for imported pointers of such types is defined by https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#host-memory-import-non-visible-type.

Valid Usage (Implicit)

See Also

VK_EXT_external_memory_host, StructureType, getMemoryHostPointerPropertiesEXT

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceExternalMemoryHostPropertiesEXT
#

VkPhysicalDeviceExternalMemoryHostPropertiesEXT - Structure describing external memory host pointer limits that can be supported by an implementation

Description

If the PhysicalDeviceExternalMemoryHostPropertiesEXT structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

See Also

VK_EXT_external_memory_host, DeviceSize, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero