NVIDIA Graphics with the GNOME Wayland session

This document intends to describe the current state of running the GNOME Wayland session using the proprietary NVIDIA driver.

Background

The proprietary NVIDIA doesn't provide the same user space API as the open source drivers. While the open source drivers allows the display server to use the Generic Buffer Manager (gbm) and Kernel Mode Setting (KMS) APIs to manage hardware buffers, set modes, and queue page flips, configure hardware planes, the NVIDIA driver forces the display server to treat it differently. Instead of these APIs, the compositor uses a combination of KMS, to set modes, and EGL (EGLDevice & EGLStream extensions to be precise) to indirectly queue page flips by linking an EGLSurface, corresponding to an area of the screen, with a CRTC of an EGLDevice, using an EGLStream.

Current state and limitations

With GNOME 3.32, there is some preliminary support for runnig a Wayland session on top of the NVIDIA drivers.

Hardware acceleration

Compositing

Compositing is done using OpenGL. The EGLSurfaces of each monitor is associated with a monitor using EGLStreams and EGLDevice, meaning the NVIDIA driver itself takes care of handing over buffers after eglSwapBuffers() to the hardware.

Hardware cursor

The cursor is currently drawn using OpenGL, as part of the compositing image.

Accelerated EGL Wayland clients

Native EGL Wayland clients are accelerated, although differently from how EGL clients work when using the open source drivers.

With open source drivers, the EGL driver (usually mesa) hands over hardware buffer handles, either using DMA-BUF handles and a generic DMA-BUF Wayland protocol, or using opaque buffers using a special purpose Wayland protocol.

With the NVIDIA drivers, an EGLStream acts as a channel between a texture in the compositing display server and the client side EGLSurface. A special purpose Wayland protocol implemented in the NVIDIA driver is hooked into GNOME Shell, to manage initiation of these EGLStreams. No explicit buffer passing is done, instead certain protocol events triggers the display server to acquire textures from the EGLStreams.

Non-accelerated Xwayland clients

Xwayland uses accelerated EGLStreams to pass window content of non-accelerated X11 clients, similarly to how it is done with passed hardware buffers when using the open source drivers.

Accelerated Xwayland clients (GLX)

There is currently no accelerated GLX support when running a GNOME Wayland session no top of the NVIDIA drivers, meaning X11 OpenGL applications will use software rendering.

Context-lost recovery

After suspending, graphics memory may be purged, requiring the display server to recover said memory, usually by reuploading textures and other resources that may have been purged. This is currently not supported when using the Wayland session on top of the NVIDIA driver, but there exists in-progress downstream patches to handle this in RHEL 8.

Monitor configuration

Mode setting

Mode setting is possible, but the current requirement to use dumb buffers during mode setting before establishing the EGLSurface, EGLDevice CRTC stream link, results in memory constraint issues with multiple monitors with higher resolutions.

Monitor mirroring

Monitor mirroring is currently not possible due to the issue that an EGLSurface can only be linked to a single CRTC. The way GNOME Shell currently does monitor mirroring relies on passing the same hardware buffer to multiple CRTCs, which is currently not supported by the API exposed by the NVIDIA driver.

Tiled monitors

Certain monitors are constructed of multiple CRTCs that are configured separately. GNOME Shell currently implements this by havig a tiled monitor share the same EGLSurface, while handing different regions of the same hardware buffer to the different CRTCs. This is currently not supported by the API exposed by the NVIDIA driver.