docs: research notes on Plymouth graphical boot

Covers how mainstream distros implement boot splash (Plymouth from
initramfs, not kernel patches), the two SBo packages available, and a
two-stage plan for this machine.

Key finding: xe.ko is absent from the current initrd, so there is no
DRM device during the initrd phase and no surface for Plymouth to draw
on. That is the prerequisite for everything else.

Nothing installed or changed; research only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 340 insertions, 0 deletions

diff --git a/.extras/docs/plymouth-graphical-boot.md b/.extras/docs/plymouth-graphical-boot.md
new file mode 100644
index 0000000..04c8863
--- /dev/null
+++ b/.extras/docs/plymouth-graphical-boot.md
@@ -0,0 +1,340 @@
+# Graphical boot on Slackware with Plymouth
+
+Notes for replacing the plain-text boot wall with a graphical splash on this
+machine. Research only, nothing has been installed or changed yet.
+
+Written 2026-08-07. Everything under "Current system state" was measured on
+that date, on the running system, not assumed. Re-verify before acting if the
+kernel or hardware changed.
+
+---
+
+## Conclusions up front
+
+**Do not patch the kernel.** Distributions stopped patching kernels for boot
+splash around 2009. The old `bootsplash` and `fbsplash` patch sets are dead,
+and the in-kernel `bootsplash` revival (Max Staudt, ~2017) never reached
+mainline. `CONFIG_LOGO` still exists but only gives a 224-colour CLUT224 PPM
+logo, not an animated splash.
+
+**Everyone uses Plymouth**, a userspace daemon started from the initrd. Ubuntu,
+Mint, Debian, Fedora, all the same stack, differing only in theme.
+
+**SBo has both packages already**, so this is not a from-scratch port:
+
+| Package | Version | Notes |
+|---|---|---|
+| `system/plymouth` | 22.02.122 | `--disable-systemd-integration` already set, so it suits Slackware's BSD init |
+| `system/plymouth-slackware-theme` | 1.1 | Theme `slackware-logo`, based on an Arch theme, ships `/etc/plymouth/plymouthd.conf` |
+
+Neither package touches the initrd or the init scripts. **That wiring is the
+entire job** and it is all manual.
+
+---
+
+## How the other distributions do it
+
+The stack is identical everywhere:
+
+1. **Kernel cmdline** carries `quiet splash`. `quiet` suppresses printk output,
+   `splash` is a flag Plymouth reads.
+2. **KMS driver** loads early (in the initrd or builtin) and creates
+   `/dev/dri/card*`. Plymouth's `drm.so` renderer draws on it, falling back to
+   `frame-buffer.so` on `/dev/fb0`.
+3. **`plymouthd` runs from the initramfs**, started before the root pivot. On
+   Debian and Ubuntu an `initramfs-tools` hook at
+   `/usr/share/initramfs-tools/hooks/plymouth` copies the daemon, theme and
+   fonts into the image.
+4. **Handoff to the display manager.** With systemd, `plymouth-start.service`
+   runs `Before=display-manager.service` and `plymouth-quit.service` tears the
+   splash down once the DM owns the screen. Both draw through KMS, so there is
+   no mode switch and no flicker.
+5. **The daemon survives `switch_root`**, which is why it is a daemon and not a
+   static image. It also renders the LUKS passphrase prompt in graphics mode.
+
+Theme selection differs cosmetically:
+
+| Distro | Default theme | Selector |
+|---|---|---|
+| Ubuntu | `bgrt`, then spinner | `update-alternatives --config default.plymouth` |
+| Mint | `mint-logo` (script module) | same |
+| Debian | `spinner` / `moonlight` | same, then `update-initramfs -u` |
+| Fedora | `bgrt` / `charge` | `plymouth-set-default-theme -R` |
+
+`bgrt` is worth knowing about: on UEFI the firmware has already painted the
+vendor logo, and the kernel exposes that exact bitmap and position through the
+ACPI BGRT table. Plymouth reuses it, so the screen appears never to change
+between firmware and OS. It is the reason modern Ubuntu boots look seamless.
+
+**None of the above applies directly here.** It all assumes systemd units plus
+`initramfs-tools` or `dracut`. Slackware has neither.
+
+---
+
+## Current system state
+
+Measured 2026-08-07 on this machine.
+
+| Item | Value |
+|---|---|
+| Slackware | 15.0+ (-current) |
+| Kernel | 6.18.41 |
+| Bootloader | GRUB, EFI, config at `/boot/grub/grub.cfg`, ESP on `/dev/nvme0n1p1` |
+| Root | `/dev/myvg/root`, **LVM**, ext4 |
+| Initrd | `/boot/initrd-6.18.41.img`, 16M, symlinked as `initrd-generic.img` |
+| `/boot/initrd-tree` | **Does not exist**, initrd is built directly by `mkinitrd -c` |
+| Runlevel | 4 (`id:4:initdefault:`) |
+| Display manager | SDDM (`/usr/bin/sddm`), no `rc.4.local` present |
+| GPU | Intel, PCI id `e20b` (Panther Lake, per `ptl_*` firmware in the module) |
+| GPU driver | `xe`, **loadable module**, currently loaded, 3.7M, 56 refs |
+| Plymouth | Not installed |
+
+Current kernel command line:
+
+```
+GRUB_CMDLINE_LINUX_DEFAULT="i915.force_probe=!e20b xe.force_probe=e20b"
+```
+
+`GRUB_GFXPAYLOAD_LINUX=keep` is already set, which is what you want: the
+graphics mode set by GRUB carries into the kernel.
+
+The initrd was generated by:
+
+```
+/sbin/mkinitrd -c -k 6.18.41 -f ext4 -r /dev/myvg/root \
+  -m xhci-pci:ohci-pci:ehci-pci:xhci-hcd:uhci-hcd:ehci-hcd:hid:usbhid:i2c-hid:hid_generic:hid-asus:hid-cherry:hid-logitech:hid-logitech-dj:hid-logitech-hidpp:hid-lenovo:hid-microsoft:hid_multitouch \
+  -L -u -L -R -o /boot/initrd-6.18.41.img
+```
+
+That string is stored inside the image as `/command_line`, so it can always be
+recovered from the initrd itself.
+
+### The finding that matters most
+
+**`xe.ko` is not in the initrd.** The only DRM-related module present is
+`drm.ko`, pulled in as a dependency of something else. Verified by extracting
+the image and listing every `.ko`:
+
+```
+asus-wmi  dm-bufio  dm-snapshot  drm  ehci-hcd  ehci-pci  hid-asus
+hid-cherry  hid-generic  hid-lenovo  hid-logitech  hid-logitech-dj
+hid-logitech-hidpp  hid-microsoft  hid-multitouch  hid  i2c-hid
+ohci-hcd  ohci-pci  platform_profile  rfkill  sparse-keymap  uhci-hcd
+usbhid  video  wmi  xhci-hcd  xhci-pci
+```
+
+`drm.ko` alone creates no `/dev/dri/card*`. Without the actual GPU driver,
+Plymouth's `drm.so` renderer has nothing to draw on during the initrd phase, so
+the splash cannot start until after the pivot. That is the difference between a
+seamless boot and a splash that shows up halfway through, which looks worse
+than no splash at all.
+
+So adding `xe` to the initrd is a **prerequisite**, not an optimisation.
+
+---
+
+## Plan
+
+Two stages. Stage one is reversible in seconds and may be all that is wanted.
+
+### Stage 1: silence the text wall (no Plymouth, no initrd work)
+
+Append `quiet loglevel=3` to the existing cmdline, keeping the force_probe
+flags:
+
+```
+GRUB_CMDLINE_LINUX_DEFAULT="i915.force_probe=!e20b xe.force_probe=e20b quiet loglevel=3"
+```
+
+Then regenerate:
+
+```
+grub-mkconfig -o /boot/grub/grub.cfg
+```
+
+This alone removes the scrolling kernel messages. No packages, no initrd
+changes, nothing that can prevent a boot. Optionally add
+`vt.global_cursor_default=0` to suppress the blinking cursor.
+
+**If this is enough, stop here.**
+
+### Stage 2: actual Plymouth splash
+
+Ordered by dependency. Do not skip step 1.
+
+#### 2.1 Get `xe` into the initrd, and confirm it still boots
+
+Rebuild with `xe` added to the module list, keeping every existing flag from
+`/command_line`:
+
+```
+/sbin/mkinitrd -c -k 6.18.41 -f ext4 -r /dev/myvg/root \
+  -m xhci-pci:ohci-pci:ehci-pci:xhci-hcd:uhci-hcd:ehci-hcd:hid:usbhid:i2c-hid:hid_generic:hid-asus:hid-cherry:hid-logitech:hid-logitech-dj:hid-logitech-hidpp:hid-lenovo:hid-microsoft:hid_multitouch:xe \
+  -L -u -L -R -o /boot/initrd-plymouth.img
+```
+
+Note the **different output name**. Keep `initrd-6.18.41.img` untouched as the
+known-good fallback, and add a second GRUB entry pointing at the new image. See
+"Safety" below.
+
+Firmware is the catch. `xe` declares 39 firmware files, and `/lib/firmware/xe`
+is 5.5M (`/lib/firmware/i915` is another 27M, and the `xe` module references
+`i915/*` blobs too for older parts). For this GPU only the `ptl_*` files should
+be needed:
+
+```
+xe/ptl_guc_70.bin
+xe/ptl_huc.bin
+```
+
+`mkinitrd -u` pulls firmware automatically, but verify after building that
+those files are actually inside the image. Missing GuC/HuC firmware makes the
+driver fail or fall back, and the splash goes with it.
+
+Boot this and confirm the system still comes up before going further.
+
+#### 2.2 Install the packages
+
+```
+sbopkg -i plymouth
+sbopkg -i plymouth-slackware-theme
+```
+
+The theme drops `/usr/share/plymouth/themes/slackware-logo/` and
+`/etc/plymouth/plymouthd.conf` containing:
+
+```
+[Daemon]
+Theme=slackware-logo
+```
+
+#### 2.3 Populate the initrd with Plymouth
+
+Upstream ships `plymouth-populate-initrd`, but it is written for
+dracut/initramfs-tools layouts and will not slot into Slackware's initrd-tree
+cleanly. Expect to copy by hand.
+
+Required inside the image:
+
+- `plymouthd` and the `plymouth` client binary
+- `/usr/lib64/plymouth/renderers/drm.so` and `frame-buffer.so`
+- `/usr/share/plymouth/themes/slackware-logo/` in full
+- `/etc/plymouth/plymouthd.conf`
+- the label plugin **and its fonts**, if the theme draws any text
+- every shared library the above link against (check with `ldd`)
+
+The font omission is the classic failure: the theme renders blank or partially,
+and it is not obvious why.
+
+Since `/boot/initrd-tree` does not exist, either create one with
+`mkinitrd -s`, add the files there and rebuild from it, or unpack the generated
+image, add the files, and repack. The tree approach is more repeatable.
+
+#### 2.4 Start the daemon inside the initrd
+
+`/init` in the initrd is `#!/bin/ash`. Module loading happens through
+`/load_kernel_modules`, which is a plain list of `modprobe -v` lines.
+
+After the DRM module is up and before any LUKS prompt, add:
+
+```sh
+plymouthd --mode=boot --attach-to-session
+plymouth show-splash
+```
+
+Ordering matters: `xe` must already be loaded, otherwise there is no
+`/dev/dri/card0` to render to.
+
+#### 2.5 Kernel cmdline
+
+```
+GRUB_CMDLINE_LINUX_DEFAULT="i915.force_probe=!e20b xe.force_probe=e20b quiet splash"
+```
+
+`splash` is the flag Plymouth looks for. Keep `GRUB_GFXPAYLOAD_LINUX=keep`.
+
+#### 2.6 Quit the splash at the right moment
+
+There is no systemd, so nothing tears the splash down automatically. Runlevel
+is 4 and the display manager is SDDM, started from the end of `/etc/rc.d/rc.4`.
+
+`rc.4` `exec`s the DM, so anything appended after that never runs. The call has
+to go **before** the `exec` chain, or into `/etc/rc.d/rc.4.local`, which `rc.4`
+checks for first and which does not currently exist. `rc.4.local` is the
+cleaner hook because it leaves the stock script untouched, but note it also
+`exec`s, so it would have to start SDDM itself.
+
+```sh
+/usr/bin/plymouth quit --retain-splash
+```
+
+`--retain-splash` leaves the last frame on screen so SDDM can fade in over it
+rather than flashing a bare console. For a console-only boot, call
+`plymouth quit` at the end of `rc.M` instead.
+
+---
+
+## Known problem areas
+
+**`switch_root` continuity.** This is the most likely thing to consume time.
+`plymouthd` holds the VT, and its socket lives in `/run`. The daemon must not be
+killed when the initramfs is torn down, and the real root needs a matching
+`/run` for the client to reconnect. Get it wrong and the splash dies at the
+pivot, dropping to a text wall for the second half of boot. Note that `/run` in
+the current initrd is an empty directory.
+
+**LVM plus splash ordering.** Root is on `/dev/myvg/root`, so LVM activation
+happens in the initrd. Plymouth should be started before that, so the splash
+covers the LVM and filesystem phase rather than appearing after it.
+
+**Firmware bloat.** Pulling all of `/lib/firmware/xe` plus the `i915` blobs the
+module references would add a lot to a 16M initrd. Restrict to the `ptl_*`
+files needed by this GPU.
+
+**Kernel updates.** Every kernel bump means rebuilding the initrd, and the
+Plymouth files have to be re-added each time unless the initrd-tree is kept
+around. This is ongoing maintenance, and the main argument for stopping at
+stage 1.
+
+**`plymouth-populate-initrd` will not work unmodified.** It assumes a
+dracut/initramfs-tools layout.
+
+---
+
+## Safety
+
+The initrd is on the boot path. A broken one means no boot, and repair requires
+install media.
+
+Before any stage 2 work:
+
+1. Build to a **new filename** (`initrd-plymouth.img`), never overwrite
+   `initrd-6.18.41.img`.
+2. Add a **second GRUB menu entry** pointing at the new initrd, keeping the
+   working entry as the default until the new one is proven.
+3. Keep install media reachable.
+
+`GRUB_DEFAULT=0` and `GRUB_TIMEOUT=10` currently, so there is a visible menu to
+choose from, which is what makes the fallback entry usable.
+
+---
+
+## References
+
+- Both SBo READMEs point at an LQ thread for Slackware-specific instructions:
+  <https://www.linuxquestions.org/questions/slackware-14/bootsplash-4175742241/>
+  It was not readable at the time of writing (LQ returns HTTP 403 to
+  automated fetches), so **it has not been incorporated here**. Read it
+  manually before starting stage 2, it may well cover the `switch_root` and
+  initrd-population details that are the hard part.
+- Theme upstream: <https://github.com/murkl/plymouth-theme-arch-os>
+- Plymouth upstream:
+  <https://www.freedesktop.org/wiki/Software/Plymouth/>
+
+---
+
+## Status
+
+Nothing installed, nothing modified. Stage 1 is a two-line change whenever
+wanted. Stage 2 is unstarted, and step 2.1 (`xe` in the initrd) is the gate for
+everything after it.