[PATCH weston v2 1/8] protocol: add linux_dmabuf extension (v2)

Pekka Paalanen ppaalanen at gmail.com
Wed Jul 1 07:56:13 PDT 2015

From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

An experimental (hence the 'z' prefix) linux_dmabuf Wayland protocol
extension for creating dmabuf-based wl_buffers in a generic manner.

This does not include proper dmabuf metadata negotiation because
there is no way to communicate all dmabuf constraints from the
compositor to a client before-hand. The client has to create a
wl_buffer wrapping one or more dmabuf buffers and then listen at
the feedback object returned to know if the operation was successful.

RFCv1 changes (after a first draft without code):
- some renames of interfaces and argument, no semantic changes
- added destructor protocol to dmabuf_batch
- added feedback interface for buffer creation

v2 changes:
- use drm_fourcc.h as authoritative source for format codes
- add support for the 64-bit layout qualifier and y-inverted dmabufs
- simplify the 'add' request (no need to preserve fd numerical id)
- add explicit plane index in the 'add' request
- integrate the 'feedback' object events to the batch interface
- rename 'create_buffer' to 'create' and move it into the batch interface
- add requirements needed from the graphics stack and clients
- improve existing errors and add batch error codes
- removed error codes from the global interface
- improve documentation for arguments, enums, etc.
- rename dmabuf_batch to zlinux_buffer_params
- The y-inverted property makes more sense as a whole buffer property.
  Y-flipping individual planes of the same buffer object is hardly useful.
  The y-invert is also converted into a flag, so we may add more flags
- add flags for interlaced buffer content

Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
Signed-off-by: Louis-Francis Ratté-Boulianne <lfrb at collabora.com>
Reviewed-by: Daniel Stone <daniels at collabora.com>
 Makefile.am               |   7 +-
 protocol/linux-dmabuf.xml | 279 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 284 insertions(+), 2 deletions(-)
 create mode 100644 protocol/linux-dmabuf.xml

diff --git a/Makefile.am b/Makefile.am
index f493d16..50385db 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -107,7 +107,9 @@ nodist_weston_SOURCES =					\
 	protocol/presentation_timing-protocol.c		\
 	protocol/presentation_timing-server-protocol.h	\
 	protocol/scaler-protocol.c			\
-	protocol/scaler-server-protocol.h
+	protocol/scaler-server-protocol.h		\
+	protocol/linux-dmabuf-protocol.c		\
+	protocol/linux-dmabuf-server-protocol.h
 BUILT_SOURCES += $(nodist_weston_SOURCES)
@@ -1242,7 +1244,8 @@ EXTRA_DIST +=					\
 	protocol/presentation_timing.xml	\
 	protocol/scaler.xml			\
 	protocol/ivi-application.xml		\
-	protocol/ivi-hmi-controller.xml
+	protocol/ivi-hmi-controller.xml		\
+	protocol/linux-dmabuf.xml
 # manual test modules in tests subdirectory
diff --git a/protocol/linux-dmabuf.xml b/protocol/linux-dmabuf.xml
new file mode 100644
index 0000000..efa619d
--- /dev/null
+++ b/protocol/linux-dmabuf.xml
@@ -0,0 +1,279 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="linux_dmabuf">
+  <copyright>
+    Copyright © 2014, 2015 Collabora, Ltd.
+    Permission to use, copy, modify, distribute, and sell this
+    software and its documentation for any purpose is hereby granted
+    without fee, provided that the above copyright notice appear in
+    all copies and that both that copyright notice and this permission
+    notice appear in supporting documentation, and that the name of
+    the copyright holders not be used in advertising or publicity
+    pertaining to distribution of the software without specific,
+    written prior permission.  The copyright holders make no
+    representations about the suitability of this software for any
+    purpose.  It is provided "as is" without express or implied
+    warranty.
+  </copyright>
+  <interface name="zlinux_dmabuf" version="1">
+    <description summary="factory for creating dmabuf-based wl_buffers">
+      Following the interfaces from:
+      https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt
+      and the Linux DRM sub-system's AddFb2 ioctl.
+      This interface offers a way to create generic dmabuf-based
+      wl_buffers. Immediately after a client binds to this interface,
+      the set of supported formats is sent with 'format' events.
+      Clients must ensure the buffer is coherent with respect to all possible
+      consumers before use. The following steps are needed:
+      - Create a new buffer, or wait until existing buffer has been released.
+      - Write pixel data to buffer (e.g. V4L2 queue and dequeue)
+      - Make platform-specific call to ensure that caches are flushed, such
+        that access with GPU / display controller / CPU will be coherent, if
+        read-side caches are flushed on those devices (which is explicitly
+        the compositor's responsibility).
+      - Don't make any more attachments after sending the buffer to the
+        compositor. Making more attachments later increases the risk of
+        the compositor not being able to use (re-import) an existing
+        dmabuf-based wl_buffer.
+      The underlying graphics stack must ensure the following:
+      - The dmabuf file descriptors relayed to the server will stay valid
+        for the whole lifetime of the wl_buffer. This means the server may
+        at any time use those fds to import the dmabuf into any kernel
+        sub-system that might accept it.
+      To create a wl_buffer from one or more dmabufs, a client creates a
+      zlinux_dmabuf_params object with zlinux_dmabuf.create_params
+      request. All planes required by the intended format are added with
+      the 'add' request. Finally, 'create' request is issued. The server
+      will reply with either 'created' event which provides the final
+      wl_buffer or 'failed' event saying that it cannot use the dmabufs
+      provided.
+    </description>
+    <request name="destroy" type="destructor">
+      <description summary="unbind the factory">
+        Objects created through this interface, especially wl_buffers, will
+        remain valid.
+      </description>
+    </request>
+    <request name="create_params">
+      <description summary="create a temporary object for buffer parameters">
+        This temporary object is used to collect multiple dmabuf handles into
+        a single batch to create a wl_buffer. It can only be used once and
+        should be destroyed after an 'created' or 'failed' event has been
+        received.
+      </description>
+      <arg name="params_id" type="new_id" interface="zlinux_buffer_params"
+           summary="the new temporary"/>
+    </request>
+    <event name="format">
+      <description summary="supported buffer format">
+        This event advertises one buffer format that the server supports.
+        All the supported formats are advertised once when the client
+        binds to this interface. A roundtrip after binding guarantees,
+        that the client has received all supported formats.
+        For the definition of the format codes, see create request.
+        XXX: Can a compositor ever enumerate them?
+      </description>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+    </event>
+  </interface>
+  <interface name="zlinux_buffer_params" version="1">
+    <description summary="parameters for creating a dmabuf-based wl_buffer">
+      This temporary object is a collection of dmabufs and other
+      parameters that together form a single logical buffer. The temporary
+      object may eventually create one wl_buffer unless cancelled by
+      destroying it before requesting 'create'.
+      Single-planar formats only require one dmabuf, however
+      multi-planar formats may require more than one dmabuf. For all
+      formats, 'add' request must be called once per plane (even if the
+      underlying dmabuf fd is identical).
+      You must use consecutive plane indices ('plane_idx' argument for 'add')
+      from zero to the number of planes used by the drm_fourcc format code.
+      All planes required by the format must be given exactly once, but can
+      be given in any order. Each plane index can be set only once.
+    </description>
+    <enum name="error">
+      <entry name="already_used" value="0"
+             summary="the dmabuf_batch object has already been used to create a wl_buffer"/>
+      <entry name="plane_idx" value="1"
+             summary="plane index out of bounds"/>
+      <entry name="plane_set" value="2"
+             summary="the plane index was already set"/>
+      <entry name="incomplete" value="3"
+             summary="missing or too many planes to create a buffer"/>
+      <entry name="invalid_format" value="4"
+             summary="format not supported"/>
+      <entry name="invalid_dimensions" value="5"
+             summary="invalid width or height"/>
+      <entry name="out_of_bounds" value="6"
+             summary="offset + stride * height goes out of dmabuf bounds"/>
+    </enum>
+    <request name="destroy" type="destructor">
+      <description summary="delete this object, used or not">
+        Cleans up the temporary data sent to the server for dmabuf-based
+        wl_buffer creation.
+      </description>
+    </request>
+    <request name="add">
+      <description summary="add a dmabuf to the temporary set">
+        This request adds one dmabuf to the set in this zlinux_buffer_params.
+        The 64-bit unsigned value combined from modifier_hi and modifier_lo
+        is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the
+        fb modifier, which is defined in drm_mode.h of Linux UAPI.
+        This is an opaque token. Drivers use this token to express tiling,
+        compression, etc. driver-specific modifications to the base format
+        defined by the DRM fourcc code.
+        This request raises the PLANE_IDX error if plane_idx is too large.
+        The error PLANE_SET is raised if attempting to set a plane that
+        was already set.
+      </description>
+      <arg name="fd" type="fd" summary="dmabuf fd"/>
+      <arg name="plane_idx" type="uint" summary="plane index"/>
+      <arg name="offset" type="uint" summary="offset in bytes"/>
+      <arg name="stride" type="uint" summary="stride in bytes"/>
+      <arg name="modifier_hi" type="uint"
+           summary="high 32 bits of layout modifier"/>
+      <arg name="modifier_lo" type="uint"
+           summary="low 32 bits of layout modifier"/>
+    </request>
+    <enum name="flags">
+      <entry name="y_invert" value="1" summary="contents are y-inverted"/>
+      <entry name="interlaced" value="2" summary="content is interlaced"/>
+      <entry name="bottom_first" value="4" summary="bottom field first"/>
+    </enum>
+    <request name="create">
+      <description summary="create a wl_buffer from the given dmabufs">
+        This asks for creation of a wl_buffer from the added dmabuf
+        buffers. The wl_buffer is not created immediately but returned via
+        the 'created' event if the dmabuf sharing succeeds. The sharing
+        may fail at runtime for reasons a client cannot predict, in
+        which case the 'failed' event is triggered.
+        The 'format' argument is a DRM_FORMAT code, as defined by the
+        libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the
+        authoritative source on how the format codes should work.
+        The 'flags' is a bitfield of the flags defined in enum "flags".
+        'y_invert' means the that the image needs to be y-flipped.
+        Flag 'interlaced' means that the frame in the buffer is not
+        progressive as usual, but interlaced. An interlaced buffer as
+        supported here must always contain both top and bottom fields.
+        The top field always begins on the first pixel row. The temporal
+        ordering between the two fields is top field first, unless
+        'bottom_first' is specified. It is undefined whether 'bottom_first'
+        is ignored if 'interlaced' is not set.
+        This protocol does not convey any information about field rate,
+        duration, or timing, other than the relative ordering between the
+        two fields in one buffer. A compositor may have to estimate the
+        intended field rate from the incoming buffer rate. It is undefined
+        whether the time of receiving wl_surface.commit with a new buffer
+        attached, applying the wl_surface state, wl_surface.frame callback
+        trigger, presentation, or any other point in the compositor cycle
+        is used to measure the frame or field times. There is no support
+        for detecting missed or late frames/fields/buffers either, and
+        there is no support whatsoever for cooperating with interlaced
+        compositor output.
+        The composited image quality resulting from the use of interlaced
+        buffers is explicitly undefined. A compositor may use elaborate
+        hardware features or software to deinterlace and create progressive
+        output frames from a sequence of interlaced input buffers, or it
+        may produce substandard image quality. However, compositors that
+        cannot guarantee reasonable image quality in all cases are recommended
+        to just reject all interlaced buffers.
+        Any argument errors, including non-positive width or height,
+        mismatch between the number of planes and the format, bad
+        format, bad offset or stride, may be indicated by fatal protocol
+        OUT_OF_BOUNDS.
+        Dmabuf import errors in the server that are not obvious client
+        bugs are returned via the 'failed' event as non-fatal. This
+        allows attempting dmabuf sharing and falling back in the client
+        if it fails.
+        This request can be sent only once in the object's lifetime, after
+        which the only legal request is destroy. This object should be
+        destroyed after issuing 'create' request. Attempting to use this
+        object after issuing 'create' raises ALREADY_USED protocol error.
+        It is not mandatory to issue 'create'. If a client wants to
+        cancel the buffer creation, it can just destroy this object.
+      </description>
+      <arg name="width" type="int" summary="base plane width in pixels"/>
+      <arg name="height" type="int" summary="base plane height in pixels"/>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <arg name="flags" type="uint" summary="see enum flags"/>
+    </request>
+    <event name="created">
+      <description summary="buffer creation succeeded">
+        This event indicates that the attempted buffer creation was
+        successful. It provides the new wl_buffer referencing the dmabuf(s).
+        Upon receiving this event, the client should destroy the
+        zlinux_dmabuf_params object.
+      </description>
+      <arg name="buffer" type="new_id" interface="wl_buffer"
+           summary="the newly created wl_buffer"/>
+    </event>
+    <event name="failed">
+      <description summary="buffer creation failed">
+        This event indicates that the attempted buffer creation has
+        failed. It usually means that one of the dmabuf constraints
+        has not been fulfilled.
+        Upon receiving this event, the client should destroy the
+        zlinux_buffer_params object.
+      </description>
+    </event>
+  </interface>

More information about the wayland-devel mailing list