[PATCH wayland] doc: start documenting Xwayland

[Daniel Stone]

Hi,

On 21 November 2016 at 15:06, Pekka Paalanen
<pekka.paalanen at collabora.co.uk> wrote:
> On Mon, 21 Nov 2016 14:31:43 +0200
> Pekka Paalanen <ppaalanen at gmail.com> wrote:
>> +    <para>
>> +      X11 and Wayland are different enough that there is no "simple" way to
>> +      translate between them. Most of X11 is uninteresting to a Wayland
>> +      compositor. That combined with the gigantic implementation effort needed
>> +      to support X11 makes it untractable to just write X11 support directly in

Nit: intractable.

>> +    <para>
>> +      Therefore Wayland compositors should use Xwayland, the X11 server that
>> +      lives in the Xorg server source code repository and shares most of the
>> +      implementation with the Xorg server. Xwayland is a complete X11 server,
>> +      just like Xorg is, but instead of talking to hardware and device drivers,
>> +      it acts as a Wayland client. The rest of this chapter talks about how
>> +      Xwayland works.
>> +    </para>

Hm, Xwayland still talks to hardware when running Glamor; it just
doesn't drive KMS / display controllers directly.

>> +    <para>
>> +      The X11 window manager (XWM) is an integral part of the Wayland
>> +      compositor. XWM uses the usual X11 window management protocol to manage
>> +      all X11 windows in Xwayland. Most importantly, XWM acts as a bridge
>> +      between Xwayland window state and the Wayland compositor's window manager
>> +      (WWM). This way WWM can manage all windows, both native Wayland and X11
>> +      (Xwayland) windows. This is very important for a coherent user
>> +      experience.
>> +    </para>

Probably worth pointing out explicitly that XWM is, like other
windows, a real genuine X11 client. And that this creates a dependency
loop which requires careful handling: Xwayland is a Wayland client of
the compositor, which is an X11 client of Xwayland.

>> +    <para>
>> +      Xwayland uses Wayland core protocol and some extensions for input and
>> +      output. The used protocol is all generic and public, there are no
>> +      Xwayland-specific or private Wayland extensions being used.

This is true, strictly speaking, but maybe misleading by omission as
the WL_SURFACE_ID X11 property is essentially private protocol between
Xwayland and XWM / the compositor. Even without that, I'm not sure we
want to paint ourselves into a corner by disallowing the use of
private protocol in the future.

>> +      Xwayland is
>> +      just a regular Wayland client, except it is specially handled by the WWM.

WWM?

>> +<!-- TBD
>> +  <section id="sect-X11-Application-Support-output">
>> +    <title>Output Characteristics</title>
>> +    <para>
>> +      Output restrictions?
>> +      Absolute window positioning?
>> +      Front buffer rendering?
>> +      Does Xwayland draw to buffers that are reserved by the Wayland compositor?
>> +      GLAMOR?
>> +      Each window drawn to separate off-screen buffer.

Hm, some of these are essentially implementation details (and bugs),
rather than anything conceptual.

>> +    <para>
>> +      There are two separate, asynchronous communication channels between
>> +      Xwayland and a Wayland compositor: one uses the Wayland protocol, and the
>> +      other one solely for XWM uses X11 protocol. This setting demands great
>> +      care from the XWM implementation to avoid (random) deadlocks with
>> +      Xwayland. It is often nearly impossible to prove that synchronous or
>> +      blocking X11 calls from XWM cannot cause a deadlock, and therefore it is
>> +      strongly recommended to make all X11 communications asynchronous. All
>> +      Wayland communications are already asynchonous by design.
>> +    </para>

Oh cool, you do mention this. Still might be worth a small shout in
the intro though.

>> +    <para>
>> +      The Wayland connection carries window content and input events, while the
>> +      X11 connection carries window management messages. This design avoids the
>> +      need to create a Wayland protocol extension specific to Xwayland. It also
>> +      lets Xwayland to be agnostic of any Wayland shell protocols, allowing
>
> ok, I see I lied here. Xwayland does use wl_shell. Not in the usual
> case of rootless operation though.
>
> I see that xwl_realize_window() creates a wl_shell_surface if the
> screen is rootful (not rootless). I assume that means that
> xwl_realize_window() will be called only for the root window in that
> case, and wl_shell allows it to appear on screen.
>
> It does indeed seem to work. Manually starting 'Xwayland :2' brings up
> a black surface, and I can run fluxbox and xterm on DISPLAY=:2, and get
> fluxbox to decorate the xterm.
>
> I wrote the documentation only for the rootless case, it seems. I might
> fix the text to acknowledge the existence of the rootful mode later,
> either as follow-up or revised, depending.
>
> Unless you think the rootful mode should get culled?

I'd be fine with jettisoning it. I don't think anyone uses it, and if
anyone actually wants a rootful X server, I can't imagine a usecase
which would be better served with Xwayland than with Xephyr (X11
client -> Xephyr -> Xwayland -> Wayland, ha).

The rest looks good to me.

Cheers,
Daniel