From bffd87615d65f3bde36ed2c0fa6235affbe6c4aa Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 4 Sep 2026 12:55:28 -0400 Subject: [PATCH] FABRIC-3.md: riscv64 (Milk-V Mars) planning decided + punch list Resolved SS V.1's flagged gap: standard RISC-V SBI boot protocol, confirmed via OpenSBI's own docs -- a0=hart ID, a1=DTB pointer, S-mode entry, universal across FW_DYNAMIC firmware regardless of vendor, not chain-specific guesswork. Decided: observation is HDMI-only, same reasoning and constraint as the Pi 5 (no bridge hardware for this board's own first bring-up either). Traced boot_info->acpi_table's real riscv64 consumers the same way as aarch64: pci_init() again (Mars's M.2 slot is PCIe-attached, same shape of gap as the Pi 5's RP1); timer.c is already fully DTB-driven, no work needed there. One real, already-flagged risk found while tracing this: PLIC_BASE is a QEMU-virt-specific constant, not DTB-discovered -- arch/riscv64/ plic.c's own doc comment already warned about this; it becomes concrete now that real hardware is actually in scope. Real punch-list item, not hypothetical. 6-item no-hardware-needed punch list (entry stub, DTB->BootInfo constructor, DTB-discovered PLIC base, unresearched JH7110 framebuffer flagged honestly rather than assumed, shared pci_init() DTB path with the Pi 5, image-packaging tooling) plus 5 items deferred to 2026-09-17. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var --- FABRIC-3.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index c25cd0b..d8c95e6 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -377,27 +377,79 @@ aarch64 (§IV.1), now confirmed for riscv64 too. image — same tooling should apply to the Mars, unconfirmed until tried. - **Not yet found**: what registers carry the DTB pointer/hart ID at the actual kernel entry point under this specific chain (the source consulted covered the image-packaging tooling, - not the OpenSBI→kernel handoff register convention) — riscv64's standard Linux boot - convention (`a0`=hart ID, `a1`=DTB pointer, S-mode entry) is the reasonable default - assumption, matching what U-Boot/OpenSBI conventionally hand off, but not yet confirmed - against this chain specifically. + not the OpenSBI→kernel handoff register convention). **Resolved 2026-09-04**: standard + RISC-V SBI boot protocol, confirmed via OpenSBI's own docs — `a0`=hart ID, `a1`=DTB pointer, + S-mode entry. Not chain-specific guesswork; this is the universal convention OpenSBI's + `FW_DYNAMIC` firmware type uses regardless of vendor, so it applies to this chain directly. **What this means for the codebase** — same shape of fork as aarch64 (§IV.1): a non-UEFI entry path, a DTB-driven `BootInfo` equivalent (the existing `starkernel/hal/fdt.c` reader -extends here too, same as for the Pi 5), no ACPI. **Not yet scoped into a punch list.** +extends here too, same as for the Pi 5), no ACPI. + +**Decided in conversation, 2026-09-04: observation is HDMI-only**, same reasoning and same +constraint as the Pi 5 (§IV) — no bridge hardware available for this board's own first +bring-up either; the Mars has its own HDMI 2.0 output (§VI). ### V.2 — Peripheral RNG and Zkr: still genuinely open - Zkr/RNDR instruction availability on the Mars's actual CPU (riscv64 Scalar Crypto extension support varies by implementation) — not yet confirmed; the VisionFive 2 bare-metal research above didn't surface this either, would need its own targeted look (or a real-hardware - probe of `misa`/the Zkr extension discovery mechanism). -- Same observation-method question as the other two boards. + probe of `misa`/the Zkr extension discovery mechanism). Deliberately **not a blocker for + first boot**, same reasoning as §IV.2's aarch64 RNG gap — `rng_get_bytes()` already + WARNs rather than hard-fails with no backend. - **Whether the Mars needs the same pinned-GPIO-VM treatment as the Pi 5** — explicitly **not decided either way**, per direct instruction ("same for Milk-V (? not sure here)"). See `FABRIC-4.md` §2. The Mars does have its own 40-pin GPIO header (§VI), so the open question is the VM architecture around it, not whether the hardware exists. +### V.3 — Punch list: design/code work, no hardware needed (before 2026-09-17) + +Traced against real code before writing this, same discipline as §IV.3: `pci_init()` +(`kernel_main.c:589`, unconditional) is the one real `acpi_table` consumer relevant here too +— the Mars's M.2 E-Key slot (§VI) is PCIe-attached, same shape of gap as the Pi 5's RP1. +`riscv64/timer.c` is **already** fully DTB-driven (both `timebase-frequency` and this +session's own hypervisor-detection check) — no further work needed there; it was built DTB- +first from the start, unlike aarch64's timer which needed a new ACPI-based check today. + +**One real, already-flagged risk found while tracing this**: `arch/riscv64/apic.c`'s own doc +comment says the PLIC base address is "a constant, not discovered from `boot_info->dtb`" — +and `arch/riscv64/plic.c`'s own doc comment (predating this document) already warned +`PLIC_BASE`/`PLIC_CONTEXT_S` are "QEMU-virt-specific... not assumed stable across" other +configurations. That warning becomes concrete now: the JH7110's real PLIC address on the Mars +is not confirmed to match QEMU-virt's, and the interrupt controller will not work correctly if +it doesn't. This is a real punch-list item, not a hypothetical. + +1. **Entry stub**: new native riscv64 entry point at `0x40000000` (§V.1), receiving `a0`=hart + ID, `a1`=DTB pointer directly (now-confirmed SBI convention) — no UEFI, no PE loader. +2. **DTB → `BootInfo` constructor**: same shape as aarch64's (§IV.3 item 2) — `dtb`=real + pointer, `acpi_table`=`NULL`, memory map from DTB `/memory`+`/reserved-memory`, `args` from + `/chosen`/`bootargs`. +3. **PLIC base address: make it DTB-discovered**, not the current QEMU-virt-specific + constant — the one concrete, already-flagged risk above. Uses the same `fdt.c` node-scoped + lookup extension §IV.3 already scopes for the Pi 5's UART/mailbox addresses — one extension, + two consumers. +4. **Framebuffer for HDMI output**: JH7110's display path is genuinely unresearched this + pass — unlike the Pi 5's mailbox interface (well-documented, reused across many Pi bare- + metal projects), no equivalent research done yet for JH7110's own display controller. + Flagged here rather than assumed simple. +5. **`pci_init()` DTB path**: shares the same new code §IV.3 item 5 scopes for the Pi 5's RP1 + — one implementation, two consumers (M.2 here, RP1 there), assuming the underlying DTB PCI + binding shape is similar enough (ECAM-based, most likely, but not yet confirmed for JH7110 + specifically). +6. **Boot image packaging**: `vf2-imager`/`mkimage`-based FIT image (§V.1) — confirm this + tooling's actual invocation once building the first real image, not just cited from + VisionFive 2 research. + +**Hardware-dependent, after 2026-09-17:** +7. Build and flash the boot image to QSPI flash (or attempt UART XMODEM recovery boot if QSPI + flashing isn't set up yet — both are real supported paths per §V.1). +8. Connect HDMI + keyboard. +9. Boot; confirm `ok>`/`zuse)ok>` reached. +10. Mint a Zuse identity on real media, confirm re-attach — the `v2.5.0` gate's own + requirement. +11. Update this section with results. + --- ## VI. Hardware identification reference