[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