Vulkan-Docs/appendices/VK_EXT_external_memory_host.txt

include::meta/VK_EXT_external_memory_host.txt[]

*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

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

=== New Object Types

None.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT
  ** ename:VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT

  * Extending elink:VkExternalMemoryHandleTypeFlagBitsKHR:
  ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_ALLOCATION_BIT_EXT
  ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_HOST_MAPPED_FOREIGN_MEMORY_BIT_EXT

=== New Enums

None.

=== New Structs

  * slink:VkImportMemoryHostPointerInfoEXT
  * slink:VkMemoryHostPointerPropertiesEXT
  * slink:VkPhysicalDeviceExternalMemoryHostPropertiesEXT

=== New Functions

  * flink:vkGetMemoryHostPointerPropertiesEXT

=== Issues

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

RESOLVED: Depends on the implementation.
Applications have to use the new flink:vkGetMemoryHostPointerPropertiesEXT
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's already freed
thus results in undefined: behavior.

4) Is flink:vkMapMemory 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's 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
pname: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 slink:VkExternalMemoryPropertiesKHR.

=== Version History

 * Revision 1, 2017-11-10 (Daniel Rakos)
   - Internal revisions