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

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