[PATCH weston v3 00/36] Head-based output configuration API a.k.a clone mode infrastructure

Pekka Paalanen ppaalanen at gmail.com
Tue Oct 31 11:48:10 UTC 2017

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

Hi all,

this series introduces a head-based output configuration API, which is
a prerequisite for implementing shared-CRTC clone mode. Clone mode
implementation is not part of this series.

The previous posting of this series was the RFC at
I am repeating the main points below.

Compared to the RFC the main changes are:

- All backends are now converted to the new API (DRM backend conversion
  is available in a branch, more on that below.)

- There is a solution to disappearing connectors.

- The design draft wiki document has sequence diagrams for the head-based API
  and has been updated to match the implementation.

- The frontend is now covering the whole API.


I started designing output configuration API changes earlier this year
to accommodate the addition of clone mode to Weston, and in particular a
very specific setup: sharing the DRM CRTC for more than one
encoder/connector. That setup is the cheapest clone mode possible, with
the caveat/feature that the cloned heads all have the exact same video

The Phabricator task tracking the whole effort is:

and there is a design draft at:

	The design overview

For a recap on what kind of clone modes are theoretically possible, I
recommend reading the email quote in T7727.

The new output configuration API has a new object: weston_head. A
weston_head represents a connector/monitor, while weston_output remains
for the CRTC, the active video mode, the framebuffers, the repaint
logic, etc. A libweston user creates a weston_output and attaches at
least one head to it. Additional heads will become clones by sharing the

If sharing the CRTC is not possible, attaching the head or enabling the
output will fail, in which case the user should create another
weston_output to drive the clone head and just specify the desktop area
to show accordingly. (The latter mode of cloning does not currently work
correctly in Weston due to the damage tracking design.)

Atomic configuration over all outputs will likely not be part of the
current effort, but I am keeping it in mind to avoid going the opposite

	Why not simpler?

Introducing weston_head causes quite a lot of churn and code motion, so
why did I not simply add a thing like

	weston_output_clone_output(output1, output2)

and hook it up by sharing the CRTC if possible and fall back to the
"heavy cloning" automatically?

I believe such design would be hard to maintain and use. It is not
obvious which weston_output should be responsible for the repaint
logic. It is possible for the responsible output to get hot-unplugged,
in which case the remaining output should take over the repaint logic.
It is also unclear what weston_output_enable/disable() etc. should do on
each. API-wise it would be possible to e.g. set differing output
scales, so there would need to be code to recognize bad attempts and
more error handling.

If one then sets out to factor out the common bits that are needed
per-CRTC instead of per-connector, you basically end up with the
head-based design but with a confusing API that does not differentiate
between master and slave outputs. The user could not know what actually
happens either, and I imagine in some use cases it would be important
to know if the CRTC-sharing works or not because it has a very big
impact on the performance and the timings (no gen-lock).

IOW, this "simpler" solution would not actually be simpler, even though
it might save a few lines of code in libweston users at first.

	The code

Here is the branch for this patch series:

This patch series does not contain the full migration of the
DRM-backend, because that work was done on top of Daniel's atomic
modesetting series. OTOH, that should make this patch series landable
upstream already, without conflicting badly with the atomic series.

Patches 2-16 introduce the new head-based API while maintaining the old
functionality, allowing frontends and backends to be converted

Patches 17-24 convert the frontends to the new API.

Patches 25-26 clean up the frontend compatiblity code.

Patches 27-29 add sanity checks and fix a bug.

Patches 30-36 migrate the backends to the new API, except for the

The DRM-backend conversion is here:

That branch consists of an arbitrary snapshot of the atomic modesetting
series, this posted series, the DRM-backend conversion, and the final
patch to clean up the remaining compatibility code:

	Regression testing

I have performed regression testing by running be below test procedures
before and after this whole posted series.

headless-backend testing:

$ make -j7 distcheck

x11-backend testing:

$ weston
$ weston --output-count=3
  - close x11 windows one by one
$ weston --fullscreen (equally broken before and after)

Wayland-backend testing:

parent: $ weston --output-count=2 --width=700
(outputs have different height)

weston --use-pixman
weston --use-pixman --fullscreen
weston --use-pixman --output-count=2
weston --use-pixman --sprawl
- close parent outputs one by one

parent: $ weston --output-count=2 --width=700 --shell=fullscreen-shell.so

weston --use-pixman
- close parent outputs one by one

RDP-backend testing:
- none

fbdev-backend testing:

$ weston -Bfbdev-backend.so

DRM-backend testing:

Two outputs plugged in, third unplugged.
1. start Weston, ensure both outputs work
2. unplug one output, ensure remaining output works
3. re-plug the output, ensure both outputs work
4. quit

One output plugged in, the rest unplugged. The plugged-in output is
configured to be off in weston.ini.
1. start Weston, zero outputs, check via remote login weston-info works
2. plug in an output, check it works
3. unplug the output, check weston-info via remote
4. quit blind

As you can see, I have not tested the RDP-backend as I did not know how
to set it up. Everything I did test did not crash or indicate anything
wrong in the logs either before nor after the patch series. There are no
regressions as I could see.

As a standard procedure, I have also ran every single commit through
'make distcheck' without failure.


Pekka Paalanen (36):
  weston: arm SEGV handler earlier
  libweston: introduce weston_head
  libweston: move wl_output to weston_head
  libweston: use head in wl_output global
  libweston: make wl_output point to weston_head
  libweston: refactor weston_mode_switch_finish
  libweston: introduce weston_output::head_list
  libweston: strdup head make, model, serial_number
  cms-colord: find a good head
  libweston: add name to weston_head
  libweston: add weston_head::connected
  libweston: add compositor list of heads
  libweston: add heads_changed hook
  libweston: new head-based output management API
  libweston: add weston_head destroy signal
  libweston: add weston_head_is_device_changed() API
  weston: move weston_output_enable() into callers
  weston: migrate headless to head-based output API
  weston: migrate x11 to head-based output API
  weston: migrate wayland to head-based output API
  weston: migrate fbdev to head-based output API
  weston: migrate RDP to head-based output API
  weston: migrate DRM to head-based output API
  libweston: change windowed_output_api output_create to create_head
  libweston: remove output_pending_signal
  libweston: stop auto-adding the implicit head
  libweston: assert make/model in weston_output_enable()
  libweston: assert current_mode in weston_output_enable()
  libweston: cancel idle_repaint on output destroy
  compositor-headless: migrate to head-based output API
  compositor-rdp: migrate to head-based output API
  compositor-fbdev: make re-enable less drastic
  compositor-fbdev: migrate to head-based output API
  compositor-x11: migrate to head-based output API
  compositor-wayland: strict surface create/destroy
  compositor-wayland: migrate to head-based output API

 compositor/cms-colord.c             |  38 +-
 compositor/main.c                   | 313 +++++++++---
 compositor/weston-screenshooter.c   |   2 +-
 desktop-shell/input-panel.c         |   4 +-
 desktop-shell/shell.c               |   4 +-
 fullscreen-shell/fullscreen-shell.c |   4 +-
 ivi-shell/input-panel-ivi.c         |   4 +-
 libweston-desktop/wl-shell.c        |   2 +-
 libweston-desktop/xdg-shell-v5.c    |   2 +-
 libweston-desktop/xdg-shell-v6.c    |   2 +-
 libweston/compositor-drm.c          |  15 +-
 libweston/compositor-fbdev.c        | 206 +++++---
 libweston/compositor-headless.c     |  75 ++-
 libweston/compositor-rdp.c          |  64 ++-
 libweston/compositor-wayland.c      | 254 +++++++---
 libweston/compositor-x11.c          |  70 ++-
 libweston/compositor.c              | 923 +++++++++++++++++++++++++++++++++---
 libweston/compositor.h              | 182 ++++++-
 libweston/windowed-output-api.h     |  23 +-
 tests/weston-test.c                 |   2 +-
 20 files changed, 1814 insertions(+), 375 deletions(-)


More information about the wayland-devel mailing list