# 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.