diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md b/debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md new file mode 100644 index 0000000..0e1b58e --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md @@ -0,0 +1,381 @@ +# GREEN-EYE ROADMAP — long-term program + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> This is the long-term plan for green-eye, the runtime analysis, injection and +> measurement environment for the NVIDIA GPU System Processor (GSP) and its +> adjacent microcontrollers. Near-term, committed work lives in +> [`docs/08-ROADMAP.md`](docs/08-ROADMAP.md); this document is the program. + +## 0. Purpose + +Open-IOV's hardest long-term problem is not writing the emulation once — it is +**surviving adversarial firmware change**. NVIDIA ships new GSP images, new +device pairings and new architectures on independent schedules, and the +firmware is deliberately opaque (stripped, signed, hardware-coupled, with +non-recoverable boot states). To keep `open-iov-vfio` accurate across that +churn, the project needs a toolchain that can: + +1. **Run** firmware off-hardware, safely and repeatably. +2. **Observe** it completely — control flow, memory, services, state machines. +3. **Change** it — inject our own services/engines and mutate inputs to learn + boundaries. +4. **Compare** — hardware vs VFIO vs simulation, old vs new firmware, with a + metric contract instead of anecdotes. +5. **Reimplement** — turn observed behaviour into reviewed code in + `open-iov-vfio` with evidence attached. + +green-eye is the vehicle for that program. It is explicitly a **development +environment**, never a shipped component. + +## 1. Starting point (H0, done) + +v0.1 (2026-10-02) provides: GDB-free QEMU RISC-V transport; hooks, +breakpoints, watchpoints; memory/struct/snapshot tooling; recorded sessions +and symbol-annotated analysis; declarative probes; plugins; a Ghidra symbol +and hit bridge; a Ghidra control bridge; a TCG full-trace plugin; a +position-independent service SDK and `greeneye inject`; and the Frida-like +`Session.call` / `run_until` primitives. Fidelity is L0/L1 (execution and +memory); the device environment (L3) is absent. + +## 2. How this roadmap is organised + +Five workstreams run through every horizon: + +* **F — Fidelity**: how much of the real GSP environment the simulator + provides (device model, boot chain, timing). +* **I — Injection**: what code we can add to the running system and how. +* **A — Adversarial navigation**: finding and understanding *unexpected* + firmware behaviour and mapping it to emulation changes. +* **C — Control & tooling**: debugging, Ghidra/agent integration, SDK, + formats, usability. +* **V — Validation**: metrics, benchmarks, golden sessions, gates that stop a + claim from landing without evidence. + +Horizons are numbered H1..H7 with explicit **entry gates** (what must be true +before starting) and **exit criteria** (what must be demonstrated). + +--- + +## H1 — Injection and control (now → weeks) + +**Goal:** make "write a service / change the firmware / prove it" a +first-class loop on the demo uproc and on re-hosted uproc code. + +### H1.1 GSP RM firmware service developer guide (deliverable today) +A written guide (docs/11) covering: RM service anatomy, service entry and +message loop, RM-core calls available to a service, allocation/control +surfaces, inter-service messaging, versioning, and the build/inject/debug +loop. On the demo this maps to the handler-table ABI; on real GSP-RM it maps +to the RM object/control model. + +### H1.2 Injection SDK v1 (deliverable today, demo-proven) +Specification (docs/12): blob format, PIC requirements, ABI, registration, +capability metadata, error model, observability hooks. Implemented in `sdk/` +and `greeneye/inject.py`, verified by direct call and firmware dispatch. + +### H1.3 GSP-RM service injection (needs H2 device model) +Once real GSP-RM runs in the simulator (H2), extend the SDK to: +* build against RM headers or against a green-eye shim for + public work; +* register a service with the simulated RM core instead of a demo handler + table; +* call RM-core entry points (allocation, control, mapping, scheduling) from + the injected code, intercepted by the simulator so calls are logged, + stubbed or forwarded; +* run injected services under the same recording/compare pipeline. +Entry gate: H2.2 (GSP-RM reaches its message loop in the simulator). +Exit: an injected service serves a control end-to-end and its session can be +diffed against hardware. + +### H1.4 Ghidra-driven execution (deliverable today, demo-proven) +`greeneye ghidra` + `GreenEyeControl.java` (docs/13): "run until here", set +breakpoints, read memory/registers, remote-call, export hits. Next +increments: +* watchpoints and structure reads from Ghidra; +* a decompiler-side hit heat-map fed by `greeneye_hits.tsv`; +* bidirectional navigation: clicking a hit opens the decompiled function. + +### H1.5 Debugger parity +Make the REPL/API cover the common GDB vocabulary for firmware work +(watchpoints, catchpoints for traps, thread/core selection, memory region +metadata) while keeping the scripted API as the primary surface. + +--- + +## H2 — Fidelity: platform device model (months) + +**Goal:** move from "executes and faults" to "boots the real GSP image to its +message loop" inside the simulator. + +### H2.1 First-touch register map (started) +The `probe` command already reports the first fault (TU104 570.144: load +access fault at firmware vaddr `0x4009014` reading `0x2000000000000A00`). +Systematically harvest first-touch addresses across versions/devices and +build the initial MMIO map from them. + +### H2.2 QEMU device model +Model, as a QEMU `-device` (or a small set): +* **falcon/SEC2 windows** (cpuctl, dmactl, fbif, imem/dmem, bootvec) with + read-back semantics adequate for boot polling; +* **CSB/TRANSCOM** mailbox windows used by the GSP application; +* **WPR2/FWSEC state** registers (so the image believes it was staged); +* **PTIMER** and basic interrupt routing; +* **DMA/IOMMU** address translation for the firmware's descriptors into + host/FB windows; +* **PMU stub** sufficient for the identity/clock provisioning the GSP app + reads early. +Entry gate: H0 + first-touch data. Exit: the image reaches `appMain` and +blocks on a host message rather than faulting. + +### H2.3 Boot-chain shims +FWSEC/booter/SEC2 are not reasonable to model fully; provide *documented +shims* that place the GSP image in the state the bootloader would have left +it (boot args in a0–a5, MPU/TCM layout, scratch state), so boot behaviour can +be studied without the security chain. Record shim assumptions in session +metadata. + +### H2.4 Multi-core and concurrency (approximate first) +GSP-RM is multi-task; adjacent controllers (SEC2/PMU) are separate cores. +Add deterministic scheduling knobs (instruction budget round-robin, timer +injection) so multi-task interleavings can be explored, replayed and +compared — without claiming real-time behaviour. + +--- + +## H3 — Non-QEMU custom simulator (months; explicitly later) + +**Why:** QEMU is an execution engine, not a workflow engine. It cannot give +us cheap snapshots, deterministic replay with time-travel, in-process +inspection, per-access callback ABI objects, or a device map expressed as +code + data we can version with the firmware profiles. A custom simulator can, +and can become the substrate for injection, fuzzing and adversarial work. + +### H3.1 Requirements +* RV64IMAC(+GC when needed) interpreter, fast enough for firmware bring-up + (target: ≥10–50 MIPS/core on one host thread; not realtime). +* Pluggable **memory map DSL**: regions (RAM/TCM/MMIO/DMA) with read/write + callbacks, access logging, and declarative register definitions. +* **Deterministic scheduler**: per-core instruction budgets, timers, event + queue; replay from an event log. +* **Snapshot/restore** of full machine state (registers, memory, device + state) for instant checkpointing and time-travel debugging. +* **Event bus** emitting the existing `events.jsonl` schema plus + `exec`/`access` events. +* **Backend ABI** identical to `Session`'s expectations, so all hooks, + watchpoints, scripts, probes, plugins, records and comparisons keep working. +* **Injection ABI**: load blobs, register services, intercept RM-core calls. +* **Python-first embedding** (C/C++ core with a Python control plane, or a + Rust core with PyO3), plus a CLI. + +### H3.2 Design sketch +``` ++-------------------- green-eye Python control plane --------------------+ +| Session API, hooks/watchpoints, recorder, plugins, Ghidra/agent bridge | ++---------------------------- Backend interface -------------------------+ + | QEMU-RSP backend (today) | native simulator backend + v v + qemu-system-riscv64 libgreenmachine (C/C++/Rust) + +-- cpu/ (interpreter, decoder) + +-- mem/ (map DSL, snapshots) + +-- dev/ (falcon, csb, pmu, dma) + +-- sched/ (cores, timers, events) + +-- trace/ (event bus, coverage) +``` +* The **map DSL** is versioned data (JSON/YAML) with per-device behaviour in + small plugin modules; new firmware/device profiles are additions, matching + the project's portability direction. +* **Snapshots** are copy-on-write memory pages + device state, giving cheap + branch exploration ("what if this reply differed?"). +* **Time-travel** is built from snapshot + deterministic event replay. + +### H3.3 Implementation plan +1. **M1**: RV64IMAC interpreter + RAM + UART; boots the demo uproc; green-eye + Session works against the native backend (parity with QEMU for the demo). +2. **M2**: memory map DSL + falcon/CSB/PTIMER devices; boots a re-hosted + uproc build; snapshots/restore. +3. **M3**: deterministic scheduler + event log/replay; multi-task tests. +4. **M4**: device-model parity with H2.2 and boot of the real GSP image under + shims. +5. **M5**: injection ABI + RM-core interception; fuzzing harness. +6. **M6**: performance and ergonomics hardening; backend selection in the + CLI (`--backend native`). + +### H3.4 Risks +Fidelity divergence from QEMU/hardware (mitigate: differential tests between +backends at H0 demos and H2 boot milestones); effort creep (gate behind H2 +success); maintenance of two backends (keep the Backend interface minimal). + +--- + +## H4 — Adversarial firmware navigation (continuous) + +**Goal:** when the firmware changes unpredictably — new handlers, opaque +state, deliberate anti-analysis, or shifted resources — navigate and +reimplement quickly. + +### H4.1 Semantic diffing +* Import each firmware's Ghidra corpus and green-eye symbol DB; diff RPC + dispatch tables, handler inventory, control sets, message layouts. +* Run the same stimulus harness against each version and use + `greeneye compare` for hit/watch/write deltas; automatically flag functions + whose call counts changed but whose static code is unchanged (behaviour + moved) vs changed code (new logic). +* Produce a "portability delta report" per version (feeds docs/07 playbooks). + +### H4.2 Capability inference +Observe what each service reads/writes (watchpoints, TCG trace) and infer +capabilities (which objects, ranges, controls it touches); compare with the +declared/emulated capability model; surface least-privilege and security +findings for `open-iov-vfio`. + +### H4.3 Mutation and fuzzing +Feed malformed construction/control traffic into re-hosted or simulated +firmware; capture error paths, asserts and panic loops with symbol +annotation; build a corpus that drives the emulation's fail-closed rules +(project security hygiene) and its error replies. + +### H4.4 Decoy / anti-analysis handling +Firmware may use timing checks, self-integrity checks, bogus code paths or +hardware-dependent branches. Techniques to build: deterministic replay to +separate data from noise; "two-run differential" with a single input bit +flipped; dead-code identification by coverage; trap-on-read of +anti-analysis registers with recorded responses; and a catalogue of observed +techniques in docs/09. + +### H4.5 Reimplementation workflow (accuracy loop) +The canonical loop for any behaviour: +1. Observe on hardware/VFIO (reference capture). +2. Observe in green-eye (simulator, replayable). +3. `compare` + metric table M1–M6 (docs/06-ACCURACY.md). +4. Implement in `open-iov-vfio` with the session directories attached as + evidence. +5. Re-run the same stimulus; the metric table must improve or stay equal. +This loop becomes a scripted harness ("consensus harness") so every change +produces comparable evidence. + +--- + +## H5 — Adjacent microcontrollers (months) + +**Goal:** treat the GSP as one node in a device-level system. + +* **Inventory**: PMU (power/voltage/clock provisioning), SEC2 and ACR/SOE + (security/boot), the booter, FWSEC/FRTS, and the DMA lines between them + (from firmware analysis and the RISC-V Story material; see + docs/09). +* **Models**: per-controller memory maps, mailbox protocols and boot state + machines as versioned data; SEC2/PMU stubs first (GSP needs them to pass + early init), full ACR/SOE later. +* **Cross-controller scenarios**: GSP↔PMU identity/clock provisioning, + GSP↔SEC2 mailbox, boot-order exercises (Init→ACR→RM for the + confidential-compute partition model). +* **Deliverable**: a device-level session that spans controllers, recorded + and comparable, so a firmware update's cross-controller interactions are + visible. + +Entry gate: H2.2 (GSP message loop). Exit: at least one cross-controller +exchange reproduced and compared with hardware evidence. + +--- + +## H6 — Verilog soft processor (far later) + +**Goal:** an FPGA/ASIC-simulation-grade soft implementation of the GSP core +environment that can run real GSP-RM images with cycle-accuracy options, for +deep timing/security/interoperability work and hardware validation of the +emulation. + +### H6.1 Scope +* RV64 core choice/build (existing open cores vs a minimal in-house core), + matching ISA/extensions used by the firmware; TCM, MPU/PMP, vectored + interrupts, timers. +* Device fabric: falcon-compatible windows, CSB/TRANSCOM, DMA engine to host + memory, WPR2/FWSEC state (with an explicit, documented security posture: + the soft model is a study environment, never a confidentiality boundary). +* Run modes: pure RTL simulation (Verilator) for determinism and coverage; + FPGA for speed; co-simulation with green-eye (JTAG/DPI/a bridge) so the + same Python hooks, sessions and comparisons apply. + +### H6.2 Integration with green-eye +* A `Backend` implementation talking to the RTL simulation clock/step and + memory API; breakpoints become simulation traps; watchpoints become + signal/page monitors. +* Sessions record cycle counts as a distinct event class (L2 timing becomes + measurable, with the accuracy caveats of docs/06 revisited). + +### H6.3 Gates +Requires: H2/H3 proven, a validated device map, and a funded reason to care +about cycle accuracy (e.g., a customer-facing timing claim). Explicitly +**not** on the critical path; do not start before the baseline goals in the +project roadmap are complete. + +--- + +## H7 — Agentic platform (continuous, gated) + +* **MCP plugin (R3)**: expose sessions as MCP tools (list/open sessions, + symbols, breakpoints, run/run_until, memory, snapshots, compare, + export_hits). Local stdio; no network by default. +* **AI harness integration**: deterministic run harnesses that an agent can + drive; sessions as the shared evidence format; guarded write actions with + an explicit capability manifest. +* **Autonomous analysis loops**: hypothesise → instrument → run → compare → + report, with human-review gates for anything that changes the product. +* **Safety**: no unattended physical-GPU cycles; no guest modifications; the + agent runs against the simulator by default. + +--- + +## Cross-cutting workstreams + +### V1 — Metrics and golden data +Keep the M1–M6 contract (docs/06) authoritative; maintain golden sessions for +the demo and re-hosted workloads; CI runs the tool tests + golden comparisons. + +### V2 — Formats and versioning +`greeneye-session/1` evolves additively with a version bump and migration +notes; symbol DBs carry provenance; injection blobs carry an ABI version and +capability metadata. + +### V3 — SDK/ABI evolution +Injection ABI v1 (demo) → v2 (RM-core interception). Breaking changes are +gated by a compatibility shim and a documented migration. + +### V4 — Security +Treat the simulator as a study environment: no confidentiality claims; keep +fuzzing and mutation behind explicit harnesses; never ship simulation shims +in the product; never place tooling in a guest. + +### V5 — Performance +Simulator performance target (H3.1); TCG trace filtering; snapshot +compression; session size budgets (region-scoped dumps). + +### V6 — Documentation and developer experience +Every horizon ships docs with copy-paste workflows, an acceptance script, and +a flag-removal (TOOL IN DEVELOPMENT) criterion; the Ghidra/agent guides are +kept current as first-class deliverables. + +## Sequencing summary + +| Horizon | Entry gate | Primary deliverable | +|---|---|---| +| H1 | H0 (done) | injection SDK + RM service guide + Ghidra control | +| H2 | H1 | QEMU device model; real GSP image reaches message loop | +| H3 | H2.2 | native simulator with snapshots/replay and injection | +| H4 | H1+H2 | adversarial diffing/capability/fuzzing harness | +| H5 | H2.2 | adjacent-controller models and cross-controller sessions | +| H6 | H3 validation | Verilog soft-core environment (far later) | +| H7 | H1 stable | MCP plugin and agentic harnesses | + +## Success criteria (program level) + +1. A new GSP version can be triaged (inventory diff + behaviour diff + + metric table) in **hours**, with recorded evidence. +2. Every new emulation behaviour lands with an A/B session pair and the M1–M6 + table. +3. Injected services prototype RM engine ideas in the simulator before any + product code is written. +4. The custom simulator reproduces the H2 boot and H4 workloads + deterministically, with snapshots and replay. +5. No claim of accuracy, portability or security depends on a single run or + on unstated fidelity assumptions. |