VK_EXT_external_memory_dma_buf: New extension1.0-VK_EXT_external_memory_dma_buf

6 files changed, 109 insertions, 7 deletions

diff --git a/doc/specs/vulkan/appendices/VK_EXT_external_memory_dma_buf.txt b/doc/specs/vulkan/appendices/VK_EXT_external_memory_dma_buf.txt
new file mode 100644
index 0000000..47bfa82
--- /dev/null
+++ b/doc/specs/vulkan/appendices/VK_EXT_external_memory_dma_buf.txt
@@ -0,0 +1,56 @@
+// Copyright (c) 2016-2017 Khronos Group. This work is licensed under a
+// Creative Commons Attribution 4.0 International License; see
+// http://creativecommons.org/licenses/by/4.0/
+
+include::meta/VK_EXT_external_memory_dma_buf.txt[]
+
+*Last Modified Date*::
+    2017-10-10
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Chad Versace, Google
+  - James Jones, NVIDIA
+  - Jason Ekstrand, Intel
+
+A dma_buf is a type of file descriptor, defined by the Linux kernel, that
+allows sharing memory across kernel device drivers and across processes.
+This extension enables applications to import a dma_buf as
+slink:VkDeviceMemory; to export slink:VkDeviceMemory as a dma_buf; and to
+create slink:VkBuffer objects that can: be bound to that memory.
+
+=== New Enum Constants
+
+  * Extending elink:VkExternalMemoryHandleTypeFlagBitsKHR:
+  ** ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT
+
+=== Issues
+
+1. How does the application, when creating a slink:VkImage that it intends to bind to
+   dma_buf-backed slink:VkDeviceMemory that contains an externally produced image, specify
+   the memory layout (such as row pitch and DRM format modifier) of the slink:VkImage?
+   In other words, how does the application achieve behavior comparable to that provided by
+   https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] and
+   https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers]?
++
+--
+*RESOLVED*.  Features comparable to those in
+https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] and
+https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers]
+will be provided by an extension layered atop this one, tentatively named +VK_EXT_image_drm_format_modifier+.
+--
+
+2. Without the ability to specify the memory layout of external dma_buf images,
+   how is this extension useful?
++
+--
+*RESOLVED*.  This extension provides exactly one new feature: the ability to
+import/export between dma_bufs and slink:VkDeviceMemory. This feature, together
+with features provided by <<VK_KHR_external_memory_fd>>, is sufficient to bind
+a slink:VkBuffer to dma_buf.
+--
+
+=== Version History
+
+  * Revision 1.0, 2017-10-10 (Chad Versace)
+    - Squashed internal revisions
diff --git a/doc/specs/vulkan/appendices/extensions.txt b/doc/specs/vulkan/appendices/extensions.txt
index b2560a2..e431f5b 100644
--- a/doc/specs/vulkan/appendices/extensions.txt
+++ b/doc/specs/vulkan/appendices/extensions.txt
@@ -290,6 +290,10 @@ ifdef::VK_EXT_display_surface_counter[]
 include::VK_EXT_display_surface_counter.txt[]
 endif::VK_EXT_display_surface_counter[]
 
+ifdef::VK_EXT_external_memory_dma_buf[]
+include::VK_EXT_external_memory_dma_buf.txt[]
+endif::VK_EXT_external_memory_dma_buf[]
+
 ifdef::VK_EXT_global_priority[]
 include::VK_EXT_global_priority.txt[]
 endif::VK_EXT_global_priority[]
diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt
index 4e04fcd..1245a1a 100644
--- a/doc/specs/vulkan/chapters/features.txt
+++ b/doc/specs/vulkan/chapters/features.txt
@@ -5220,9 +5220,8 @@ If pname:handleType is 0, flink:vkGetPhysicalDeviceImageFormatProperties2KHR
 will behave as if slink:VkPhysicalDeviceExternalImageFormatInfoKHR was not
 present, and slink:VkExternalImageFormatPropertiesKHR will be ignored.
 
-If pname:handleType is not compatible with the pname:format, pname:type,
-pname:tiling, pname:usage, and pname:flags specified in
-slink:VkPhysicalDeviceImageFormatInfo2KHR, then
+If pname:handleType is not compatible with the parameters specified in
+slink:VkPhysicalDeviceImageFormatInfo2KHR and its pname:pNext chain, then
 flink:vkGetPhysicalDeviceImageFormatProperties2KHR returns
 ename:VK_ERROR_FORMAT_NOT_SUPPORTED.
 
@@ -5281,6 +5280,12 @@ include::../api/enums/VkExternalMemoryHandleTypeFlagBitsKHR.txt[]
     NT handle returned by code:ID3D12Device::code:CreateSharedHandle
     referring to a Direct3D 12 committed resource.
     It owns a reference to the memory used by the Direct3D resource.
+ifdef::VK_EXT_external_memory_dma_buf[]
+  * ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT is a file
+    descriptor for a Linux dma_buf.
+    It owns a reference to the underlying memory resource represented by
+    its Vulkan memory object.
+endif::VK_EXT_external_memory_dma_buf[]
 
 <<<
 
@@ -5299,8 +5304,25 @@ following table:
 | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR | Must match | Must match
 | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR | Must match | Must match
 | ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR | Must match | Must match
+ifdef::VK_EXT_external_memory_dma_buf[]
+| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT | No restriction | No restriction
+endif::VK_EXT_external_memory_dma_buf[]
 |====
 
+ifdef::VK_EXT_external_memory_dma_buf[]
+[NOTE]
+.Note
+====
+Even though the above table does not restrict the drivers and devices with
+which ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT may: be shared,
+query mechanisms exist in the Vulkan API that prevent the import of
+incompatible dma-bufs (such as flink:vkGetMemoryFdPropertiesKHR) and that prevent
+incompatible usage of dma-bufs (such
+slink:VkPhysicalDeviceExternalBufferInfoKHR and
+slink:VkPhysicalDeviceExternalImageFormatInfoKHR).
+====
+endif::VK_EXT_external_memory_dma_buf[]
+
 --
 
 [open,refpage='VkExternalImageFormatPropertiesKHR',desc='Structure specifying supported external handle properties',type='structs']
diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt
index 68e968f..6d46ee7 100644
--- a/doc/specs/vulkan/chapters/memory.txt
+++ b/doc/specs/vulkan/chapters/memory.txt
@@ -1470,6 +1470,18 @@ pname:handleType.
 See elink:VkExternalMemoryHandleTypeFlagBitsKHR for a description of the
 properties of the defined external memory handle types.
 
+ifdef::VK_EXT_external_memory_dma_buf[]
+[NOTE]
+.Note
+====
+The size of the exported file may: be larger than the size requested by
+slink:VkMemoryAllocateInfo::allocationSize. If pname:handleType is
+ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT, then the application can:
+query the file's actual size with link:man:lseek(2)[lseek(2)].
+====
+endif::VK_EXT_external_memory_dma_buf[]
+
+
 .Valid Usage
 ****
   * [[VUID-vkGetMemoryFdKHR-handleType-00671]]
@@ -1505,7 +1517,8 @@ include::../api/protos/vkGetMemoryFdPropertiesKHR.txt[]
     pname:fd must: be an external memory handle created outside of the
     Vulkan API.
   * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]]
-    pname:handleType must: not be one of the handle types defined as opaque.
+    pname:handleType must: not be
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT_KHR.
 ****
 
 include::../validity/protos/vkGetMemoryFdPropertiesKHR.txt[]
diff --git a/src/spec/vk.xml b/src/spec/vk.xml
index f2f93b2..b812678 100644
--- a/src/spec/vk.xml
+++ b/src/spec/vk.xml
@@ -6940,10 +6940,11 @@ private version is maintained in the 1.0 branch of the member gitlab server.
                 <enum value="&quot;VK_MVK_moltenvk&quot;"               name="VK_MVK_MOLTENVK_EXTENSION_NAME"/>
             </require>
         </extension>
-        <extension name="VK_MESA_extension_126" number="126" author="MESA" contact="Chad Versace @chadversary" supported="disabled">
+        <extension name="VK_EXT_external_memory_dma_buf" number="126" type="device" requires="VK_KHR_external_memory_fd" author="EXT" contact="Chad Versace @chadversary" supported="vulkan">
             <require>
-                <enum value="0"                                         name="VK_MESA_EXTENSION_126_SPEC_VERSION"/>
-                <enum value="&quot;VK_MESA_extension_126&quot;"         name="VK_MESA_EXTENSION_126_EXTENSION_NAME"/>
+                <enum value="1"                                                  name="VK_EXT_EXTERNAL_MEMORY_DMA_BUF_SPEC_VERSION"/>
+                <enum value="&quot;VK_EXT_external_memory_dma_buf&quot;"         name="VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME"/>
+                <enum bitpos="7" extends="VkExternalMemoryHandleTypeFlagBitsKHR" name="VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT"/>
             </require>
         </extension>
         <extension name="VK_MESA_extension_127" number="127" author="MESA" contact="Chad Versace @chadversary" supported="disabled">
diff --git a/src/vulkan/vulkan.h b/src/vulkan/vulkan.h
index 8e21042..30aa826 100644
--- a/src/vulkan/vulkan.h
+++ b/src/vulkan/vulkan.h
@@ -4195,6 +4195,7 @@ typedef enum VkExternalMemoryHandleTypeFlagBitsKHR {
     VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT_KHR = 0x00000010,
     VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_HEAP_BIT_KHR = 0x00000020,
     VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT_KHR = 0x00000040,
+    VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT = 0x00000080,
     VK_EXTERNAL_MEMORY_HANDLE_TYPE_FLAG_BITS_MAX_ENUM_KHR = 0x7FFFFFFF
 } VkExternalMemoryHandleTypeFlagBitsKHR;
 typedef VkFlags VkExternalMemoryHandleTypeFlagsKHR;
@@ -6616,6 +6617,11 @@ VKAPI_ATTR VkResult VKAPI_CALL vkCreateMacOSSurfaceMVK(
 #endif
 #endif /* VK_USE_PLATFORM_MACOS_MVK */
 
+#define VK_EXT_external_memory_dma_buf 1
+#define VK_EXT_EXTERNAL_MEMORY_DMA_BUF_SPEC_VERSION 1
+#define VK_EXT_EXTERNAL_MEMORY_DMA_BUF_EXTENSION_NAME "VK_EXT_external_memory_dma_buf"
+
+
 #define VK_EXT_sampler_filter_minmax 1
 #define VK_EXT_SAMPLER_FILTER_MINMAX_SPEC_VERSION 1
 #define VK_EXT_SAMPLER_FILTER_MINMAX_EXTENSION_NAME "VK_EXT_sampler_filter_minmax"