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

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_external_memory

Contact

• Daniel Rakos @drakos-amd%0A<<Here describe the issue or question you have about the VK_EXT_external_memory_host extension> >

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
• Jason 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

• getMemoryHostPointerPropertiesEXT

New Structures

• MemoryHostPointerPropertiesEXT

• Extending MemoryAllocateInfo:

  • ImportMemoryHostPointerInfoEXT

• Extending PhysicalDeviceProperties2:

  • PhysicalDeviceExternalMemoryHostPropertiesEXT

New Enum Constants

• EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME

• EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION

• Extending ExternalMemoryHandleTypeFlagBits:

  • EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT
  • EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

• Extending StructureType:

  • STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT
  • STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT
  • STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT

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

ImportMemoryHostPointerInfoEXT, MemoryHostPointerPropertiesEXT, PhysicalDeviceExternalMemoryHostPropertiesEXT, getMemoryHostPointerPropertiesEXT

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.

Documentation

getMemoryHostPointerPropertiesEXT

Arguments

:: forall io. MonadIO io

=> Device

device is the logical device that will be importing pHostPointer.

-> ExternalMemoryHandleTypeFlagBits

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

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

pHostPointer is the host pointer to import from.

-> io MemoryHostPointerPropertiesEXT

vkGetMemoryHostPointerPropertiesEXT - Get properties of external memory host pointer

Valid Usage

• handleType must be EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

• pHostPointer must be a pointer aligned to an integer multiple of PhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment
• If handleType is EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pHostPointer must be a pointer to host memory
• If handleType is EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pHostPointer must be a pointer to host mapped foreign memory

Valid Usage (Implicit)

• device must be a valid Device handle

• handleType must be a valid ExternalMemoryHandleTypeFlagBits value
• pMemoryHostPointerProperties must be a valid pointer to a MemoryHostPointerPropertiesEXT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_EXTERNAL_HANDLE

See Also

VK_EXT_external_memory_host, Device, ExternalMemoryHandleTypeFlagBits, MemoryHostPointerPropertiesEXT

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

Valid Usage

• If handleType is not 0, it must be supported for import, as reported in ExternalMemoryProperties

• If handleType is not 0, it must be EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT or EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT
• pHostPointer must be a pointer aligned to an integer multiple of PhysicalDeviceExternalMemoryHostPropertiesEXT::minImportedHostPointerAlignment
• If handleType is EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT, pHostPointer must be a pointer to allocationSize number of bytes of host memory, where allocationSize is the member of the MemoryAllocateInfo structure this structure is chained to
• If handleType is EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT, pHostPointer must be a pointer to allocationSize number of bytes of host mapped foreign memory, where allocationSize is the member of the MemoryAllocateInfo structure this structure is chained to

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT

• handleType must be a valid ExternalMemoryHandleTypeFlagBits value

See Also

VK_EXT_external_memory_host, ExternalMemoryHandleTypeFlagBits, StructureType

Constructors

ImportMemoryHostPointerInfoEXT

Fields

• handleType :: ExternalMemoryHandleTypeFlagBits

  handleType is a ExternalMemoryHandleTypeFlagBits value specifying the handle type.

• hostPointer :: Ptr ()

  pHostPointer is the host pointer to import from.

Instances

Show ImportMemoryHostPointerInfoEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

showsPrec :: Int -> ImportMemoryHostPointerInfoEXT -> ShowS

show :: ImportMemoryHostPointerInfoEXT -> String

showList :: [ImportMemoryHostPointerInfoEXT] -> ShowS

Storable ImportMemoryHostPointerInfoEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

sizeOf :: ImportMemoryHostPointerInfoEXT -> Int

alignment :: ImportMemoryHostPointerInfoEXT -> Int

peekElemOff :: Ptr ImportMemoryHostPointerInfoEXT -> Int -> IO ImportMemoryHostPointerInfoEXT

pokeElemOff :: Ptr ImportMemoryHostPointerInfoEXT -> Int -> ImportMemoryHostPointerInfoEXT -> IO ()

peekByteOff :: Ptr b -> Int -> IO ImportMemoryHostPointerInfoEXT

pokeByteOff :: Ptr b -> Int -> ImportMemoryHostPointerInfoEXT -> IO ()

peek :: Ptr ImportMemoryHostPointerInfoEXT -> IO ImportMemoryHostPointerInfoEXT

poke :: Ptr ImportMemoryHostPointerInfoEXT -> ImportMemoryHostPointerInfoEXT -> IO ()

FromCStruct ImportMemoryHostPointerInfoEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

peekCStruct :: Ptr ImportMemoryHostPointerInfoEXT -> IO ImportMemoryHostPointerInfoEXT

ToCStruct ImportMemoryHostPointerInfoEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

withCStruct :: ImportMemoryHostPointerInfoEXT -> (Ptr ImportMemoryHostPointerInfoEXT -> IO b) -> IO b

pokeCStruct :: Ptr ImportMemoryHostPointerInfoEXT -> ImportMemoryHostPointerInfoEXT -> IO b -> IO b

withZeroCStruct :: (Ptr ImportMemoryHostPointerInfoEXT -> IO b) -> IO b

pokeZeroCStruct :: Ptr ImportMemoryHostPointerInfoEXT -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero ImportMemoryHostPointerInfoEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

zero :: ImportMemoryHostPointerInfoEXT

data MemoryHostPointerPropertiesEXT

VkMemoryHostPointerPropertiesEXT - Properties of external memory host pointer

Description

The value returned by memoryTypeBits must only include bits that identify memory types which are host visible.

Valid Usage (Implicit)

See Also

VK_EXT_external_memory_host, StructureType, getMemoryHostPointerPropertiesEXT

Constructors

MemoryHostPointerPropertiesEXT

Fields

• memoryTypeBits :: Word32

  memoryTypeBits is a bitmask containing one bit set for every memory type which the specified host pointer can be imported as.

Instances

Eq MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

(==) :: MemoryHostPointerPropertiesEXT -> MemoryHostPointerPropertiesEXT -> Bool

(/=) :: MemoryHostPointerPropertiesEXT -> MemoryHostPointerPropertiesEXT -> Bool

Show MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

showsPrec :: Int -> MemoryHostPointerPropertiesEXT -> ShowS

show :: MemoryHostPointerPropertiesEXT -> String

showList :: [MemoryHostPointerPropertiesEXT] -> ShowS

Storable MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

sizeOf :: MemoryHostPointerPropertiesEXT -> Int

alignment :: MemoryHostPointerPropertiesEXT -> Int

peekElemOff :: Ptr MemoryHostPointerPropertiesEXT -> Int -> IO MemoryHostPointerPropertiesEXT

pokeElemOff :: Ptr MemoryHostPointerPropertiesEXT -> Int -> MemoryHostPointerPropertiesEXT -> IO ()

peekByteOff :: Ptr b -> Int -> IO MemoryHostPointerPropertiesEXT

pokeByteOff :: Ptr b -> Int -> MemoryHostPointerPropertiesEXT -> IO ()

peek :: Ptr MemoryHostPointerPropertiesEXT -> IO MemoryHostPointerPropertiesEXT

poke :: Ptr MemoryHostPointerPropertiesEXT -> MemoryHostPointerPropertiesEXT -> IO ()

FromCStruct MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

peekCStruct :: Ptr MemoryHostPointerPropertiesEXT -> IO MemoryHostPointerPropertiesEXT

ToCStruct MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

withCStruct :: MemoryHostPointerPropertiesEXT -> (Ptr MemoryHostPointerPropertiesEXT -> IO b) -> IO b

pokeCStruct :: Ptr MemoryHostPointerPropertiesEXT -> MemoryHostPointerPropertiesEXT -> IO b -> IO b

withZeroCStruct :: (Ptr MemoryHostPointerPropertiesEXT -> IO b) -> IO b

pokeZeroCStruct :: Ptr MemoryHostPointerPropertiesEXT -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero MemoryHostPointerPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

zero :: MemoryHostPointerPropertiesEXT

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

Valid Usage (Implicit)

See Also

VK_EXT_external_memory_host, DeviceSize, StructureType

Constructors

PhysicalDeviceExternalMemoryHostPropertiesEXT

Fields

• minImportedHostPointerAlignment :: DeviceSize

  minImportedHostPointerAlignment is the minimum required alignment, in bytes, for the base address and size of host pointers that can be imported to a Vulkan memory object. The value must be a power of two.

Instances

Eq PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

(==) :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> Bool

(/=) :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> Bool

Show PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

showsPrec :: Int -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> ShowS

show :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> String

showList :: [PhysicalDeviceExternalMemoryHostPropertiesEXT] -> ShowS

Storable PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

sizeOf :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> Int

alignment :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> Int

peekElemOff :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> Int -> IO PhysicalDeviceExternalMemoryHostPropertiesEXT

pokeElemOff :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> Int -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO ()

peekByteOff :: Ptr b -> Int -> IO PhysicalDeviceExternalMemoryHostPropertiesEXT

pokeByteOff :: Ptr b -> Int -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO ()

peek :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO PhysicalDeviceExternalMemoryHostPropertiesEXT

poke :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO ()

FromCStruct PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

peekCStruct :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO PhysicalDeviceExternalMemoryHostPropertiesEXT

ToCStruct PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

withCStruct :: PhysicalDeviceExternalMemoryHostPropertiesEXT -> (Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO b) -> IO b

pokeCStruct :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO b -> IO b

withZeroCStruct :: (Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO b) -> IO b

pokeZeroCStruct :: Ptr PhysicalDeviceExternalMemoryHostPropertiesEXT -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PhysicalDeviceExternalMemoryHostPropertiesEXT

Defined in Vulkan.Extensions.VK_EXT_external_memory_host

Methods

zero :: PhysicalDeviceExternalMemoryHostPropertiesEXT

type EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION = 1

pattern EXT_EXTERNAL_MEMORY_HOST_SPEC_VERSION :: forall a. Integral a => a

type EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME = "VK_EXT_external_memory_host"

pattern EXT_EXTERNAL_MEMORY_HOST_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a