From 5eeb993ca20b0ccb6d1c811ceb132f94ae7ae79a Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 4 Sep 2026 12:43:15 -0400 Subject: [PATCH] FABRIC-3.md: riscv64 boot chain resolved, BeagleBone Black noted, header bug fixed Milk-V Mars boot chain resolved via VisionFive 2 research: the Mars is a documented mainline U-Boot target using the exact same binaries as the VisionFive 2 (same StarFive JH7110 SoC) -- U-Boot + OpenSBI + devicetree, not UEFI, same fork already decided for aarch64. Entry point 0x40000000, mhartid CSR for core ID, UART at 0x10000000/115200 -- DTB pointer/hart-ID register convention at actual kernel entry not yet confirmed for this specific chain. Fixes a real bug from the earlier aarch64 edit: the "## V. riscv64 -- Milk-V Mars" section header had been accidentally dropped, leaving a stale duplicate "Already true"/"Genuinely open" block sitting where the real section should have started. Removed the duplicate, restored the header, folded today's research into the section properly. BeagleBone Black added to SS VI's hardware-identification reference per direct instruction -- recorded only, no work scoped around it: it's a 32-bit ARM (TI AM335x, Cortex-A8) SoC, a genuinely different, fourth architecture this kernel has no support for, not another board under an existing one. FABRIC-4.md SS2: captured the pinned-GPIO-VM idea raised in conversation (Pi 5 needs one, Milk-V Mars explicitly undecided) as a theory-stage note, cross-referenced from SSIV/SSV's own open-questions lists. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var --- FABRIC-3.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++------ FABRIC-4.md | 31 +++++++++++++++++++++ 2 files changed, 102 insertions(+), 8 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index 36d071d..5054765 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -212,6 +212,9 @@ is **not yet built** — today's `rng_get_bytes()` (`src/starkernel/rng/rng.c`) **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. +- **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). ### IV.1 — Boot-chain decision: UEFI vs. native, researched 2026-09-04 @@ -277,20 +280,62 @@ direct hardware probing once the board is in hand (scan the known BCM2711 RNG200 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). +## 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. +### V.1 — Boot chain: resolved, researched 2026-09-04 + +**Resolved, not left open.** The Mars is a documented mainline U-Boot board target in its own +right ([U-Boot docs — Milk-V Mars](https://docs.u-boot.org/en/latest/board/starfive/milk-v_mars.html)), +and it uses **the exact same U-Boot binaries as the StarFive VisionFive 2** — same SoC +(StarFive JH7110), board identity detected at SPL time, devicetree patched accordingly, no +separate Mars-specific firmware. This directly answers §V's own previously-open question: +**U-Boot + OpenSBI + devicetree, not UEFI** — same fork this kernel already decided for +aarch64 (§IV.1), now confirmed for riscv64 too. + +**Boot chain, concretely:** +1. BootROM (ZSBL), StarFive's on-chip loader at `0x2A000000`, selects boot media by GPIO pins. +2. U-Boot SPL (FSBL) — initializes DRAM, configures PLLs. +3. OpenSBI (`fw_dynamic.bin`) — M-mode runtime services. +4. U-Boot main, S-mode, depends on OpenSBI. +5. Boot media: QSPI flash (recommended) or UART XMODEM (recovery). SD/eMMC boot modes are + deprecated in current U-Boot. + +**Entry protocol, from real VisionFive 2 bare-metal work (same SoC, directly applicable per +§VI's own cross-reference):** +- Entry point `0x40000000`. +- Core identification via the `mhartid` CSR — the SiFive S7 monitor core is hart 0, the four + U74 application cores are harts 1–4 (matches the QEMU riscv64 target's own hart numbering + convention already assumed elsewhere in this codebase — worth double-checking, not + assuming, once real hardware is in hand). +- UART at `0x10000000`, 115200 baud, already initialized by firmware before handoff. +- Custom bare-metal images package via `vf2-imager` (invokes U-Boot's `mkimage`) into a FIT + 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. + +**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.** + +### 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. + 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. +- **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. --- @@ -356,3 +401,21 @@ the actual unit in hand is flagged as such rather than assumed. - Sources: [milkv.io — Mars overview](https://milkv.io/docs/mars/overview), [milkv.io — Mars product page](https://milkv.io/mars), [TinyComputers.io — Mars review](https://tinycomputers.io/posts/milk-v-mars-review.html). + +### Noted for later, not yet in scope — BeagleBone Black + +Added to this reference per direct instruction 2026-09-04, **recorded only — no work scoped +around it yet.** Genuinely different from the three targets above: the BeagleBone Black's +SoC is a **32-bit ARM** part, not aarch64 — a fourth architecture this kernel has no support +for at all today (amd64/aarch64/riscv64 only), not another board under an existing one. + +- **SoC: TI Sitara AM335x.** +- **CPU**: single-core ARM Cortex-A8, 1 GHz, armv7-a (32-bit) — up to ~2000 MIPS. +- **RAM**: 512 MB DDR3L. Storage: 4 GB eMMC (default boot source) + microSD (secondary/ + overridable to primary). +- **Other on-die units**: PowerVR SGX530 3D GPU; 2× PRU (Programmable Realtime Unit) 32-bit + 200 MHz microcontrollers — real-time I/O coprocessors, no equivalent on any of the three + boards above; crypto accelerators. +- **Boot modes**: eMMC, microSD, serial, USB. +- Sources: [element14 — BBB product page](https://www.element14.com/community/docs/DOC-84108/l/beaglebone-black-development-board-with-1ghz-am335x-arm%C3%A3%C3%A2-cortex-a8-processor), + [TI.com — BEAGL-BONE-BLACK](https://www.ti.com/tool/BEAGL-BONE-BLACK). diff --git a/FABRIC-4.md b/FABRIC-4.md index 0e65eae..a820d5e 100644 --- a/FABRIC-4.md +++ b/FABRIC-4.md @@ -73,3 +73,34 @@ level up the stack. build the one wheel concretely first, generalize only if/when a second one is actually needed (this project's own standing convention — three similar lines beat a premature abstraction). + +## 2. A pinned GPIO VM per real-hardware board (2026-09-04) + +Raised in conversation with Captain Bob during `FABRIC-3.md` §IV/§V's bare-metal-boot +planning — theory stage, no code, no scope, deliberately not punch-listed yet. + +**The idea, as stated:** the Raspberry Pi 5 will need a special pinned VM dedicated to GPIO — +presumably following the same Tripod precedent Hermes/Artemis already established (a +permanently-pinned, born-at-boot VM with a fixed role, per `FABRIC-2.md` §H.1's "pinned +sessions never leave" model). Whether the Milk-V Mars needs the same treatment is explicitly +**not yet decided** — Captain Bob's own framing: "same for Milk-V (? not sure here)." Worth +noting the Mars does have its own 40-pin GPIO header (§VI), so the question isn't "does it +have GPIO" but whether it needs its own *dedicated pinned VM* for it the same way the Pi 5 +does, or whether GPIO access there fits some other shape. + +**Why a dedicated VM, not just a C driver, presumably (not yet confirmed as the actual +reasoning — inferred from the Tripod precedent, not stated outright):** GPIO is shared, +stateful hardware that multiple capsules/patrons might want to touch — the same category of +problem Hermes (messaging) and Artemis (block storage) already solve by being a dedicated, +addressable VM other patrons talk to, rather than a bare C primitive anyone can call directly. + +**Explicitly not decided yet:** +- Whether Milk-V Mars needs the same pinned-VM treatment, or something else. +- What this VM's own vocabulary/interface would look like (a `GPIO-READ`/`GPIO-WRITE`-shaped + word set? something richer, given the Pi 5's GPIO header also muxes UART/SPI per §IV.1?). +- Whether this is one pinned VM per board doing double duty (GPIO + whatever else that board's + bring-up needs) or GPIO specifically warrants its own separate VM distinct from, say, a + future UART-handling VM. +- How this interacts with §IV.1's own still-open native-boot-flow work — a GPIO VM needs GPIO + register addresses from the DTB the same way the rest of that bring-up does, so this idea + isn't independent of that work, just downstream of it.