Kristian Høgsberg

The Wayland Display Server

The Wayland Display Server

1  Wayland Overview

1.1  Replacing X11

Over time, a lot of functionality have slowly moved out of the X server and into client-side libraries or kernel drivers. One of the first components to move out was font rendering, with freetype and fontconfig providing an alternative to the core X fonts. Direct rendering OpenGL as a graphics driver in a client side library. Then cairo came along and provided a modern 2D rendering library independent of X and compositing managers took over control of the rendering of the desktop. Recently with GEM and KMS in the Linux kernel, we can do modesetting outside X and schedule several direct rendering clients. The end result is a highly modular graphics stack.

1.2  Make the compositing manager the display server

Wayland is a new display server building on top of all those components. We are trying to distill out the functionality in the X server that is still used by the modern Linux desktop. This turns out to be not a whole lot. Applications can allocate their own off-screen buffers and render their window contents by themselves. In the end, what’s needed is a way to present the resulting window surface to a compositor and a way to receive input. This is what Wayland provides, by piecing together the components already in the eco-system in a slightly different way.
X will always be relevant, in the same way Fortran compilers and VRML browsers are, but it’s time that we think about moving it out of the critical path and provide it as an optional component for legacy applications.

2  Wayland protocol

2.1  Basic Principles

The wayland protocol is an asynchronous object oriented protocol. All requests are method invocations on some object. The request include an object id that uniquely identifies an object on the server. Each object implements an interface and the requests include an opcode that identifies which method in the interface to invoke.
The server sends back events to the client, each event is emitted from an object. Events can be error conditions. The event includes the object id and the event opcode, from which the client can determine the type of event. Events are generated both in response to a request (in which case the request and the event constitutes a round trip) or spontanously when the server state changes.

2.2  Code generation

The interfaces, requests and events are defined in protocol/wayland.xml. This xml is used to generate the function prototypes that can be used by clients and compositors.
The protocol entry points are generated as inline functions which just wraps the wl_proxy_* functions. The inline functions aren't part of the library ABI and languange bindings should generate their own stubs for the protocl entry points from the xml.

2.3  Wire format

The protocol is sent over a UNIX domain stream socket. Currently, the endpoint is named 0wayland, but it is subject to change. The protocol is message-based. A message sent by a client to the server is called request. A message from the server to a client is called event. Every message is structured as 32-bit words, values are represented in the host's byte-order.
The message header has 2 words in it:
The payload describes the request/event arguments. Every argument is always aligned to 32-bit. There is no prefix that describes the type, but it is inferred implicitly from the xml specification.
The representation of argument types are as follows:

2.4  Connect Time

2.5  Security and Authentication

2.6  Creating Objects

2.7  Compositor

The compositor is a global object, advertised at connect time.
Interface compositor
acknowledge(key, frame)
frame(frame, time)

2.8  Surface

Created by the client.
Interface surface
no events
Needs a way to set input region, opaque region.

2.9  Input

Represents a group of input devices, including mice, keyboards. Has a keyboard and pointer focus. Global object. Pointer events are delivered in both screen coordinates and surface local coordinates.
Interface cache
attach(buffer, x, y)
motion(x, y, sx, sy)
button(button, state, x, y, sx, sy)
key(key, state)
keyboard_focus(surface, keys)
Talk about:
A surface can change the pointer image when the surface is the pointer focus of the input device. Wayland doesn't automatically change the pointer image when a pointer enters a surface, but expects the application to set the cursor it wants in response the the pointer focus and motion events. The rationale is that a client has to manage changing pointer images for UI elements within the surface in response to motion events anyway, so we'll make that the only mechanism for setting changing the pointer image. If the server receives a request to set the pointer image after the surface loses pointer focus, the request is ignored. To the client this will look like it successfully set the pointer image.
The compositor will revert the pointer image back to a default image when no surface has the pointer focus for that device. Clients can revert the pointer image back to the default image by setting a NULL image.
What if the pointer moves from one window which has set a special pointer image to a surface that doesn't set an image in response to the motion event? The new surface will be stuck with the special pointer image. We can't just revert the pointer image on leaving a surface, since if we immediately enter a surface that sets a different image, the image will flicker. Broken app, I suppose.

2.10  Output

A output is a global object, advertised at connect time or as they come and go.
Interface output
no requests
geometry(width, height)

2.11  Shared object cache

Cache for sharing glyphs, icons, cursors across clients. Lets clients share identical objects. The cache is a global object, advertised at connect time.
Interface cache
upload(key, visual, bo, stride, width, height)
item(key, bo, x, y, stride)

2.12  Drag and Drop

Multi-device aware. Orthogonal to rest of wayland, as it is its own toplevel object. Since the compositor determines the drag target, it works with transformed surfaces (dragging to a scaled down window in expose mode, for example).
New objects, requests and events:
Sequence of events:
MIME is defined in RFC's 2045-2049. A registry of MIME types is maintained by the Internet Assigned Numbers Authority (IANA).

3  Types of compositors

3.1  System Compositor

3.2  Session Compositor

3.3  Embbedding Compositor

X11 lets clients embed windows from other clients, or lets client copy pixmap contents rendered by another client into their window. This is often used for applets in a panel, browser plugins and similar. Wayland doesn't directly allow this, but clients can communicate GEM buffer names out-of-band, for example, using d-bus or as command line arguments when the panel launches the applet. Another option is to use a nested wayland instance. For this, the wayland server will have to be a library that the host application links to. The host application will then pass the wayland server socket name to the embedded application, and will need to implement the wayland compositor interface. The host application composites the client surfaces as part of it's window, that is, in the web page or in the panel. The benefit of nesting the wayland server is that it provides the requests the embedded client needs to inform the host about buffer updates and a mechanism for forwarding input events from the host application.

4  Implementation

what's currently implemented

4.1  Wayland Server Library

4.2  Wayland Client Library

4.3  Wayland System Compositor

4.4  X Server Session

File translated from TEX by TTH, version 3.89.
On 10 Dec 2010, 09:22.