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.