Vulkan-Docs/appendices/VK_EXT_external_memory_host...

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
Change log for November 27, 2017 Vulkan 1.0.66 spec update: * Bump API patch number and header version number to 66 for this update. Github Issues: * Clarified how and when ename:VK_ERROR_TOO_MANY_OBJECTS is generated in flink:vkAllocate Memory, and remove incorrect valid usage statement about exceeding the API limit (public issue 356). * Minor clarification of the description of flink:vkUpdateDescriptorSetWithTemplateKHR::pname:descriptorUpdateTemplate (public issue 564). * Minor fixes for flink:vkCmdSetViewportWScalingNV (public pull request 588). * Fix random name markup issues (public pull request 603). * Fix code:BuiltIn decoration typo in the <<fxvertex-attrib, Vertex Attributes>> section (public pull request 606). * Fix synchronization language following the definition of flink:vkAcquireNextImageKHR (public issue 607). * Restore descriptions of several commands and structures missing from the generated spec due to a mistyped asciidoctor conditional (public issue 612). * Fix 1.0.41 changelog to refer to public issues 403/404 (public issue 618). Internal Issues: * Refactor valid usage statements with internal conditionals in `copies.txt`, `pipelines.txt`, `renderpass.txt`, and `resources.txt` so each branch of the conditional appears as a standalone statement which can contain a separate VUID. This should have no impact on the generated specs, but is necessary given the present state of the VU extractor and the validation layer code that consumes them (internal issue 1043). * Fix VkQueueGlobalPriorityEXT enum values missing _EXT suffix (internal issue 1045). * Clarified initial ownership of resources bound to shared memory objects, (internal issue 1068). * Fix duplicated valid usage ID tag for flink:vkCmdCopyImage, and make the required layouts include ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIONAL in both cases (internal issue 1084). Other Issues: * Remove the noise functions from GLSL for SPIR-V for Vulkan in the `GL_KHR_vulkan_glsl.txt` extension. New Extensions: * `VK_EXT_external_memory_host` * `VK_EXT_external_memory_dma_buf` * `VK_EXT_queue_family_foreign` 2017-11-27 09:07:06 +00:00			`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`