Display and Graphics Stack

Introduction

EDF provides a graphical desktop environment on boards equipped with a Mali GPU. The display stack consists of two components:

  • kmscon – a userspace virtual console that renders directly through DRM/KMS. kmscon presents an authenticated login prompt on the display, replacing the need for a traditional framebuffer console.

  • Weston – the reference compositor for the Wayland display protocol. After the user logs in through kmscon, Weston launches automatically and provides a lightweight graphical desktop.

This two-stage approach provides user authentication before desktop access, runs the desktop session under the logged-in user account (rather than a system service account), and works on platforms where the GPU driver does not expose a framebuffer device (such as the Mali-G78AE).

This page covers how to use the graphical desktop on supported EDF boards, how to access the desktop remotely through VNC, how to manage the display services, and how to configure the display stack in a custom Yocto build.

Supported Images and Boards

The graphical desktop is included in the EDF disk images built for boards that use a Mali GPU. Non-mali images do not include Weston, kmscon, or any graphical desktop.

Common machine

GPU

Driver

Example boards

amd-cortexa53-mali-common

Mali-400

Proprietary Arm (default) or Lima

ZCU102, ZCU104, ZCU106, KV260, KR260

amd-cortexa78-mali-common

Mali-G78AE

Proprietary Arm only

VEK385

Note

If your board does not use a Mali GPU, the EDF image boots to a serial console login prompt instead. No graphical desktop is available.

Using the Graphical Desktop

To use the graphical desktop, connect a display and input devices to your board before powering it on.

  1. Connect an HDMI or DisplayPort monitor to the board.

  2. Connect a USB keyboard. A keyboard is required to log in at the display console. A mouse is optional – Weston starts with the --continue-without-input flag.

  3. Power on the board and boot the EDF image from SD card, eMMC, or other supported boot media.

  4. After boot completes, a text-based login prompt appears on the monitor. kmscon renders the prompt directly through DRM/KMS, so no framebuffer device is required.

  5. Log in with the default EDF credentials (user amd-edf). After authentication, the Weston graphical desktop launches automatically.

  6. To open a terminal, right-click the desktop background and select Terminal from the context menu. The terminal runs as the logged-in user, so sudo commands work as expected.

Note

Weston logs are saved to $XDG_RUNTIME_DIR/weston.log. For the default amd-edf user this is typically /run/user/1001/weston.log (the exact UID is set by the recipe that creates the user). If XDG_RUNTIME_DIR is not set, logs are saved to /tmp/weston.log. Logs are non-persistent and are cleared on reboot.

Note

The display does not blank or lock after inactivity. The no-idle-timeout option is enabled by default.

Note

If you boot the board without a display cable connected, kmscon does not start. Plugging in a display cable after boot triggers a udev hotplug rule that starts the kmscon console automatically.

VNC Remote Access

The EDF Weston configuration includes the VNC back end for remote desktop access without a physical display connection. The VNC back end requires TLS for all connections, so generate a TLS certificate on the target before use.

Generate a self-signed TLS certificate on the target:

$ sudo mkdir -p /etc/weston/tls
$ sudo openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
    -nodes -keyout /etc/weston/tls/vnc.key -out /etc/weston/tls/vnc.crt \
    -days 365 -subj "/CN=weston"

Set ownership and permissions on the private key:

$ sudo chown root:video /etc/weston/tls/vnc.key
$ sudo chmod 640 /etc/weston/tls/vnc.key

Optionally, configure /etc/xdg/weston/weston.ini so that the TLS paths and display resolution are set persistently:

[vnc]
tls-cert=/etc/weston/tls/vnc.crt
tls-key=/etc/weston/tls/vnc.key

[output]
name=vnc
mode=1920x1080

Log in to the board through SSH or a serial console and start Weston with the VNC back end.

Note

The VNC back end starts an independent Weston session – it does not mirror the desktop running on the local display. Both sessions can run in parallel without interfering with each other.

If weston.ini is configured as shown in the preceding section:

$ weston --backend=vnc

If weston.ini is not configured, pass the TLS paths and resolution on the command line:

$ weston --backend=vnc \
    --vnc-tls-cert=/etc/weston/tls/vnc.crt \
    --vnc-tls-key=/etc/weston/tls/vnc.key \
    --width=1920 --height=1080

Weston listens on port 5900 by default. Connect from a TLS-capable VNC client (TigerVNC, RealVNC, or similar) to <target_ip>:5900. Accept the self-signed certificate when prompted.

Note

The VNC back end is only available in Weston 13. Mali-400 boards using the proprietary Arm driver run Weston 9 and do not support VNC. To use VNC on Mali-400, switch to the open-source Lima driver (see GPU Driver Configuration).

Demo Applications

The EDF images include the weston-examples package, which provides demo applications for verifying GPU rendering. Launch these from the Weston terminal:

  • weston-simple-egl – renders a spinning triangle by using OpenGL ES

  • weston-simple-shm – displays a color-cycling window by using shared memory buffers

  • weston-flower – draws an animated flower pattern

  • weston-smoke – interactive smoke effect (responds to mouse input)

For example, to verify that GPU-accelerated rendering is working:

$ weston-simple-egl

A window with a spinning triangle appears on the desktop. Press Esc to close it.

For more comprehensive GPU benchmarking, install glmark2 from the package feed:

$ sudo dnf install glmark2
$ glmark2-es2-wayland

This displays a rotating horse rendered with OpenGL ES 2.0 and reports a benchmark score. Press Esc to close it.

Install Qt example applications from the package feed:

$ sudo dnf install qtbase-examples

Set the Qt platform to Wayland and launch a demo:

$ export QT_QPA_PLATFORM=wayland
$ /usr/share/examples/widgets/widgets/sliders/sliders

The EDF Weston configuration also includes Xwayland support, which lets legacy X11 applications run inside the Wayland desktop. Install X11 applications from the package feed:

$ sudo dnf install xeyes xclock
$ xeyes &
$ xclock &

The X11 applications open as windows on the Weston desktop, managed through the Xwayland compatibility layer.

Display Service Management

The display stack uses two systemd services:

  • kmsconvt@tty1 – the kmscon virtual console that provides the login prompt on the display. Runs in both graphical.target and multi-user.target.

  • weston – the Weston compositor, launched by the user’s login profile. Only starts when the default target is set to graphical.target.

The systemd boot target controls whether the display provides a full graphical desktop (Weston) or a text-only console (kmscon only):

To switch to a text-only display console (no Weston):

$ sudo systemctl set-default multi-user.target

To switch back to the graphical desktop on the next boot:

$ sudo systemctl set-default graphical.target

Check the kmscon service status:

$ sudo systemctl status kmsconvt@tty1

Check whether Weston is running (as a user process, not a system service):

$ pgrep -a weston

Yocto Build Configuration

The following describes how the graphical desktop is integrated into the EDF Mali images at the Yocto build level. Use this information to add or remove display support from a custom image.

Display Service Architecture

The graphical desktop uses a two-stage startup:

  1. kmscon provides a DRM/KMS-based virtual console on tty1. A udev rule (99-kmscon-hotplug.rules) starts kmsconvt@tty1.service when a display cable is plugged in. A systemd drop-in (10-check-display.conf) checks for a connected display before starting the service, so kmsconvt is skipped on boards without a display connector.

  2. Weston is launched after the user logs in. The weston-init recipe installs a profile script (/etc/profile.d/kmscon-weston.sh) that detects the kmscon session (through the KMS_START_SCRIPT environment variable) and checks that the configured default target is graphical.target. If both conditions are met, the script launches Weston through kmscon-launch-gui, which handles the DRM device handoff between kmscon and Weston. On serial or SSH sessions, or when the default target is multi-user.target, the profile script is a no-op.

The Weston system service is disabled (SYSTEMD_AUTO_ENABLE set to disable) because Weston is started from the user’s login profile rather than directly by systemd. When the default target is set to multi-user.target, kmscon still provides a display console login prompt, but Weston does not start – the user gets a text console on the display instead.

Packages

The Mali EDF images include packagegroup-core-weston, which pulls in Weston, its default back end, and supporting libraries. The weston image feature is enabled automatically when a machine declares the mali400 or malig78ae machine feature and wayland is in DISTRO_FEATURES. For Mali-400, this works with both the proprietary Arm driver and the open-source Lima driver.

kmscon and its dependency libtsm are pulled in automatically as runtime dependencies of weston-init (through RDEPENDS). This is custom EDF wiring added by the weston-init.bbappend in meta-xilinx-mali400 – upstream weston-init does not depend on kmscon.

Default systemd Target

The Mali EDF image recipes set the default systemd boot target to graphical.target:

SYSTEMD_DEFAULT_TARGET = "graphical.target"

The boot target determines the overall system mode (graphical vs command-line). Setting it to graphical.target ensures that display-related services are available. The kmscon udev hotplug rule handles the actual display console startup.

If you are building a custom image and want the display stack installed but not started on boot, omit the SYSTEMD_DEFAULT_TARGET override. The system then boots to multi-user.target (command-line) by default.

PACKAGECONFIG Options

The EDF distro layer enables the following PACKAGECONFIG options:

For weston-init:

  • no-idle-timeout – disables display blanking and screen locking after inactivity.

  • xwayland – enables Xwayland support for running legacy X11 applications inside the Wayland desktop. This option is enabled automatically because x11 is part of the default OE-Core distro features inherited by the EDF distro.

For weston:

  • vnc – enables the VNC back end for remote desktop access. Requires neatvnc with TLS support (provided by GnuTLS). Only available in Weston 13.

For kmscon:

  • video_drm2d – DRM/KMS rendering without OpenGL (avoids conflicts with render-only GPUs such as Mali-400).

  • font_pango – Pango font rendering.

  • multi_seat – multi-seat support through logind.

Note

On ZynqMP boards, kmscon requires two platform-specific patches gated by the :zynqmp override: one to use ARGB8888 framebuffer format (the zynqmp-dpsub primary plane does not support XRGB8888), and one to force legacy modesetting (atomic modesetting is not supported). These patches are applied automatically by the kmscon bbappend in meta-xilinx-mali400.

GPU Driver Configuration

The GPU driver determines how Weston accesses graphics hardware. The following table lists the available driver configurations. The EDF distro automatically adds libmali to DISTRO_FEATURES when a Mali GPU is detected in MACHINE_FEATURES, so the proprietary Arm driver is the default for both GPU families.

GPU

Driver

Weston

Default

MACHINE_FEATURES

DISTRO_FEATURES

Layer

Mali-400

Proprietary Arm

9

Yes

mali400

libmali (auto)

meta-xilinx-mali400

Mali-400

Lima (open-source)

13

No

mali400

remove libmali

meta-xilinx-mali400

Mali-G78AE

Proprietary Arm

13

Yes

malig78ae

libmali (auto)

meta-xilinx-gpu-malig78ae

The proprietary Arm Mali-400 driver only provides GLES 2 interfaces. Weston 13 requires GLES 3, so Mali-400 boards using the proprietary driver are limited to Weston 9. The open-source Lima driver (through Mesa) provides GLES 3, so switching to Lima enables Weston 13 on Mali-400 boards. The Mali-G78AE proprietary driver provides GLES 3 and uses Weston 13.

The (auto) annotation indicates that the EDF distro configuration adds libmali automatically. No manual DISTRO_FEATURES change is needed for the default driver. To switch to the open-source Lima driver on Mali-400 machines, remove libmali in local.conf:

DISTRO_FEATURES:remove = " libmali"

Mesa does not currently support the Mali-G78AE GPU, so the proprietary Arm driver is the only option for Cortex-A78 machines. The proprietary driver provides EGL, GLES 1/2/3, GBM, Vulkan, and OpenCL support. When enabled, it replaces the Mesa providers for these graphics interfaces. The G78AE also requires out-of-tree kernel modules (kernel-modules-g78ae) which are installed and loaded automatically through udev rules.

Note

The proprietary Arm Mali driver and the open-source Lima driver are mutually exclusive. Do not enable both simultaneously.

Adding the Display Stack to a Custom Image

To add the graphical desktop to your own image recipe, append the following to your image .bb file:

IMAGE_INSTALL:append = " packagegroup-core-weston"
SYSTEMD_DEFAULT_TARGET = "graphical.target"

The packagegroup-core-weston package group pulls in Weston and all supporting libraries (including kmscon through weston-init dependencies). Ensure that your machine configuration includes a Mali GPU driver. Without the GPU driver, Weston falls back to a software renderer, which may result in reduced performance.

Removing the Display Stack from a Mali Image

To build a Mali image without the graphical desktop, remove the package group and reset the systemd target in a .bbappend file:

IMAGE_INSTALL:remove = " packagegroup-core-weston"
SYSTEMD_DEFAULT_TARGET = "multi-user.target"

Troubleshooting

No Display Output After Boot

  • Verify that the monitor is connected and powered on before booting the board.

  • Confirm that the kmscon service is running:

    $ sudo systemctl status kmsconvt@tty1

  • If the service is inactive, check whether a display connector is detected:

    $ cat /sys/class/drm/card0-*/status

    At least one connector must report connected for kmsconvt to start.

  • Check the journal for kmscon errors:

    $ sudo journalctl -u kmsconvt@tty1

  • Verify that the kernel has loaded the display and GPU drivers:

    $ dmesg | grep -i drm
$ dmesg | grep -i mali

Weston Does Not Start After Login

  • Verify that the profile script is installed:

    $ cat /etc/profile.d/kmscon-weston.sh

  • Check that the KMS_START_SCRIPT environment variable is set (it is set automatically by kmscon):

    $ echo $KMS_START_SCRIPT

  • Check the Weston log for errors:

    $ cat ${XDG_RUNTIME_DIR:-/tmp}/weston.log

References