plymouth: boot splash for KMS devices, with a ucode theme engine and a demo theme

[dangowrt]

A boot splash for boards that have a KMS device and no framebuffer console, in three parts: the plymouth daemon, a splash plugin that makes a theme a ucode program, and a demo theme that shows what the plugin can do.

plymouth

Built for DRM only: no framebuffer backend, no systemd or upstart integration, no gtk, pango or freetype, so the runtime needs libpng and libdrm and nothing else. The package installs no theme and names none in plymouthd.conf; a theme is a package of its own and selects itself when it is installed.

Four patches. Two are build fixes for musl, which has neither rpmatch() nor execinfo.h. The other two are bugs found while getting this working on an rk3588 board, both submitted upstream:

• The DRM renderer calls drmDropMaster() immediately after opening the device and only takes master back in activate(), so every connector probe in query_device() runs as a client that is not DRM master. The kernel declines a forced probe from such a client and returns the cached connection status, which on a connector nothing has probed yet is unknown. No output counts as connected, no controller is assigned, and the renderer gives up with Could not initialize heads. The splash could therefore only light a display that something else had already probed, which with fbdev emulation gone never happens.
• Escape tears the splash down and switches to the text details view, guarded only on a VT existing. CONFIG_VT is enabled on targets with no framebuffer console at all, so the VT is real but the only console driver bound to it is the dummy one and the details view is written where nobody can read it. The screen simply goes black until escape is pressed again.

plymouth-plugin-ucode

Plymouth's own script plugin has its own small language and composites prepared images, so a theme arrives as a few hundred PNGs. This plugin makes a theme one ucode program with a plutovg canvas over plymouth's pixel buffer: a theme is source, and its artwork is SVG.

A theme returns setup, frame, paint and event. frame advances state and declares what changed, paint draws one damaged rectangle, and nothing reaches the screen that the theme did not ask for, which is what keeps a busy scene at a couple of milliseconds a frame instead of repainting everything. The contract is documented in files/README.md, and plymouth-theme-bench measures any theme offscreen on any target, so themes can be compared without a display.

The plugin connects to ubus and passes events through, together with the objects that already existed when it connected, so a theme can show what the system is actually doing rather than animating a guess. It starts the splash from a preinit hook, before the overlay is mounted, and keeps it up through sysupgrade.

plymouth-theme-openwrt-demo

A worked example, and the default theme once installed. It is explicitly a demo: people with a better eye will do nicer things, and the point here is to show the mechanism end to end.

The scene is a network graph laid out afresh on every boot, drawn from one ucode program and one SVG with no rendered frames anywhere. It has two phases because the splash does. Before ubusd exists there is nothing true to report, so the graph just grows, a node every second or so, for however long preinit takes. Once the bus is up the rest of the graph completes at once, the row of pictograms is built from /etc/rc.d/S*, and the packets that move afterwards are driven by real ubus activity rather than by a timer.

A stage appears only for a service that is actually enabled and has a pictogram, drawn dark until that service's own ubus object shows up, so a box without blockd never shows a storage icon rather than showing one that stays dark all boot. sysntpd registers no object at all and reports its sync through /etc/hotplug.d/ntp, which is the general escape hatch for a service with a hook but no object. Shutdown, reboot and sysupgrade take the graph apart instead of building it.

Roughly 5 ms a frame at every resolution from 640x480 to 3840x2160 on a Rock 5B, against a 33 ms budget at the default frame rate.

The xkeyboard-config commit

Not cosmetic and not optional: plymouth's meson.build does dependency('xkeyboard-config'), which cannot resolve unless that package stages its pkg-config file. Without it plymouth does not configure. It is first in the series and kept separate because it is a different package; happy to split it into its own PR if preferred.

Testing

Build tested for rockchip/armv8 (aarch64, musl) and run tested on a Radxa ROCK 5B driving an HDMI television, from power-on through the handover to the application that takes the display afterwards. The Theme= line written by the demo theme's postinst was verified in a freshly built rootfs, not just at runtime.

[openwrt]

Formality Check: Failed

We checked this pull request against the contribution guidelines. Here is what needs your attention:

🛑 CRITICAL ERRORS

Commit 3335c71 - plymouth-plugin-ucode: add a scripted splash plugin for ucode:

• New OpenWrt package is missing the mandatory parameter: 'PKG_LICENSE_FILES'

Commit 2a1fe10 - plymouth-theme-openwrt-demo: add a demo theme for the ucode engine:

• New OpenWrt package is missing the mandatory parameter: 'PKG_LICENSE_FILES'

Tip

Do not close this pull request to make corrections. Instead, modify your existing commits (e.g. git commit --amend) and update the branch using git push --force-with-lease --force-if-includes. The checks will re-run automatically.

---

_{Something broken? Consider reporting an issue.
Running version 26ec621 deployed on 2026-09-20 09:46:35 CEST}