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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var

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