[PATCH wayland] doc: start documenting Xwayland

Pekka Paalanen pekka.paalanen at collabora.co.uk
Mon Nov 21 15:06:29 UTC 2016


On Mon, 21 Nov 2016 14:31:43 +0200
Pekka Paalanen <ppaalanen at gmail.com> wrote:

> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> 
> This is a rough intro to what Xwayland is and does, with just one
> implementation detail so far (Window identification).
> 
> I paid no attention to formatting details, those can be polished in
> follow-ups. I just want the prose out.
> 
> I also just quickly whacked up the diagram, would be happy to see
> someone replace it with a nicer one. I just didn't have time to learn
> dot for now.
> 
> Cc: Olivier Fourdan <ofourdan at redhat.com>
> Cc: Jonas Ã…dahl <jadahl at gmail.com>
> Cc: Daniel Stone <daniel at fooishbar.org>
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> ---
>  doc/publican/Makefile.am                           |   5 +-
>  doc/publican/sources/Wayland.xml                   |   1 +
>  doc/publican/sources/Xwayland.xml                  | 172 +++++++++++++++++++++
>  .../sources/images/xwayland-architecture.png       | Bin 0 -> 7611 bytes
>  4 files changed, 177 insertions(+), 1 deletion(-)
>  create mode 100644 doc/publican/sources/Xwayland.xml
>  create mode 100644 doc/publican/sources/images/xwayland-architecture.png
> 

> diff --git a/doc/publican/sources/Xwayland.xml b/doc/publican/sources/Xwayland.xml
> new file mode 100644
> index 0000000..ca4025a
> --- /dev/null
> +++ b/doc/publican/sources/Xwayland.xml
> @@ -0,0 +1,172 @@
> +<?xml version='1.0' encoding='utf-8' ?>
> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
> +<!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
> +%BOOK_ENTITIES;
> +]>  
> +<chapter id="chap-X11-Application-Support">
> +  <title>X11 Application Support</title>
> +  <section id="sect-X11-Application-Support-introduction">
> +    <title>Introduction</title>
> +    <para>
> +      Being able to run existing X11 applications is crucial for the adoption
> +      of Wayland, especially on desktops, as there will always be X11
> +      applications that have not been or cannot be converted into Wayland
> +      applications, and throwing them all away would be prohibitive.
> +      Therefore a Wayland compositor often needs to support running X11
> +      applications.
> +    </para>
> +    <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
> +      a Wayland compositor. The implementation would be nothing short from a
> +      real X11 server.
> +    </para>
> +    <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>
> +  </section>
> +  <section id="sect-X11-Application-Support-architecture">
> +    <title>Architecture</title>
> +    <para>
> +      A Wayland compositor usually takes care of launching Xwayland.
> +      Xwayland works in cooperation with a Wayland compositor as follows:
> +    </para>
> +    <figure>
> +      <title>Xwayland architecture diagram</title>
> +      <mediaobjectco>
> +        <imageobjectco>
> +          <imageobject>
> +            <imagedata fileref="images/xwayland-architecture.png" format="PNG" />
> +          </imageobject>
> +        </imageobjectco>
> +      </mediaobjectco>
> +    </figure>
> +    <para>
> +      An X11 application connects to Xwayland just like it would connect to any
> +      X server. Xwayland processes all the X11 requests. On the other end,
> +      Xwayland is a Wayland client that connects to the Wayland compositor.
> +    </para>
> +    <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>
> +    <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. Xwayland is
> +      just a regular Wayland client, except it is specially handled by the WWM.
> +      The special handling is due to XWM replacing all shell protocol
> +      extensions that native Wayland applications use.
> +    </para>
> +    <para>
> +      Since Xwayland uses Wayland for input and output, it does not have any
> +      use for the device drivers that Xorg uses. None of the xf86-video-* or
> +      xf86-input-* modules are used. There also is no configuration file for
> +      the Xwayland server. For optional hardware accelerated rendering,
> +      Xwayland uses GLAMOR.
> +    </para>
> +    <para>
> +      A Wayland compositor usually spawns only one Xwayland instance. This is
> +      because many X11 applications assume they can communicate with other X11
> +      applications through the X server, and this requires a shared X server
> +      instance. This also means, that Xwayland does not protect nor isolate X11
> +      clients from each other, unless the Wayland compositor specifically
> +      chooses to break the X11 client intercommunications by spawning
> +      application specific Xwayland instances. X11 clients are naturally
> +      isolated from Wayland clients though.
> +    </para>
> +    <para>
> +      Xwayland compatibility compared to a native X server will probably never
> +      reach 100%. Desktop environment (DE) components, specifically X11 window
> +      managers, are practically never supported. An X11 window manager would
> +      not know about native Wayland windows, so it could manage only X11
> +      windows. OTOH, there must be an XWM that reserves the exclusive window
> +      manager role so that the Wayland compositor could show the X11 windows
> +      appropriately. For other DE components like pagers and panels adding the
> +      necessary interfaces to support them in WWM through XWM is often
> +      considered not worthwhile.
> +    </para>
> +  </section>
> +<!-- 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.
> +    </para>
> +  </section>
> +  <section id="sect-X11-Application-Support-input">
> +    <title>Input Characteristics</title>
> +    <para>
> +      Input arbitrated by the Wayland compositor, but also by Xwayland?
> +      Careful cooperation...
> +
> +      How X11 pointer warping, confinement etc. are supported?
> +    </para>
> +  </section>
> +-->
> +  <section id="sect-X11-Application-Support-xwm">
> +    <title>X Window Manager (XWM)</title>
> +    <para>
> +      From the X11 point of view, the X window manager (XWM) living inside a
> +      Wayland compositor is just like any other window manager. The difference
> +      is mostly in which process it resides in, and the few extra conventions
> +      in the X11 protocol to support Wayland window management (WWM)
> +      specifically.
> +    </para>
> +    <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>
> +    <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

Hi,

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?


Thanks,
pq

> +      Xwayland to be better integratable in various environments. Also many
> +      Wayland desktop compositors started with an existing X11 window manager,
> +      and this design allows them to use their existing code.
> +    </para>
> +    <section id="sect-X11-Application-Support-xwm-window-identification">
> +      <title>Window identification</title>
> +      <para>
> +        In Xwayland, an X11 window may have a corresponding wl_surface object
> +        in Wayland. The wl_surface object is used for input and output: it is
> +        referenced by input events and used to provide the X11 window content
> +        to the Wayland compositor. The X11 window and the wl_surface live in
> +        different protocol streams, and they need to be matched for XWM to do
> +        its job.
> +      </para>
> +      <para>
> +        When Xwayland creates a wl_surface on Wayland, it will also send an X11
> +        ClientMessage of type atom "WL_SURFACE_ID" to the X11 window carrying
> +        the wl_surface Wayland object ID as the first 32-bit data element. This
> +        is how XWM can associate a wl_surface with an X11 window. Note, that
> +        the request to create a wl_surface and the ID message may arrive in any
> +        order in the Wayland compositor.
> +      </para>
> +    </section>
> +  </section>
> +</chapter>



More information about the wayland-devel mailing list