From 7f9a4d4d4a30e90719a72f6523274b17cb0f2e08 Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 4 Sep 2026 12:02:45 -0400 Subject: [PATCH] FABRIC-3.md: three per-architecture bare-metal-boot planning sections Per direct instruction: amd64's real goal is genericity (any x86_64 laptop/desktop/tower/mini, not just the Beelink SER5 reference machine); aarch64 targets the Raspberry Pi 5 exclusively; riscv64 targets the Milk-V Mars exclusively -- no cross-board genericity requirement for the latter two, unlike amd64. Each section starts from what's already true (ROADMAP.md's existing v2.2.0/v2.4.0/v2.5.0 board-by-board gates, the already-built thumbdrive/iso-usb Makefile targets, the amd64 RDRAND backend) and names what's genuinely still unknown rather than assuming -- most notably whether the Milk-V Mars boots via UEFI (like this project's QEMU riscv64 target) or via U-Boot+OpenSBI+devicetree, which would need a different boot entry path, not just different peripheral addresses. Doc-only change, no acceptance build needed. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var --- FABRIC-3.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/FABRIC-3.md b/FABRIC-3.md index 61c7688..0eeab57 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -117,3 +117,90 @@ functional rollback. the prior tag placement was itself part of the same "got ahead of myself" correction, not a separate decision. No remote tag existed yet (`git ls-remote --tags origin` was empty for `v2.0.0`), so no destructive remote operation was needed, only a local move-and-push. +5. **Follow-up, same day**: `v2.0.1` (the working branch this and Task 1 happened on) deleted, + local and `origin` — confirmed a strict ancestor of `master`'s new HEAD first, so nothing + was lost. `master` is the repo's only branch from here on. + +--- + +## II. Three architectures, three different hardware scopes + +Per direct instruction, 2026-09-04. The real-hardware targets are **not** symmetric across +architectures — each gets its own section below because the actual scope of "done" is +different for each: + +- **amd64 — genericity is the goal, not just the SER5.** The Beelink SER5 is the machine in + hand and the development/reference target, but the real requirement is broader: this needs + to boot on *any* x86_64 machine — laptop, desktop, tower, or mini PC — not just one vendor's + quirks. SER5-only success is necessary but not sufficient; anything that works only because + of an SER5-specific assumption (a particular ACPI table shape, a specific UEFI + implementation's quirks) is a bug against this goal, not a deferred nice-to-have. +- **aarch64 — Raspberry Pi 5, and only the Raspberry Pi 5.** No genericity requirement across + aarch64 boards — this is the one and only target for this architecture. +- **riscv64 — Milk-V Mars, and only the Milk-V Mars.** Same as aarch64: one specific board, + not a generic riscv64-SBC goal. + +**How to use sections III–V below.** Same discipline as everything else in this series: plan +before building, one section at a time, iterating — not all three architectures in parallel, +and not front-loading a complete plan before any real hardware is in front of us. Each section +starts with what's already true (existing repo infrastructure, already-decided policy) and +what's still genuinely unknown, not assumed. + +## III. amd64 — generic x86_64 bare metal (reference hardware: Beelink SER5) + +**Already true, not to be re-derived:** +- `ROADMAP.md`'s "Board-by-board hardware rollout" already names this `v2.2.0`'s gate: the + generic GPT/FAT32 thumbdrive image (`make -f Makefile.starkernel ARCH=amd64 thumbdrive`, + already built — `Makefile.starkernel:1018`) flashes to and boots on the real SER5 via its + real UEFI, reaching POST + `ok>`, with the amd64 RDRAND entropy backend + (`src/starkernel/rng/rng.c`, already built and part of `master`) serving live entropy. +- `iso-usb` (`Makefile.starkernel:1060`) is the alternate, novice-friendly path (UEFI + isohybrid ISO for tools like GNOME Disks "Restore Disk Image...") — same underlying image, + different flashing UX. +- `FABRIC-2.md` §I.6's own 8-step physical-boot sequence (build ISO, identify the target + device, flash it, physically boot, decide an observation method, confirm POST, confirm + `ok>`, document) is the closest thing to an existing plan — but it predates the genericity + requirement and was written with no hardware in hand yet. + +**Genuinely open, not yet decided:** +- What "generic enough" actually needs to be verified against, beyond the SER5 — is there a + second, different machine available to cross-check against, or does genericity get argued + from firmware-standards-compliance (real UEFI, no vendor-specific assumptions in the boot + code) rather than a second physical test right away? +- Observation method for a headless/serial-less real machine (no QMP/serial socket the way + QEMU gives us) — HDMI + keyboard? A serial console cable if the board exposes UART pins? +- Whether Secure Boot needs handling, and how, on real UEFI firmware (QEMU/OVMF's own Secure + Boot behavior may not match every real vendor's). + +## IV. aarch64 — Raspberry Pi 5 + +**Already true:** `ROADMAP.md` names this `v2.4.0`'s gate: boots on the real board, aarch64 +peripheral-RNG backend live, Zuse mint/attach on real media. The peripheral-RNG backend itself +is **not yet built** — today's `rng_get_bytes()` (`src/starkernel/rng/rng.c`) only has a +`virtio-rng` path, real on QEMU, meaningless on real Pi 5 hardware (no virtio device there). + +**Genuinely open, not yet decided:** +- Raspberry Pi 5's own boot chain — UEFI (e.g. via the community EDK2 port) or the Pi's native + boot flow? This determines whether the existing UEFI-targeted boot code needs a different + entry path for this board at all, or just different ACPI/DTB-provided data. +- Which peripheral RNG the Pi 5 actually exposes, and how to read it (memory-mapped peripheral + vs. a firmware call) — not yet researched. +- Same observation-method question as amd64 (no QEMU serial socket on real hardware) — + possibly shared tooling/approach across both boards once decided once. + +## V. riscv64 — Milk-V Mars + +**Already true:** `ROADMAP.md` names this (generically, "Milk-V") as part of `v2.5.0`'s gate: +boots on the real board, the Zkr (RNDR) entropy backend live. Same gap as aarch64: +`rng_get_bytes()` has no riscv64 hardware-RNG path today, only `virtio-rng`. + +**Genuinely open, not yet decided:** +- Milk-V Mars's actual boot chain — this project's QEMU riscv64 target boots via UEFI + (EDK2 `RISCV_VIRT` firmware, confirmed in `Makefile.starkernel`'s own `qemu` recipe), but + real riscv64 SBCs commonly boot via U-Boot + OpenSBI + a devicetree instead of UEFI. Which + one the Mars actually uses is not yet confirmed — this is the single most consequential + unknown across all three sections, since it could mean this board needs a genuinely + different boot entry path, not just different peripheral addresses. +- Zkr/RNDR instruction availability on the Mars's actual CPU (riscv64 Scalar Crypto extension + support varies by implementation) — not yet confirmed. +- Same observation-method question as the other two boards.