rename (cosmetic): green-eye -> risc-v-gsp-rm-debugger in user-facing names, docs, CLI, launcher and CI workflow; internal greeneye package/module identifiers unchanged (includes in-flight greeneye module edits present in the tree)

1 files changed, 381 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md b/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md
new file mode 100644
index 0000000..26f586f
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md
@@ -0,0 +1,381 @@
+# RISC-V GSP-RM DEBUGGER ROADMAP — long-term program
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!**
+> This is the long-term plan for risc-v-gsp-rm-debugger, 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.
+
+risc-v-gsp-rm-debugger 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 risc-v-gsp-rm-debugger 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
+```
++-------------------- risc-v-gsp-rm-debugger 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; risc-v-gsp-rm-debugger
+   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 risc-v-gsp-rm-debugger 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 risc-v-gsp-rm-debugger (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 risc-v-gsp-rm-debugger (JTAG/DPI/a bridge) so the
+  same Python hooks, sessions and comparisons apply.
+
+### H6.2 Integration with risc-v-gsp-rm-debugger
+* 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.