doc: start documenting Xwayland
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.
v2:
- typo fix
- rephrase "talking to hardware" as "driving the displays"
- mention circular dependency in intro
- add section to explain rootless and rootful modes
- remove paragraph about Xwayland protocol usage
- move TBD part to the end under a new section header
v3:
- use "advantage" and "disadvantage" instead of "pro" and "con"
- slight rewording on rootful mode and rootless mode paragraphs
- removed the paragraph about the lack of shell and special Wayland
protocol extensions
- removed the commented out list of ideas to write
v4:
- typo fixes pointed out by Yong
Cc: Olivier Fourdan <ofourdan@redhat.com>
Cc: Jonas Ådahl <jadahl@gmail.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
index 57728a0..e861fe6 100644
--- a/doc/publican/Makefile.am
+++ b/doc/publican/Makefile.am
@@ -24,9 +24,11 @@
$(srcdir)/sources/Preface.xml \
$(srcdir)/sources/Revision_History.xml \
$(srcdir)/sources/Protocol.xml \
+ $(srcdir)/sources/Xwayland.xml \
$(srcdir)/sources/Compositors.xml \
$(srcdir)/sources/images/icon.svg \
$(srcdir)/sources/images/wayland.png \
+ $(srcdir)/sources/images/xwayland-architecture.png \
$(srcdir)/sources/Client.xml \
$(srcdir)/sources/Server.xml
@@ -43,7 +45,8 @@
img_sources = \
$(srcdir)/sources/images/icon.svg \
- $(srcdir)/sources/images/wayland.png
+ $(srcdir)/sources/images/wayland.png \
+ $(srcdir)/sources/images/xwayland-architecture.png
doxygen_img_sources := \
$(doxydir)/xml/wayland-architecture.png \
diff --git a/doc/publican/sources/Wayland.xml b/doc/publican/sources/Wayland.xml
index 2f47f13..0457c15 100644
--- a/doc/publican/sources/Wayland.xml
+++ b/doc/publican/sources/Wayland.xml
@@ -11,6 +11,7 @@
<xi:include href="Compositors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Protocol.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Xwayland.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ProtocolSpec.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
diff --git a/doc/publican/sources/Xwayland.xml b/doc/publican/sources/Xwayland.xml
new file mode 100644
index 0000000..a39866f
--- /dev/null
+++ b/doc/publican/sources/Xwayland.xml
@@ -0,0 +1,170 @@
+<?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 intractable to just write X11 support directly in
+ a Wayland compositor. The implementation would be nothing short of 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 driving the displays and opening input
+ devices, it acts as a Wayland client. The rest of this chapter talks
+ about how Xwayland works.
+ </para>
+ <para>
+ For integration and architecture reasons, while Xwayland is a Wayland
+ client of the Wayland compositor, the Wayland compositor is an X11 client
+ of Xwayland. This circular dependency requires special care from the
+ Wayland compositor.
+ </para>
+ </section>
+ <section id="sect-X11-Application-Support-two-modes">
+ <title>Two Modes for Foreign Windows</title>
+ <para>
+ In general, windows from a foreign window system can be presented in one
+ of two ways: rootless and rootful (not rootless).
+ </para>
+ <para>
+ In rootful mode, the foreign window system as a whole is represented as a
+ window (or more) of its own. You have a native window, inside which all
+ the foreign windows are. The advantage of this approach in Xwayland's
+ case is that you can run your favourite X11 window manager to manage your
+ X11 applications. The disadvantage is that the foreign windows do not
+ integrate with the native desktop. Therefore this mode is not usually
+ used.
+ </para>
+ <para>
+ In rootless mode, each foreign window is a first-class resident among the
+ native windows. Foreign windows are not confined inside a native window
+ but act as if they were native windows. The advantage is that one can
+ freely stack and mix native and foreign windows, which is not possible in
+ rootful mode. The disadvantage is that this mode is harder to implement
+ and fundamental differences in window systems may prevent some things
+ from working. With rootless Xwayland, the Wayland compositor must take
+ the role as the X11 window manager, and one cannot use any other X11
+ window manager in its place.
+ </para>
+ <para>
+ This chapter concentrates on the rootless mode, and ignores the rootful
+ mode.
+ </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>
+ 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.
+ </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. On the other hand, 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>
+ <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>
+ <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>
diff --git a/doc/publican/sources/images/xwayland-architecture.png b/doc/publican/sources/images/xwayland-architecture.png
new file mode 100644
index 0000000..f24dc18
--- /dev/null
+++ b/doc/publican/sources/images/xwayland-architecture.png
Binary files differ
