Wayland Protocol & Architecture

Table of Contents

Introduction

Wayland is a modern, secure display server protocol for Linux and Unix-like operating systems. It is a replacement for the older X11 system and it manages how applications render graphics and windows to your screen.

In a Wayland desktop, you have two components:

Wayland Client (The Application): This is the individual program (like your web browser or text editor). It draws its own interface and sends the finished pixels to the compositor to be displayed.
Wayland Compositor (The Server/Manager): This is the manager, it handles all hardware input (mouse, keyboard) and forwards it to the proper client (application like your focused browser), and combines all the individual windows rendered by the clients into the final image you see on your screen.

Wayland Package

Installing the wayland package (preinstalled on most modern distros) provides the official freedesktop.org implementation of the protocol. This includes:

wayland.xml: A high-level XML interface defining the core Wayland specifications (requests and events). All Wayland protocols (core and extensions) use this format.

wayland-scanner: A tool that generates C headers and glue code from XML protocol files. Many scanners exist in other languages like rust

libwayland-client & libwayland-server: C libraries that implement the wire protocol for both components and offer common utilities for handling Wayland data structures.

Wayland Protocol

The wayland protocol is actually easy to understand and very elegant. I will explain the interfaces first and then I will go over the wiring protocol and it will start to click.

Interfaces (XML files)

We discussed earlier that there is an xml file which is wayland.xml (we call it core). There are so many other xml files as well which we call extensions to wayland, like xdg-shell which is defines the functionality needed to create windows that can be dragged, resized, etc, in a wayland desktop. You can browse these xml files locally, they will be usually in /usr/share/wayland-protocols/.

I find it sometimes very helpful to peak at Wayland Protocols Explorer, it's very elegant and it shows all popular Wayland protocols. I know there are so many protocols, but nobody is expecting you to know them all. You should just be able to read the documentation and know how to use it.

You might notice that there are labels to these protocols, and they are listed under a certain subdirectories in the wayland-prtocols directory locally.

Core: this is the core wayland protocols
Stable: [TODO]
Staging: [TODO]
Unstable: [TODO]

The XML file format defines interfaces, each interface has many requests, and events. Let's explain this with an example form the core wayland.xml.

There are many interfaces, one of them is wl_surface, below is the code truncated.

  <?xml version="1.0" encoding="UTF-8"?>
  <protocol name="wayland">
    <interface name="wl_display" version="1">
  	...
    </interface>

    ....

    <interface name="wl_surface" version="7">
  	<description summary="an onscreen surface">
  	  A surface is a rectangular area that may be displayed on zero
  	  or more outputs, and shown any number of times at the compositor's
  	  ....
  	</description>
      <enum name="error">
        <description summary="wl_surface error values">
          These errors can be emitted in response to wl_surface requests.
        </description>
        <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
  	  ....
      </enum>
    </interface>
  </protocol>