doc: add ISO boot documentation, efifb display chain, and BusyBox reference

New files:
- doc/index.md: documentation index with one-line summary per doc file
- doc/iso_boot.md: ISO boot parameter reference — details every kernel
  parameter injected, which initramfs framework uses it, parameter value
  rules, known limitations (Debian DVD installer, efifb framebuffer chain);
  credits u-root's boot/iso package as inspiration for the layered approach
  (u-root/u-root#3578)
- doc/busybox_perks.md: BusyBox v1.36.1 vs GNU command differences for
  every tool used in initrd scripts; documents sort -k1 -u incompatibility
  where BusyBox sort -u deduplicates by entire line, not by sort key
- doc/modules.md: module list from Makefile showing which tools are
  BusyBox applets vs standalone binaries

Updated files:
- doc/architecture.md: add display output after kexec section with ASCII
  diagram showing the full chain: coreboot/libgfxinit -> VIDEO_TYPE_EFI
  -> Heads efifb -> kexec-tools -> target kernel efifb; documents the
  smem_start limitation (Linux no longer leaks physical fb address);
  notes that current efifb approach is suboptimal (waiting for upstream
  fixes); TPM DUK is the only supported workaround for LUKS passphrase
  on blank display
- doc/boot-process.md: add Stage 2b (USB ISO Boot) section covering
  kexec-iso-init.sh flow (Layer 1 initrd compat, Layer 2 loopback.cfg,
  Layer 3 kexec-select-boot), compat markers legend, and parameter
  injection
- doc/logging.md: update ANSI policy — codes are preserved in debug.log
  for less -R rendering; remove _strip_ansi references and "MUST NOT
  appear in debug.log" language
- doc/ux-patterns.md: document boot option format and compat markers
- initrd/bin/kexec-iso-init.sh: add u-root boot/iso credit in header
  and Layer 2 section

Signed-off-by: Thierry Laurion <insurgo@riseup.net>

Author: tlaurion

doc/architecture.md

@@ -87,7 +87,7 @@ Changes to user configuration are persisted by reflashing the ROM (CBFS operatio
 The top-level `Makefile` orchestrates:
 
 - Cross-compiler (`musl-cross-make`, target: `x86_64-linux-musl` or `powerpc64le-linux-musl`)
-- Modules (coreboot, Linux, busybox, GPG, cryptsetup, kexec, LVM2, …)
+- Modules (coreboot, Linux, busybox, GPG, cryptsetup, kexec, LVM2, zstd, … — see [modules.md](modules.md) for the full list)
 - Six CPIO archives assembled into the initrd:
   1. `dev.cpio` — device nodes
   2. `modules.cpio` — kernel modules
@@ -119,3 +119,91 @@ The CI pipeline's workspace and cache behavior is documented in
 - **Fail-closed** — failed verification drops to authenticated recovery shell, not an unverified OS boot
 - **Separation of duties** — the key that signs `/boot` lives on a hardware security dongle, never in the ROM
 - **Auditability** — all source is open, builds are reproducible, ROM images are verifiable
+
+---
+
+## Display output after kexec
+
+```
+                                                                     kexec boundary
+                      ┌──────────────────────────────────────────────────┐
+                      │                DISPLAY CONTROLLER                │
+                      │  (initialised by coreboot, continuously scans    │
+                      │   out from framebuffer at physical address X)    │
+                      └──────────────────────┬───────────────────────────┘
+                                             │ reads pixels from
+                                             ▼
+                                    ┌────────────────┐
+                                    │  scanout buf   │
+                                    │  @ phys addr X │
+                                    └────────────────┘
+                                             ▲
+                      ───────────────────────┼──────────────────────────────
+   Heads side                                │                    OS side
+                                             │
+ ┌──────────────────────────┐       ┌───────────────────────────────┐
+ │  coreboot/libgfxinit     │       │  target kernel (after kexec)  │
+ │  - initialises display   │       │  sysfb_init() reads boot      │
+ │  - sets VIDEO_TYPE_EFI   │       │  params → VIDEO_TYPE_EFI      │
+ │    in screen_info        │       │  → "efi-framebuffer" device   │
+ └────────────┬─────────────┘       │  → efifb binds                │
+              │                     │  BUT: lfb_base == 0           │
+              ▼                     │  → efifb_probe fails          │
+ ┌──────────────────────────┐       │  → no /dev/fb0                │
+ │  Heads kernel            │       │  → initramfs display blank    │
+ │  sysfb_init() → sees     │       └───────────────────────────────┘
+ │  VIDEO_TYPE_EFI          │
+ │  → "efi-framebuffer"     │       ┌───────────────────────────────┐
+ │  → efifb binds           │       │  DRM driver (post-switchroot) │
+ │  → Heads GUI visible     │       │  i915 reinitialises display  │
+ └────────────┬─────────────┘       │  → framebuffer works again   │
+              │                     └───────────────────────────────┘
+              │
+              ▼
+ ┌──────────────────────────┐
+ │  kexec-tools             │
+ │  opens /dev/fb0 → reads  │
+ │  fb parameters           │
+ │  fix.id = "EFI VGA" ✓    │
+ │  smem_start = 0 ✗        │
+ │  (kernel hid it)         │
+ │  writes to new kernel    │
+ │  boot params:            │
+ │  orig_video_isVGA = EFI  │
+ │  lfb_base = 0            │
+ └──────────────────────────┘
+```
+
+Heads' initrd runs under a kernel compiled with `CONFIG_FB_EFI=y`.
+coreboot/libgfxinit initialises the display hardware (PLL, timings,
+scanout buffer) and presents it to Linux as an efifb-compatible
+framebuffer (`screen_info` set to `VIDEO_TYPE_EFI`).  Heads' kernel
+binds efifb, maps the scanout buffer, and the Heads console and
+whiptail GUI are visible.  Without this, Heads would have no
+framebuffer at all.
+
+After kexec, the display hardware remains in its initialised state
+(kexec does not reset devices — the controller keeps scanning out
+from the same physical address).  The target kernel must also have
+`CONFIG_FB_EFI=y` to adopt the same framebuffer — simplefb and
+simpledrm are not compatible because the scanout buffer was set up
+as an efifb-compatible buffer by coreboot, not as a simplefb buffer.
+
+**Known limitation — lost framebuffer address:**
+
+Linux no longer exposes the physical framebuffer address to userspace.
+kexec-tools obtains `smem_start = 0` from `FBIOGET_FSCREENINFO` and
+writes `lfb_base = 0` into the new kernel's boot params.  The target
+kernel's efifb sees a zero address and cannot map the framebuffer —
+the display stays blank even though the controller is still scanning
+out the correct memory (set up by coreboot, preserved through kexec).
+
+Historically, Heads worked around this by using i915 with
+`CONFIG_DRM_FBDEV_LEAK_PHYS_SMEM=y` (leaking the physical address),
+but that was suboptimal.  The current efifb approach is also
+suboptimal — we are waiting for improvements in coreboot, Linux, and
+kexec-tools to properly convey the framebuffer state across kexec.
+
+**TPM Disk Unlock Key** works around this for encrypted disks by
+injecting the LUKS key before kexec — the initramfs never prompts for
+a passphrase on a blank display.  Serial console is unaffected.

doc/boot-process.md

@@ -122,6 +122,97 @@ menu, system info, power off.
 
 ---
 
+## Stage 2b: USB ISO Boot (`kexec-iso-init.sh`)
+
+When booting from an ISO file on USB media, `kexec-iso-init.sh` handles the ISO
+boot flow. It is invoked from the "USB ISO Boot" option in the main menu.
+
+### Flow
+
+1. **Signature verification**: Check for `.sig` or `.asc` detached signature
+2. **Mount ISO**: Mount the ISO file as loopback device at `/boot`
+3. **Layer 1 — initramfs fs compatibility check** (`check_initrd_fs_compat`):
+   Before presenting boot options, verify the ISO's initramfs contains kernel
+   modules for the USB partition's filesystem (ext4/vfat/exfat).  If the initrd
+   can't read the USB filesystem, the kernel won't find the ISO after kexec.
+   - Parsing boot configs for initrd paths (instead of searching the whole ISO)
+   - Unpacking each initrd and checking for required `.ko` files and
+     `modules.builtin`
+   - Each initrd gets its own independent `[OK]` / `[!]` / (blank) marker in
+     `/tmp/kexec_initrd_compat.txt` (the per-initrd flag `initrd_supports_fs` is tracked
+     separately from the global `any_supported` flag, so no initrd is silently
+     skipped)
+   - `[OK]` = initrd has the needed module as `.ko`, has it in
+     `modules.builtin`, or has no `.ko` files at all (minimal initrd with
+     everything built into the kernel — nothing to check against).
+   - `[!]`  = initrd has loadable kernel modules but none for the USB
+     filesystem type.  No built-in assumption — we report what we find.
+   - Read-only filesystems (iso9660/squashfs/udf) and unmapped fstypes skip
+   - All initrds are checked (no early break) so the compat file is complete.
+4. **Layer 2 — loopback.cfg fast path**: If the ISO has a `loopback.cfg`, parse
+   it and resolve GRUB variables (`${iso_path}`, `${isofile}`) to extract the
+   ISO kernel params from loopback entries.
+5. **Boot param injection**: When Layer 2 resolves nothing (no GRUB vars found
+   in loopback.cfg), all common ISO boot methods are injected unconditionally
+   as kernel ADD params so the ISO initrd can pick whichever it supports:
+   - `iso-scan/filename=/$ISO_PATH` — Ubuntu casper, Fedora dracut
+   - `findiso=/$ISO_PATH` — Debian live-boot, NixOS stage-1
+   - `img_dev=/dev/disk/by-uuid/$DEV_UUID` — block device containing the ISO
+   - `img_loop=$ISO_PATH` — loopback file path (relative)
+   - `iso=$DEV_UUID/$ISO_PATH` — UUID/path alternative
+   - `live-media=/dev/disk/by-uuid/$DEV_UUID` — device filter (casper, live-boot)
+   The kernel ignores parameters it doesn't understand.
+   `fromiso=` is intentionally not injected because it conflicts with `findiso=`
+   in Debian live-boot's `check_dev()` — `fromiso` mounts the ISO, then `findiso`
+   looks for the ISO file inside the mounted ISO (not found), unmounts it,
+   leaving orphaned loop devices that get re-scanned → infinite loop.
+   `findiso=` alone covers Debian and NixOS.
+   `live-media-path=` is intentionally not injected because the default differs
+   per distro (`/live` for Debian, `/casper` for Ubuntu/PureOS, `/LiveOS` for
+   Fedora); leaving it unset lets each distro use its own default.
+6. **Layer 3 — kexec-select-boot**: Launch the standard boot menu with `-u`
+   (unique entries, dedup sorted by name).
+
+### Initrd compatibility markers in the boot menu
+
+During Layer 1, `check_initrd_fs_compat` writes per-initrd results to
+`/tmp/kexec_initrd_compat.txt`.  `kexec-select-boot` reads this file and shows
+`[OK]` or `[!]` at the start of each menu line (before the entry name):
+
+| Marker | Meaning | Behavior |
+|--------|---------|----------|
+| `[OK]` | Initrd has the USB fs module (as .ko or modules.builtin) | Boot should work |
+| `[!]`  | Initrd has loadable modules but none for the USB fs type | May fail after kexec |
+| (blank) | Initrd has zero .ko files — can't verify either way | Assume OK (minimal initrd) |
+| (none) | Entry has no initrd (memtest, etc.) | No filesystem dependency |
+
+A `NOTE` (3-second sleep, cannot scroll past) is displayed before the menu
+explaining the legend.  Markers follow `doc/logging.md` accessibility rules:
+text-based, serial-safe, not color-dependent.
+
+### Compatibility note for ext4 and vfat
+
+Initrds with no `.ko` files at all get no marker at all (blank) — we can't
+verify either way, so nothing is displayed.
+
+### Boot param injection
+
+When Layer 2 (loopback.cfg) resolves no GRUB variables, the following
+parameters are injected unconditionally so the ISO initrd can find the USB
+partition and the ISO file after kexec, regardless of which distribution's
+init system it uses:
+
+| Parameter | Example | Used by |
+|-----------|---------|---------|
+| `iso-scan/filename=` | `/ISOs/foo.iso` | Ubuntu casper, Fedora dracut |
+| `findiso=` | `/ISOs/foo.iso` | Debian live-boot, NixOS stage-1 |
+| `img_dev=` | `/dev/disk/by-uuid/UUID` | Block device hint |
+| `img_loop=` | `ISOs/foo.iso` | Loopback path |
+| `iso=` | `UUID/ISOs/foo.iso` | Alternative path |
+| `live-media=` | `/dev/disk/by-uuid/UUID` | Device filter (casper, live-boot) |
+
+---
+
 ## Stage 3: kexec-select-boot
 
 Called from the boot menu. Responsible for final verification and OS handoff.

doc/busybox_perks.md

@@ -0,0 +1,150 @@
+# BusyBox vs GNU: Heads usage reference
+
+Heads initrd scripts run under BusyBox v1.36.1, not GNU coreutils.
+This documents every command usage across Heads scripts and the BusyBox
+adaptations required.
+
+## dd
+
+BusyBox `dd` supports `status=`, `iflag=`, `oflag=` the same as GNU.
+
+**Usage in Heads**:
+```bash
+dd if="$file" bs=6 count=1 status=none   # kexec-iso-init.sh:
+dd bs=1 count=1 status=none              # unpack_initramfs.sh:38
+dd bs="$segment_end" count=1 status=none # unpack_initramfs.sh:101
+```
+
+## xxd
+
+**BusyBox quirk**: `xxd -p` pads the last line to 60 columns with spaces.
+GNU xxd does not pad.
+
+**Usage in Heads**:
+```bash
+# Good — strips padding:
+next_byte="$(dd bs=1 count=1 status=none | xxd -p | tr -d '\n ')"  # unpack_initramfs.sh:38
+magic="$(dd if="$f" bs=6 count=1 status=none | xxd -p | tr -d '\n ')" # unpack_initramfs.sh:68
+
+# Reverse — needs fold workaround (from etc/functions.sh:2701):
+fold -w 60 | xxd -p -r
+```
+
+## cpio
+
+**BusyBox quirk**: Stops at first TRAILER. GNU reads past it and exits 2.
+
+**Heads pattern**: `cpio -i -d "${CPIO_ARGS[@]}" 2>/dev/null || true`
+The `|| true` handles GNU's exit 2 on multi-segment archives.
+
+For multi-segment extraction (`unpack_initramfs.sh:94-106`), the TRAILER offset
+is pre-computed and dd limits cpio's input to exactly one segment, so both
+BusyBox and GNU behave identically.
+
+## grep
+
+**BusyBox**: no `-a` flag, but treats binary as text by default.
+
+**Heads usage**: `grep -F -b -o "TRAILER!!!" "$file" 2>/dev/null` at `unpack_initramfs.sh:76`.
+The `-a` flag is not needed — BusyBox treats binary as text by default; GNU grep handles it without `-a` too.
+
+**Heads pattern**: `grep -F -b -o "TRAILER!!!" "$file" 2>/dev/null | head -1 | cut -d: -f1 || true`
+
+## stat
+
+Identical for `stat -c %s FILE`.
+
+**Usage in Heads**:
+```bash
+orig_size="$(stat -c %s "$unpack_archive")"        # unpack_initramfs.sh:127
+rest_size="$(stat -c %s "$rest_archive")"            # unpack_initramfs.sh:128
+rest_size="$(stat -c %s "$next_archive" 2>/dev/null || echo 0)" # unpack_initramfs.sh:147
+```
+
+## find
+
+**Usage in Heads** (all supported by BusyBox):
+```bash
+find "$dir" -name "*.ko*" -type f 2>/dev/null | head -1  # kexec-iso-init.sh
+find "$dir" -name '*.cfg' -type f 2>/dev/null            # kexec-iso-init.sh
+find "$dir" -name "*.ko*" 2>/dev/null | grep -q "ext4"    # kexec-iso-init.sh
+```
+
+## gunzip / gzip / zcat
+
+Identical. Used via pipe in segment decompression:
+```bash
+gunzip | unpack_cpio   # unpack_initramfs.sh:111
+```
+
+## unxz / xzcat
+
+Identical:
+```bash
+unxz | unpack_cpio    # unpack_initramfs.sh:115
+```
+
+## zstd / zstd-decompress
+
+**Standalone binary** compiled at `build/x86/zstd-1.5.5/programs/zstd-decompress`
+and included in the initrd via `Makefile:745` (`CONFIG_ZSTD`). Not a BusyBox
+applet, but available in all boards with `CONFIG_ZSTD=y`.
+
+Usage via pipe (`unpack_initramfs.sh:119`):
+```bash
+zstd-decompress -d < input.zst   # reads stdin, writes stdout
+```
+
+**Current code**: `(zstd-decompress -d 2>/dev/null || zstd -d 2>/dev/null || true) | unpack_cpio`
+— should work if `CONFIG_ZSTD=y` in the board config.
+
+## sed
+
+Identical for all patterns used in Heads:
+```bash
+sed 's|^/dev/||'          # kexec-iso-init.sh (path stripping)
+sed 's/^append //'         # kexec-iso-init.sh (param extraction)
+sed 's/^initrd //'         # kexec-iso-init.sh (field extraction)
+sed "s|\${$var}|$val|g"    # kexec-iso-init.sh (GRUB var resolution)
+```
+
+## awk
+
+BusyBox awk is minimal but sufficient for Heads usage:
+```bash
+awk -v dev="$dev" 'index($1, dev) == 1 { print $3; exit }' /proc/mounts
+awk '{print $2}' /proc/mounts
+```
+
+## cut / head / tr / uniq / fold / basename / dirname / readlink
+
+All identical for Heads usage. No special BusyBox workarounds needed.
+
+## sort
+
+**BusyBox quirk**: `sort -k` keyed sort with `-u` deduplicates based on the
+**entire line**, not the sort key.  GNU sort deduplicates by the key alone.
+
+**Heads pattern**: Use `awk -F'|' '!seen[$1]++'` instead of `sort -t\| -k1 -u`
+when deduplicating by a single field:
+```bash
+# Wrong under BusyBox (dedups by full line, not field 1):
+sort -t\| -k1 -u
+
+# Correct under both:
+awk -F'|' '!seen[$1]++'
+```
+
+## cat / mv / rm / mkdir / mktemp / printf / wc / xargs / echo
+
+All identical. No BusyBox workarounds needed.
+
+## Summary of required BusyBox workarounds
+
+| Command | Workaround | Where |
+|---------|------------|-------|
+| `xxd -p` | `tr -d '\n '` strips 60-col padding | `unpack_initramfs.sh:38,68` |
+| `xxd -p -r` | `fold -w 60 \| xxd -p -r` | `etc/functions.sh:2701` |
+| `cpio` trailing data exit | `|| true` swallows GNU exit 2 | `unpack_initramfs.sh:52,101` |
+| `grep -a` | Omit or keep (no-op on both) | `unpack_initramfs.sh:78` |
+| `zstd` not available | `(zstd-decompress -d \|\| zstd -d \|\| true)` fails silently | `unpack_initramfs.sh:119` |

doc/index.md

@@ -0,0 +1,16 @@
+# Heads documentation index
+
+Quick reference — read the relevant doc when working on a topic.
+
+| File | What it covers |
+|------|----------------|
+| `architecture.md` | System architecture: coreboot → kernel → initrd, build system, config hierarchy |
+| `boot-process.md` | Boot flow stages, ISO boot layers (Layer 1/2/3), [OK]/[!] marker legend |
+| `busybox_perks.md` | GNU vs BusyBox command differences for all tools used in initrd scripts |
+| `docker.md` | Docker-based build environment |
+| `logging.md` | Log levels (STATUS, WARN, NOTE, INFO, DEBUG, TRACE) usage conventions |
+| `modules.md` | Available tools: which are BusyBox applets vs standalone binaries |
+| `security-model.md` | TPM, measured boot, trust chain |
+| `tpm.md` | TPM 1.2 and 2.0 operations |
+| `ux-patterns.md` | User interaction patterns (whiptail, CLI menu, confirm dialogs) |
+| `iso_boot.md` | ISO boot parameter reference — what each kernel param does and which framework uses it |