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