Home 🏠

Wayland Basics

2023-05-19 – #Linux #Desktop

Vocabulary
Intro (Problems with Xorg)
Wayland
- The wire format
- Protocols
Conclusion
Links

If you use linux on a desktop machine, you might have run into "wayland". In this post I try to demystify it a bit.

Vocabulary

There is a lot of confusing vocabulary in this subject. Before diving into the material, I should clean things up.

Compositor

Figure 1. Compositing is a well-known term in media

Compositing essentially describes the process of taking two or more images and joining them together in a single image. A compositor is something that does the compositing 🤯

There is one edge case: What if a desktop environment only ever shows one window. There is a whole genre of software that does that: They are called kiosk and one example is the cage compositor

On the desktop that mostly means, that multiple window images are thrown into one big image that can be displayed on your monitor. Now it is easy to see that every computer desktop needs a compositor as long as you see two windows side by side.

Note	Compositors under Xorg While Xorg itself is already a compositor, there is a established extension to outsource compositing to programs like picom or GNOME’s mutter. These programs can then add more visual effects. So there are really two compositors most of the time.

Display Server

Compositing is only a subset of a bigger task: Input/output management. For example: I’m currently typing this on a keyboard. Every click has to be registered and ideally only the focused window will receive the information about that click and act on it.

All that has to be managed by a sort of supervisor which has to talk to the kernel for that job. The programs that solve this task are called display servers.

Important

Wayland Compositors

Display Servers that implement the Wayland display server protocol are called Wayland Compositors even though they do more than compositing the image. They are really compositing all of the input/output devices.

Window Manager

Window Managers (WM) are really just a gimmick in this whole stack. The idea is that the heavy lifting of input/output management is done by the display server already, so now someone else can implement how the windows should arrange and behave like. I will not go further into this topic.

Overview

Figure 2. The desktop software stack as it applies to all major operating systems. GUI applications are on the same place as "graphical interface".

Intro (Problems with Xorg)

For the longest time now, the dominant display server on the linux desktop is Xorg. Xorg is roughly the only implementation of the X11 specification.

For a while everything was fine and dandy, a app only had to be compatible with Xorg for it to be available to all of the linux desktop - as all of the linux desktop was Xorg.

Since Xorg is a project from 1980s legacy supports, historical weight and technical debt accumulated a lot over the years.

It led to the situation where a lot of linux users are familiar with screen tearing as it is such a common problem on Xorg based systems. But screen tearing, although a very annoying issue that makes your desktop experience insufferable, is not the only issue with Xorg.

Security

Due to Xorgs age, it is not surprising that IT security isn’t a big priority on many accounts. You know how you can just run a hotkey daemon like sxhkd in your terminal? That is a non-root key-logger and thus a big security hazard right there!

The same thing applies to taking screenshots on Xorg. Any running process can check on your keyboard input and what is being displayed on the screen.

If you want to read up on the security of Xorg screen lockers, read up on the opinion of the XScreenSaver author here - and also check out the rest of his cute website. XScreenSaver is used by a whole lot of X screen lockers.

Another honorable mention of that are screen lockers under Xorg. It’s literally just a maximized window that asked for receiving all keyboard input. If that window crashes somehow… the computer is "unlocked". It’s insane.

Programming experience

as a developer of X.Org

I can’t really speak to that but if you want to see Daniel Stone presenting his experience as a X.Org and Wayland developer, take a look here. It’s a very well done and entertaining presentation.

side note: three people on this earth understand X input

really wish I wasn’t one of them

— Daniel Stone

RedHat (who understandably want to funnel their resources into the future of the Linux desktop which is Wayland) and the lack of willing open source developers on that front has essentially put Xorg on life support / deep maintenance mode. In October 2021 - after 3 years and the longest time period so far without a official release - Xorg 21.1 has been released, officially adding the features of 3 years of development such as the long-wanted support for different refresh rates of monitors. That release also started the GNOME-like version naming convention. I wouldn’t expect a lot of development going forward.

The developer experience reflects in the fact that many Xorg developer went on to start the Wayland project.

as a developer of clients

You can take a look at the documentation of Wayland protocols on the Wayland Explorer. It’s a well made site and I use it myself as a reference.

Table 1. Comparing development experience
X.Org (Old posts)	Wayland (Actual documentation)

Have you ever tried to write a small app that talks to the X server directly? You most likely have given up thinking that you would rather slurp a tennis ball through a straw than to proceed. That feeling is very human. The X protocol and its extensions are very badly documented. Many people just end up setting random X properties on their windows that they found out about in some mailing list or forum post from the early 2000s.

Wayland fixes that problem. All wayland documentation you need at the end of the day, is the documentation of the protocols (we will get to that). These protocols - written in XML - are inherently self-documenting. That allows for a exhaustive and auto-generated documentation of … everything.

Why not just build a new X11 display server?

So if the Xorg server is such a mess, why did people not go ahead and write a new X11 display server instead of ditching the protocol altogether?

The answer is that the X11 protocol itself also sucks. Problems such as the developer experience and the security issues are a direct consequence of the protocol and not of the Xorg implementation.

If you think about it, there are actually other implementations of the server-side X11 protocol, such as Xephyr or Xwayland (which is the compatibility layer between X clients and wayland servers) but none of which is really a full blown standalone display server such as Xorg.

Wayland

I think I have set the stage for a new technical solution by now. So how does wayland work?

The wire format

Keep it mind that the wire format is only a implementation detail of wayland. Theoretically there can be a program that speaks the wire format but doesn’t implement the wayland protocol. And you could also implement the wayland protocols on top of any other communication protocol. I’m only going into it here because I find it interesting and revealing for a comprehensive view.

If I want to talk to a wayland compositor, I can just write to the unix socket of the compositor. The unix socket by default is at a path like /run/user/1000/wayland-0. Talking to the socket directly requires a specific language though: The wire format.

Wayland is strictly object oriented. That means that there are no global functions one can run. Instead there are only methods that can be called on instances of a class. To call such a method, I would have to send the following information to the socket:

An ID that uniquely identifies the object on which I call the method
The "index" of the method I want to call
Even more data if the method takes arguments

And since all I can do is call methods from objects, all bytes send to the socket will have this form too. There can’t be an outgoing message that doesn’t have this form.

Now, methods don’t return anything in wayland. You throw the bytes in the socket void and hope for the best.

Wayland is also event-driven. The only way that you retrieve information from the compositor is through signals. They work just like you are used to from GUI toolkits. And if you think about it: Signals are the exact counterpart to methods. Instead of you calling a procedure as discussed earlier, the compositor now calls your procedure which works the same way but now you are the receiver and the method index is a signal index.

You will see a short example of the wire format after you got to learn the basic protocol.

Protocols

You can check the raw XML protocol here

You often hear about protocols when talking about wayland. But what even is a protocol? Protocols in wayland are nothing but the definition of a set of classes which might occur on a given wayland connection. It’s literally just a XML File that essentially says stuff like "There is a window class", "the first method of the window class sets the width of the window" etc. It’s what is needed to interpret the calls on the connection. With that information you know which bytes to send into the socket and how to intepret the received bytes.

Note	Luckily you don’t have to put every protocol into code, write bytes to the unix sockets yourself and keep track of all the IDs. There is a library to do just that: libwayland.

I will now describe a couple of the more important protocols for end users.

wayland.xml

Check the protocol yourself here (this time in a cute web app)

Now you may ask yourself: If there are no global functions I can call, how would I even start something like opening a window? The answer to that is defined in the wayland protocol: On every open connection there exists an object with the ID 1. That object is called "the display". The ID 0 is reserved for the NULL-pointer.

"The display" is just one of many classes that are defined in the wayland protocol. The wayland protocol is just another protocol that happens to be super important to all wayland compositors, as it is the biggest common factor of all wayland compositors.

The wayland protocol defines of course more than that such as how memory is being shared between server and client and how keyboard and mouse events are propagated.

Example

Warning

This is an oversimplified example to showcase how to think about wayland while developing. This example does have inaccuracies. Nevertheless, you can easily try to follow the protocol by having the wayland.xml documentation open on the side.

Now open up the wayland.xml file or check it out in the web app, you can easily follow this example. The following message flow is very often needed in a similar manner:

client sends (1, 2, 2) to server

Client calls the second method of the object with ID 1. The object with ID 1 is always reserved for the wl_display object. So the method called is wl_display::get_registry and the argument it passes is the new ID to which the result is being bound to: ID 2.

server sends (2, 1, 1337, "wl_shm", 3) to client

(The string would normally be byte encoded and null terminated)

The server calls the first signal of the object with ID 2. The client just bound ID 2 to the wl_registry so it knows what to do. The first signal is the wl_registry::global signal which announces global objects. This event in particular announces the wl_shm global on version 3! 1337 is just the made-up "name"/reference in this example.

In the second step, the server invoked the first signal of the object with ID 2. In the third step, the client calls the first method of the object with ID 2. They are counted separately.

client sends (2, 1, 1337, 3) to server

The client wants to share memory with the server so it registers a wl_shm on ID 3 and lets the compositor know about it. It does so by calling the first method of the object with ID 2: wl_registry::bind, binding the name from the previous signal to ID 3.

Note

If you use libwayland, the C-method does not reflect the wayland protocol perfectly. This is because it also passes the interface of the object to the bind function which is needed to leverage types. You will also have access to functions such as wl_display::roundtrip which is NOT defined in the protocol but added for convenience.

server sends (3, 1, 0) to client

You know the drill: ID 3 is our previously bound wl_shm, the first signal is wl_shm::format which announces possible pixel formats. The pixel format 0 is the four byte representation argb8888 which to my knowledge is available on all wayland compositors.

Now the client can create a wl_shm_pool on the wl_shm global object with which it can then create a wl_buffer. This buffer can be attached to a wl_surface which can then be used in a xdg_surface to create a top level window. As you can see, it gets a bit verbose but the concept stays the same and all of the message flow can be understood through the documentation.

xdg-shell.xml

Check out this protocol yourself too! https://wayland.app/protocols/xdg-shell

I’m sure after this example you read all of the wayland.xml specification. Maybe you have stumbled across this section:

wl_shell

Create desktop-style surfaces […]

Note! This protocol is deprecated and not intended for production use. For desktop-style user interfaces, use xdg_shell. Compositors and clients should not implement this interface.

With "top-level windows" I mean windows like your browser, GIMP, GIMPs popup dialog, GIMPs popup dialog of the popup dialog, your terminal and so forth. Not included are other surfaces displayed on the desktop such as your bars, your conky widgets or your screen locker.

wl_shell was meant as the desktop shell part of the protocol. It could be used to create the top-level windows that we are here for. But at the end of the day, it couldn’t hold up to the expectations and needs of the requirements. It was decided that the top-level window logic should be kept outside the wayland.xml protocol to allow for faster iterations and better design. To replace wl_shell we now have the xdg-shell protocol which you will have to use if you plan on doing top-level windows.

layershell.xml

Xdg-shell is cool but it is missing a very important piece in the whole desktop puzzle: The ability to add components such as notification popups and status bars.

For the KDE and GNOME ecosystem that was not a big problem, they just added their own within the compositor. But enthusiast compositors such as Sway rely on the ability to customize them. And so the wlroots people came up with the layershell protocol to do just that.

While wayland.xml and xdg-shell.xml are obligatory to implement if you want to have a functional wayland compositor, this protocol is not. Sadly, GNOME doesn’t support this protocol and thus programs written for layershell won’t work on the GNOME compositor. This kind of fragmentation is often criticized about wayland but I think it is ok: Different compositors can set vastly different emphasis.

Conclusion

https://arewewaylandyet.com/ might tell you otherwise

I hope I could demystify a bit of wayland for you. This post might read a little futuristic but I want you to understand that wayland is already here! GNOME made wayland the "default user session" in 3.20, in 2016. Since 2016, Fedora also ships with a default wayland session since Fedora 25.

Ubuntu made wayland the default all the way back in Ubuntu 17.10 (in October 2017, duh) but then went back to Xorg as people had lots of troubles. Since Ubuntu 21.04 it is back with a default wayland session again and this time it seems to be here to stay. So if you ever see a linux user, chances are they already use wayland.