egl: add initial EGL_MESA_image_dma_buf_export v2.4

At the moment to get an EGL image to a dma-buf file descriptor,
you have to use EGL_MESA_drm_image, and then use libdrm to
convert this to a file descriptor.

This extension just provides an API modelled on EGL_MESA_drm_image,
to return a dma-buf file descriptor.

v2: update spec for new API proposal
add internal queries to get the fourcc back from intel driver.

v2.1: add gallium pieces.

v2.2: add offsets to spec and API, rename fd->fds, stride->strides
in API. rewrite spec a bit more, add some q/a

v2.3:
add modifiers to query interface and 64-bit type for that (Daniel Stone)
specifiy what happens to num fds vs num planes differences. (Chad Versace)

v2.4:
fix grammar (Daniel Stone)

Signed-off-by: Dave Airlie <[email protected]>

1 files changed, 142 insertions, 0 deletions

diff --git a/docs/specs/MESA_image_dma_buf_export.txt b/docs/specs/MESA_image_dma_buf_export.txt
new file mode 100644
index 00000000000..c3794ee3680
--- /dev/null
+++ b/docs/specs/MESA_image_dma_buf_export.txt
@@ -0,0 +1,142 @@
+Name
+
+    MESA_image_dma_buf_export
+
+Name Strings
+
+    EGL_MESA_image_dma_buf_export
+
+Contributors
+
+    Dave Airlie
+
+Contact
+
+    Dave Airlie (airlied 'at' redhat 'dot' com)
+
+Status
+
+    Proposal
+
+Version
+
+    Version 2, Mar 30, 2015
+
+Number
+
+    EGL Extension #not assigned
+
+Dependencies
+
+    Reguires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+    EGL_KHR_base_image is required.
+
+    The EGL implementation must be running on a Linux kernel supporting the
+    dma_buf buffer sharing mechanism.
+
+Overview
+
+    This extension provides entry points for integrating EGLImage with the
+    dma-buf infrastructure.  The extension allows creating a Linux dma_buf
+    file descriptor or multiple file descriptors, in the case of multi-plane
+    YUV image, from an EGLImage.
+
+    It is designed to provide the complementary functionality to EGL_EXT_image_dma_buf_import.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Types
+
+    This is a 64 bit unsigned integer.
+
+    typedef khronos_uint64_t EGLuint64MESA;
+
+
+New Procedures and Functions
+
+    EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
+                                  EGLImageKHR image,
+				  int *fourcc,
+				  int *num_planes,
+				  EGLuint64MESA *modifiers);
+
+    EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
+                                        EGLImageKHR image,
+                                        int *fds,
+				        EGLint *strides,
+					EGLint *offsets);
+
+New Tokens
+
+    None
+
+
+Additions to the EGL 1.4 Specification:
+
+    To mirror the import extension, this extension attempts to return
+    enough information to enable an exported dma-buf to be imported
+    via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token.
+
+    Retrieving the information is a two step process, so two APIs
+    are required.
+
+    The first entrypoint
+       EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
+                                  EGLImageKHR image,
+				  int *fourcc,
+				  int *num_planes,
+				  EGLuint64MESA *modifiers);
+
+    is used to retrieve the pixel format of the buffer, as specified by
+    drm_fourcc.h, the number of planes in the image and the Linux
+    drm modifiers. <fourcc>, <num_planes> and <modifiers> may be NULL,
+    in which case no value is retrieved.
+
+    The second entrypoint retrieves the dma_buf file descriptors,
+    strides and offsets for the image. The caller should pass
+    arrays sized according to the num_planes values retrieved previously.
+    Passing arrays of the wrong size will have undefined results.
+    If the number of fds is less than the number of planes, then
+    subsequent fd slots should contain -1.
+
+        EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
+                                         EGLImageKHR image,
+					 int *fds,
+                                         EGLint *strides,
+                                         EGLint *offsets);
+
+    <fds>, <strides>, <offsets> can be NULL if the infomatation isn't
+    required by the caller.
+
+Issues
+
+1. Should the API look more like an attribute getting API?
+
+ANSWER: No, from a user interface pov, having to iterate across calling
+the API up to 12 times using attribs seems like the wrong solution.
+
+2. Should the API take a plane and just get the fd/stride/offset for that
+   plane?
+
+ANSWER: UNKNOWN,this might be just as valid an API.
+
+3. Does ownership of the file descriptor remain with the app?
+
+ANSWER: Yes, the app is responsible for closing any fds retrieved.
+
+4. If number of planes and number of fds differ what should we do?
+
+ANSWER: Return -1 for the secondary slots, as this avoids having
+to dup the fd extra times to make the interface sane.
+
+Revision History
+
+    Version 2, March, 2015
+        Add a query interface (Dave Airlie)
+    Version 1, June 3, 2014
+        Initial draft (Dave Airlie)
+