[RFC libweston] Head-based output configuration API a.k.a clone mode infrastructure

[Pekka Paalanen]

Hi,

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
timings.

I now have a libweston public API draft written in code, which is why I
am sending this announcement.

The Phabricator task tracking the whole effort is:
https://phabricator.freedesktop.org/T7727

and there is a design draft at:
https://phabricator.freedesktop.org/w/wayland/weston/atomic-output-config/

I have not followed my draft exactly so far. I have not introduced
weston_canvas to replace weston_output, and I suspect I never will as
it seems to be just lots of renaming without benefits. Also the API
I ended up writing does not follow the draft on all points.


	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 CRTC. 

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
direction.


	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:
https://git.collabora.com/cgit/user/pq/weston.git/log/?h=clonemode-user-API-1

Mind, that there is an arbitrary version of Daniel's atomic modesetting
series before my work. I expect to have to make changes in the
DRM-backend, and the atomic modesetting will land before clone mode
anyway, so I have been working on top of it.

I want to highlight a few commits there:

https://git.collabora.com/cgit/user/pq/weston.git/commit/?h=clonemode-user-API-1&id=b0a5d3db4e9f03c9d6f70d68095439fe81b4de1c
and the following introduce weston_head.

https://git.collabora.com/cgit/user/pq/weston.git/commit/?h=clonemode-user-API-1&id=8a511ce3f2812f69bcd81d8c6169e190d740699e
introduces the new way to react to hotplug events.

https://git.collabora.com/cgit/user/pq/weston.git/commit/?h=clonemode-user-API-1&id=dbc0e54e955e3e5385188e587061e5e156ec800c
introduces the new way of creating and destroying outputs.

https://git.collabora.com/cgit/user/pq/weston.git/commit/?h=clonemode-user-API-1&id=13b233a18d62bc5ca8150cb8ae86b0332375954c
shows what a simple user implementation using the new API will look
like. Eventually the DRM frontend will be using it's own code instead
of this to offer all the clone mode options.

Notice, how the new API will make it possible to force-enable
disconnected connectors. (This is another corner-case I have needed in
the wild.)

If you look at the code in libweston, you will see that the public API
is all actually a fake for now, but it does work (well, should, I
haven't tested much). I have internally embedded a weston_head in
weston_output and just fiddle with those instead of actually
implementing the premise of the new API.

Obviously my next steps will be to implement the premise of the new API
and make it possible to attach more than one head to an output. Then I
can also delete the head embedded in weston_output as it is only a
temporary support for backends that have not been migrated yet.


Comments on the design and the public API are warmly welcome. The code
written so far should be runnable but the libweston internals are
dotted with temporary hacks just to allow migrating everything in small
steps and I will have to rebase this anyway, so reviewing the
implementation is probably not that useful yet.

As usual, every single commit has been designed with the intention to
not regress anything, library ABI breaks notwithstanding.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170818/e11cfa4d/attachment-0001.sig>