Wayland Window System

Wayland is a protocol that a backend compositor uses to communicate with its clients. It is also a C library implementation of that protocol. Weston is the reference implementation of the Wayland compositor. The platform supports Wayland and Weston. Check the Release Notes for specific versions supported.

For more information about Wayland, see the Wayland home page and documentation page at:

NVIDIA defines extensions to enumerate and control devices and screens through EGL. These are collectively referred to as EGLOutput/EGLDevice.

The EGLOutput/EGLDevice specifications used by Weston are as follows:

The Weston compositor uses EGLOutput/EGLDevice to display the composited Weston desktop or individual Wayland applications on a physical display device.

The platform provides utilities for changing the configuration and runtime parameters.

The full source code to the NVIDIA implementation of Weston is in:

The NVIDIA implementation of Weston uses the Direct Rendering Manager (DRM) backend, found in the target filesystem at:

There are two implementations of the DRM display backend. One is implemented on the Linux KMS. The other is implemented on top of the EGLOutput series of extensions.

During the Weston startup, Weston creates an OpenGL ES EGLStream producer, if option use-egldevice is enabled. Weston then creates EGLOutput. EGLOutput is the EGLStream consumer that passes all the output frames from Weston to the display, For more information, see EGLOutput Specifications. If use-egldevice is not enabled, the output method switches to drm/kms.Wayland buffer sharing between EGL clients and Weston is implemented using EGLStreams. The EGL client creates an EGLStream producer and binds the EGLStream file descriptor to wl_buffer through the Wayland protocol. Weston queries the EGLStream file descriptor from wl_buffer through a query of EGL_WAYLAND_BUFFER_WL to eglQueryWaylandBufferWL(). This functionality is provided by the EGL_WL_bind_wayland_display extension.

Wayland buffer sharing also supports dma-buf sharing based on the linux-dmabuf-unstable-v1-protocol protocol. For more information, see Weston dma-buf Support.

The NVIDIA EGL implementation tries to detect what platform it is running on at runtime (e.g., Wayland, etc.). It is possible to bypass this detection by setting the EGL_PLATFORM environment variable. For Wayland, this variable must be set to "wayland". And do not set the environment variable DISPLAY in case of the wayland platform. If DISPLAY is set, you are assumed to be running X11.

The libdrm.so library is used to set display modes and to attach framebuffer images to display overlays. The platform custom implementation of libdrm.so is not implemented on top of the DRM-KMS display driver. Instead, it is implemented on top of the NVIDIA NVDC display driver.

Weston requires the NVIDIA custom libdrm.so and is not compatible with the default Ubuntu libdrm.so.

The default Ubuntu libdrm libraries are located at:

The SDK installation deletes those libraries and replaces them with libdrm.so at:

When installing 3rd party packages or new software with apt-get, you must make sure that libdrm.so* shared objects are not recreated. If they exist, remove them from:

Weston supports multiple backends. This section describes the core options that all Weston backends support.

Weston supports multiple backends and, depending on the backend used, accepts different options. NVIDIA supports drm-backend.so, which allows Weston to support NVIDIA graphics.

The supported drm-backend.so options and the values they consume are as follows.

Weston uses a configuration file called weston.ini for its setup. When Weston starts, it will search for the weston.ini configuration file in one of the following places:

If $XDG_CONFIG_HOME is set, Weston searches in:

If $HOME is set, Weston searches in:

If $XDG_CONFIG_DIRS is set, Weston searches in:

If $XDG_CONFIG_DIRS is not set, Weston searches in:

If no variables are set, Weston searches in:

Where the environment variable:

Weston picks the default settings for display by itself. If the default settings are insufficient, the display settings can be defined in weston.ini.

To configure the display, add the following to weston.ini with the appropriate values for output name, mode, and transform:

Where name=<output_name> sets a name for the output string. The backend uses the name to identify the output.

The mode=<mode> assignment sets the output mode string. The mode parameter is handled differently depending on the backend. The DRM backend accepts different modes:

Optionally, you can specify a modeline, for example:

A modeline consists of the refresh rate in Hz, the horizontal and vertical resolution, and options for horizontal and vertical synchronization. The cvt(1) program provides a suitable modeline string.

The transform=<transformation> assignment applies the transformation to the screen output string. The transform key must be one of the following 8 strings:

The following is a weston.ini configuration example:

Weston creates its Unix socket file, for example wayland-0, in the directory specified by the required environment variable $XDG_RUNTIME_DIR. $XDG_RUNTIME_DIR defines the base directory relative to which user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc.) are stored.

Check whether the $XDG_RUNTIME_DIR environment variable is set, if it is not set please set it as follows.

Use either of the following two methods to set the $XDG_RUNTIME_DIR directory before running Weston:

Weston can be launched with root privileges or via weston-launch tool.

 

The instructions provided assume Weston and Wayland are running as superuser.

Weston supports mixed mode compositing using dma-buf. Weston collects all the overlay planes and assigns one to the GFX as the primary plane. Others are available as overlay planes. Weston evaluates all surfaces and views on every frame, and chooses one of these strategies to composite them:

The weston-debug client application receives and prints debug messages using the weston-debug protocol. For example, when Weston is recompositing, it prints all surface views and descriptions of the decision process regarding their assignment to overlays and GL compositing.

For weston-debug to work, you must run Weston with the ‑‑debug switch. Do not use this switch in production.

You can pass weston-debug additional parameters to choose categories of debug output to display:

Alternatively, you can enable Weston debug output by setting the environment variable WAYLAND_DEBUG=server, and Weston client debug by setting WAYLAND_DEBUG=1.

Clients can post dma-buf buffers to Weston using Wayland’s Linux DMA-BUF Unstable V1 Protocol. Dma-buf support with Weston contains the following components.

GBM is commonly used to allocate buffers, which are backed by the dma-buf file descriptor.

This code snippet shows how to allocate a buffer using GBM:

Weston supports the DRM_FORMAT_XRGB8888 and DRM_FORMAT_ARGB8888 formats.

A modifier is an encoding of vendor-specific buffer layout parameters. Weston modifiers are supported by DRM (read the IN_FORMATS plane property blob) and by EGL (call eglQueryDmaBufModifiersEXT()).

You can use this API function to write data directly into a GBM buffer:

You can also memory map a GBM buffer and get a CPU-accessible address to the data written to or read from it:

Weston uses the Generic Buffer Management (GBM) library to allocate buffers that are backed by dma-buf file descriptors. Client applications must call the following GBM functions to get the dma-buf file descriptor and associated parameters from the GBM buffer object. To post the dma-buf to a Wayland surface, the file descriptor and parameters must be provided via Linux DMA-BUF Unstable V1 Protocol.

The following code snippet shows the main calls involved (assume gbm buffer object contains one plane only).

The GL renderer in Weston creates an eglImage from a dma-buf object that it receives with Linux DMA-BUF Unstable V1 Protocol using the EGL_EXT_image_dma_buf_import and EGL_EXT_image_dma_buf_import_modifiers extensions. Weston obtains the GL texture target to be used with this eglImage by calling eglQueryDmaBufModifiersEXT(), and binds the eglImage to the texture.

To enable experimental Gnome-Wayland desktop shell support: