[PATCH wayland] doc: start documenting Xwayland

Tue Nov 22 09:58:33 UTC 2016

On Tue, 22 Nov 2016 09:20:48 +0000
Daniel Stone <daniel at fooishbar.org> wrote:

> Hi,
> 

Hi Daniel,

nice comments, I'll revise the patch later. Some replies below.

> 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?

Introduced in the previous paragraph: Wayland window manager; by that I
mean the proper window manager in a Wayland compositor, to
differentiate from the component that acts as a X11 WM, even if you
count XWM as a part of WWM.

Does any better terminology come to mind?

Or is the split between XWM and WWM just a Weston thing?

> >> +<!-- 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.

Right. It's a bit hard to draw the line between the implementation and
the description, since there is and likely ever will be just one
implementation. I would also like to document some implementation
details somewhere (where?).

> >> +    <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).

Yeah, and one problem with rootful Xwayland is that it has no
decorations and is not a usable window by much any standards.

> The rest looks good to me.

As do the comments.

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