From 147617800dd615b72a7449c9fd591ec0c7cf33af Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Mon, 21 Nov 2016 12:09:46 +0200 Subject: [PATCH] doc: start documenting Xwayland MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Cc: Jonas Ådahl Cc: Daniel Stone Signed-off-by: Pekka Paalanen Reviewed-by: Jonas Ådahl --- doc/publican/Makefile.am | 5 +- doc/publican/sources/Wayland.xml | 1 + doc/publican/sources/Xwayland.xml | 170 ++++++++++++++++++ .../sources/images/xwayland-architecture.png | Bin 0 -> 7611 bytes 4 files changed, 175 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/Makefile.am b/doc/publican/Makefile.am index 57728a00..e861fe67 100644 --- a/doc/publican/Makefile.am +++ b/doc/publican/Makefile.am @@ -24,9 +24,11 @@ publican_sources = \ $(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 @@ css_sources = \ 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 2f47f132..0457c15c 100644 --- a/doc/publican/sources/Wayland.xml +++ b/doc/publican/sources/Wayland.xml @@ -11,6 +11,7 @@ + diff --git a/doc/publican/sources/Xwayland.xml b/doc/publican/sources/Xwayland.xml new file mode 100644 index 00000000..a39866f8 --- /dev/null +++ b/doc/publican/sources/Xwayland.xml @@ -0,0 +1,170 @@ + + +%BOOK_ENTITIES; +]> + + X11 Application Support +
+ Introduction + + 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. + + + 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. + + + 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. + + + 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. + +
+
+ Two Modes for Foreign Windows + + In general, windows from a foreign window system can be presented in one + of two ways: rootless and rootful (not rootless). + + + 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. + + + 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. + + + This chapter concentrates on the rootless mode, and ignores the rootful + mode. + +
+
+ Architecture + + A Wayland compositor usually takes care of launching Xwayland. + Xwayland works in cooperation with a Wayland compositor as follows: + +
+ Xwayland architecture diagram + + + + + + + +
+ + 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. + + + 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. + + + 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. + + + 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. + + + 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. + +
+
+ X Window Manager (XWM) + + 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. + + + 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. + +
+ Window identification + + 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. + + + 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. + +
+
+ diff --git a/doc/publican/sources/images/xwayland-architecture.png b/doc/publican/sources/images/xwayland-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..f24dc1837f2e190c9d38719420a844aeb5997efa GIT binary patch literal 7611 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 literal 0 HcmV?d00001