[PATCH RFC wayland-protocols] unstable/linux-dmabuf: add wp_linux_dmabuf_device_hint

[Simon Ser]

On multi-GPU setups, multiple devices can be used for rendering. Clients need
hints about the device in use by the compositor. For instance, if they render
on another GPU, then they need to make sure the memory is accessible between
devices and that their buffers are not placed in hidden memory.

This commit introduces a new wp_linux_dmabuf_device_hints object. This object
advertizes a preferred device via a file descriptor and a set of preferred
formats/modifiers.

Each object is bound to a wl_surface and can dynamically update its hints. This
enables fine-grained per-surface optimizations. For instance, when a surface is
scanned out on a GPU the compositor isn't compositing with, the preferred
device can be set to this GPU to avoid unnecessary roundtrips.

Signed-off-by: Simon Ser <contact at emersion.fr>
---

These additions are inspired from [1]. The goal here is to be able to get rid
of wl_drm, enabling more use-cases in the process.

I'm not a DRM/Mesa specialist, so let me know if I've made horrible mistakes.
As always, comments and questions are welcome.

[1]: https://gitlab.freedesktop.org/wayland/wayland/issues/59

 .../linux-dmabuf/linux-dmabuf-unstable-v1.xml | 67 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 2 deletions(-)

diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
index 154afe2..eafb559 100644
--- a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
+++ b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
@@ -24,7 +24,7 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="zwp_linux_dmabuf_v1" version="3">
+  <interface name="zwp_linux_dmabuf_v1" version="4">
     <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
@@ -35,6 +35,9 @@
       the set of supported formats and format modifiers is sent with
       'format' and 'modifier' events.
 
+      Clients can use the get_surface_device_hints request to get dmabuf hints
+      for a particular surface.
+
       The following are required from clients:
 
       - Clients must ensure that either all data in the dma-buf is
@@ -138,9 +141,19 @@
       <arg name="modifier_lo" type="uint"
            summary="low 32 bits of layout modifier"/>
     </event>
+
+    <request name="get_surface_device_hints" since="4">
+      <description summary="get device hints for a surface">
+        This request creates a new wp_linux_dmabuf_device_hints object for the
+        specified wl_surface. This object will deliver hints about dmabuf
+        parameters to use for buffers attached to this surface.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_linux_dmabuf_device_hints_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
   </interface>
 
-  <interface name="zwp_linux_buffer_params_v1" version="3">
+  <interface name="zwp_linux_buffer_params_v1" version="4">
     <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
@@ -345,4 +358,54 @@
 
   </interface>
 
+  <interface name="zwp_linux_dmabuf_device_hints_v1" version="4">
+    <description summary="dmabuf device hints">
+      This object advertizes dmabuf hints for a surface. Such hints include the
+      primary device and the formats that are preferred for this surface.
+
+      These hints are sent once when this object is created and whenever they
+      change. The done event is always sent once after all hints have been sent.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the device hints">
+        Using this request a client can tell the server that it is not going to
+        use the wp_linux_dmabuf_device_hints object anymore.
+      </description>
+    </request>
+
+    <event name="primary_device">
+      <description summary="preferred primary device">
+        This event advertizes the primary device that the server prefers. There
+        is exactly one primary device.
+      </description>
+      <arg name="fd" type="fd" summary="device file descriptor"/>
+    </event>
+
+    <event name="modifier">
+      <description summary="preferred buffer format modifier">
+        This event advertises the formats that the server prefers, along with
+        the modifiers preferred for each format.
+
+        For the definition of the format and modifier codes, see the
+        wp_linux_buffer_params::create request.
+      </description>
+      <arg name="format" type="uint" summary="DRM_FORMAT code"/>
+      <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"/>
+    </event>
+
+    <event name="done">
+      <description summary="all hints have been sent">
+        This event is sent after all properties of a
+        wp_linux_dmabuf_device_hints have been sent.
+
+        This allows changes to the wp_linux_dmabuf_device_hints properties to be
+        seen as atomic, even if they happen via multiple events.
+      </description>
+    </event>
+  </interface>
+
 </protocol>
-- 
2.19.1