DMA-Buf Support in QtWayland for Client Buffers

This post summarized in one sentence: QtWayland’s dev branch gained support for the linux-unstable-dmabuf-v1 protocol (version 3), which allows QtWayland compositors to be used on top of the open-source etnaviv driver and moreover, brings a performance improvement on top of all drivers.

With a Few More Details

Sharing buffers between Wayland clients and the Wayland compositor is a good idea to avoid unnecessary buffer copies. For doing buffer sharing, however, descriptors are needed that explain the client’s buffer memory layout to the compositor (look here for more details about DMA buffer modifiers and look here for more background about buffer sharing). For dealing with this task, there is a Wayland protocol extension called “linux_dmabuf_unstable_v1”, which introduces a communication interfaces between Wayland client and compositor to provide buffers in the form of file handles and to describe them with so-called buffer modifiers, such that the compositor is able to understand the memory organization of the received buffers.

During the hacking hours of last Akademy I started to look into this topic and how to introduce the DMA client buffer handling interface into the QtWayland compositor framework. My main focus for this protocol extension was not on the rendering speed aspect alone though, but to make QtWayland based compositors available on the i.MX6 hardware with the etnaviv open source driver (for details why linux_dmabuf_unstable_v1 is required for this, see this blog post about making Weston compatible with etnaviv).

Fortunately, some initial base work was already done and I had two extremely helpful guys on IRC who I could bother with questions (many thanks to Johan Helsing and Daniel Stone!) After much testing, code improvements and refactorings during the last weeks, mostly by testing the my patch on i.MX6 development boards, the patch finally got into a decent quality to be merged upstream into Qt’s dev branch, which will make the linux-dmabuf-unstable-v1 support available with the Qt 5.13 release. However, I can assure that this patch (with minor changes) works also quite well on Qt 5.10, 5.11 and 5.12 (I tested with all of these version but will not provide support or compatibility patches 😉 ). Also thanks to my employer that I could spent some of my work time to fight memory leaks and to get the patch into a decent quality.

Using linux-dmabuf-unstable-v1 with QtWayland

The protocol extension, which is available in Qt’s dev branch, is opt-in. So the QtWayland compositor must be told explicitly to use DMA buffers. This can be done by setting the following environment variable:

QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=linux-dmabuf-unstable-v1

Please also note that the extension is being built conditionally based on whether the libdrm headers are found or not. In case that the extension is not there (starting the compositor with WAYLAND_DEBUG=1 is a good idea for gaining insights) please have a look into Qt’s configuration logs. Moreover, you want to use Mesa with version of at least 18.1.5 or otherwise to have this patch applied; otherwise surfaces are not properly updated on a buffer change.

In the case that you work on an i.MX6 with etnativ, you also want to use this patch to avoid leaking a buffer every time a client window is destroyed.