From 1ec2a2938461fc7a0f2dcedca607a889d6818acc Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 4 Sep 2026 12:52:37 -0400 Subject: [PATCH] FABRIC-3.md: aarch64 (Pi 5) planning decided + punch list Decisions from conversation: observation is HDMI-only for this board's own bring-up (no second Pi, no dedicated USB-serial adapter; using the Milk-V Mars as a bridge before it's independently validated would be circular). Both boards arrive 2026-09-17, giving real runway to finish design/code work first ("plan well before doing"). Traced boot_info->acpi_table's actual aarch64 consumers against real code before writing the punch list: only pci_init() (unconditional, relevant since RP1 is PCIe-attached) and this session's own running_under_hypervisor() (already degrades safely on NULL). GIC init (arch/aarch64/apic.c) already only tries boot_info->dtb, never acpi_table -- Pi 5 native boot removes its stated blocker for free. 6-item no-hardware-needed punch list: entry stub at 0x80000, a DTB -> BootInfo constructor calling the existing unmodified kernel_main() (the crux of why most of M1-M9 stays shared), the mailbox-interface framebuffer driver, an fdt.c node-scoped-lookup extension (its own header already flagged this as a known future need), a DTB-based pci_init() path for RP1, and config.txt contents. Plus 5 items deliberately deferred until hardware is in hand 2026-09-17. Also fixed a formatting slip from an in-progress edit (a bullet accidentally turned into a malformed heading) before it could compound. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var --- FABRIC-3.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 3 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index 9f05dc6..c25cd0b 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -209,9 +209,18 @@ peripheral-RNG backend live, Zuse mint/attach on real media. The peripheral-RNG 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:** -- Same observation-method question as amd64 (no QEMU serial socket on real hardware) — - possibly shared tooling/approach across both boards once decided once. +**Decided in conversation, 2026-09-04:** +- **Observation: HDMI-only for this board's own bring-up.** No second Pi, no dedicated + USB-serial adapter available. The Milk-V Mars could in principle serve as a GPIO-UART + bridge once it arrives (same 40-pin-header shape as the SER5 plan), but using it to observe + the Pi 5 before the Mars has been independently validated itself would be a chicken-and-egg + dependency, not a real plan. Revisit serial capture later if genuinely needed, once at least + one board is proven working — not a blocker for this pass. +- **Both boards (Pi 5, Milk-V Mars) arrive 2026-09-17.** Real runway exists to finish the + design/code work below *before* any hardware is in hand — "plan well before doing," per + direct instruction. + +**Still genuinely open, not yet decided:** - **A pinned GPIO VM, theory-stage** — see `FABRIC-4.md` §2. Raised in conversation, not yet scoped; downstream of §IV.1's own native-boot-flow work (a GPIO VM needs GPIO addresses from the DTB the same way the rest of this bring-up does). @@ -279,6 +288,58 @@ to target right now — this needs either a Broadcom datasheet (if one becomes a direct hardware probing once the board is in hand (scan the known BCM2711 RNG200 offset region on the BCM2712 memory map and see if anything responds — risky without a datasheet confirming it's safe to touch, so likely a "board in hand, careful probe" task, not a today task). +Deliberately **not a blocker for the first native boot** — reaching `ok>` doesn't require a +live entropy backend; `rng_get_bytes()` already has a "no entropy backend available" WARNING +path (`rng.c`) rather than a hard failure, so this can land after boot succeeds. + +### IV.3 — Punch list: design/code work, no hardware needed (before 2026-09-17) + +Traced against real code before writing this, not estimated: `boot_info->acpi_table`'s only +aarch64-relevant consumers today are `pci_init()` (`kernel_main.c:589`, unconditional, not +amd64-gated — relevant because RP1 is PCIe-attached on real Pi 5 hardware) and this session's +own `running_under_hypervisor()` (`arch/aarch64/timer.c`, already degrades safely to "not a +hypervisor" when `acpi_table` is `NULL` — no fix needed there). +`ioapic_init()`/`i8042_init()` are `#ifdef ARCH_AMD64`-gated, irrelevant here. +`arch/aarch64/apic.c` (GIC init) already only ever tries `boot_info->dtb`, never +`acpi_table` — its own doc comment already anticipated DTB-based discovery, just blocked +until now because QEMU's own UEFI firmware never publishes one; Pi 5 native boot removes that +blocker for free. + +1. **Entry stub**: new `boot/native_rpi5_entry.S` (or similar) — linked at `0x80000`, receives + `x0` = DTB pointer per the researched protocol (§IV.1), minimal early setup (stack — either + a small fixed BSS region, matching `BootInfo.kernel_stack_base`'s existing "zero = fall + back to 2 MiB BSS stack" convention, or something new if that's insufficient this early). +2. **DTB → `BootInfo` constructor**: new C function populating the *existing* `BootInfo` + struct (`include/starkernel/uefi.h`) from the DTB instead of UEFI protocols — `dtb` = the + real pointer, `acpi_table` = `NULL` (already the correct value for "no ACPI," per IV's own + research above), `runtime_services` = `NULL`, `memory_map`/`framebuffer`/`args` populated + from DTB `/memory`+`/reserved-memory`, the mailbox interface (next item), and DTB `/chosen` + `bootargs` respectively. Then calls the **existing, unmodified** `kernel_main()` — this is + the crux of why most of M1–M9 stays shared. +3. **Mailbox-property-interface framebuffer driver** — genuinely new code (§IV.1's own + assessment), populating `BootInfo.framebuffer` the same shape UEFI GOP currently does, so + `console.c`/`vt100.c`/`framebuffer.c` need no changes at all downstream. +4. **`fdt.c`/`fdt.h` extension**: today's reader only supports "first match anywhere in the + tree" (`fdt_find_prop`'s own doc comment) — sufficient for the single global properties + used so far (riscv64's `timebase-frequency`), **not** sufficient for node-scoped lookups + (a specific peripheral's own `reg` address, e.g. UART or the mailbox registers) once more + than one node could plausibly define a same-named property. `fdt.h`'s own header comment + already flagged this as a known future need ("item 0.6 will need node-scoped `reg` + lookups... may extend this") — this is that extension, now with a real consumer. +5. **`pci_init()` DTB path**: a devicetree-based alternative for RP1 discovery, since + `boot_info->acpi_table` will be `NULL` on this path and RP1 is PCIe-attached, not directly + memory-mapped. +6. **`config.txt` contents, decided from research**: `kernel=kernel_2712.img` (or `kernel8.img` + with `os_check=0` if the Pi-5-specific name isn't used), `arm_64bit=1`, pointing at + `bcm2712-rpi-5-b.dtb`. + +**Hardware-dependent, after 2026-09-17 (not started until then):** +7. Build the boot media (SD card: `config.txt`, `bcm2712-rpi-5-b.dtb`, kernel image). +8. Connect HDMI + keyboard (observation decision above). +9. Boot; confirm `ok>`/`zuse)ok>` reached. +10. Mint a Zuse identity on real media, confirm re-attach — the `v2.4.0` gate's own + requirement, same shape as amd64's. +11. Update this section with results before moving to riscv64's own hardware-dependent steps. ## V. riscv64 — Milk-V Mars