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, 0 insertions, 381 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
deleted file mode 100644
index 0e1b58e..0000000
--- a/debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md
+++ /dev/null
@@ -1,381 +0,0 @@
-# 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.