diff options
Diffstat (limited to '.extras/docs')
| -rw-r--r-- | .extras/docs/plymouth-graphical-boot.md | 340 |
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. |