# 08 — green-eye roadmap

> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
> This is the **near-term, committed** roadmap (rungs R0–R7 below). The
> **long-term program** — adversarial firmware navigation, adjacent
> microcontrollers, a non-QEMU custom simulator, a Verilog soft-processor
> environment and the agentic platform — lives in
> [`../GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md).
> Items here are **not** v0.1. Do not start them ad hoc; each has a gate.

## R0. Product principles

* green-eye stays a **development tool**: no shipped dependencies, no guest
  presence, no kernel-module coupling.
* Fidelity improvements must be *measurable* (metrics table in 06) and must
  not slow the fast path (demo + probe) below usefulness.
* Every new backend must satisfy the same `Session` contract so scripts,
  probes, plugins and recordings survive.

## R1. Platform device model (raise L3)

**Why:** a bare `qemu virt` cannot boot the real fwimage; the probe shows the
first unmapped access and stops.

**Scope:** model the minimum GSP environment:
falcon windows (FALCON/CSB/TRANSCOM registers), WPR2/FWSEC state registers
with read-back semantics, PTIMER, PMU/SEC2 mailbox stubs, FB DMA/IOMMU
address translation for the firmware's DMA descriptors, and interrupt
routing. QEMU `qemu-system-riscv64` with a custom device (`-device`) is the
preferred vehicle; TCG plugins provide the observation points.

**Gate:** R1 starts only when a portability task (P2/P3) or an accuracy
measurement (P1.6) requires booting real firmware in-simulator. Until then,
use the probe + rehosted uproc paths.

**Exit criteria:** `greeneye probe <fwimage>` reaches a stable address and
reports "waiting for host message" rather than a fault; the first host↔GSP
RPC records are captured in a session; M3 ordering can be measured against
the physical backend.

## R2. Custom simulator (explicitly requested; not first version)

**Why:** QEMU is an excellent execution engine but a poor *workflow* engine
for this project: no in-process API, RSP serialisation for every access,
limited snapshotting, and a device model designed for whole boards rather
than firmware servers. A custom simulator can be deterministic, replayable
and scriptable at native speed.

**Shape (to build later, not now):**
* an RV64IMAC interpreter/JIT with a **pluggable memory map** (RAM, MMIO
  hooks, DMA windows) and a **deterministic scheduler** (no realtime claim);
* native `Session` integration — replace the RSP transport with a
  `Backend` interface, keep hooks/watchpoints/memory/recording identical;
* first-class **snapshot/restore** of full machine state (time-travel
  debugging, branch-flip experiments);
* an **event bus** feeding the existing `events.jsonl` schema;
* a **stub DSL** for device registers (read/write scripts with state), so a
  new GPU generation is configuration, matching the project's portability
  direction.

**Candidates to evaluate at that time:** extending QEMU TCG with a thin
in-process backdoor, `libriscv`, `rv8`, or a from-scratch interpreter.
Realtime is explicitly *not* a requirement; determinism and introspection are.

**Gate:** R1 must have stabilised the device semantics (otherwise the custom
simulator inherits an unvalidated model). Estimated multi-week work; schedule
only after the guest-bridge work (PLAN B) no longer depends on it.

## R3. MCP server plugin

**Why:** expose green-eye sessions to AI harnesses and other agents under the
plugin model the user requested.

**Shape:** a plugin (`plugins/mcp_server.py` when built) that wraps the
session/analysis API as MCP tools: `list_sessions`, `open_session`,
`symbols_resolve`, `set_breakpoint`, `run`, `memory_read`, `memory_hexdump`,
`snapshot`, `compare_sessions`, `export_hits`. Transport local stdio first;
no network exposure by default. The plugin depends on an MCP library only at
plugin load time; the core stays stdlib-only.

**Gate:** v0.1 must be stable (acceptance list in 00) and the session format
frozen. Explicitly deferred by the owner; do not add MCP code before then.

## R4. Full-memory trace (TCG plugin integration)

The optional `qemu/greeneye_trace.c` plugin records instruction execution and
memory accesses. Roadmap: build it against the vendored QEMU headers, stream
its JSONL into the session format as `exec`/`access` events, and teach
`analyze` to render coverage/heatmaps and written-page timelines. This is the
"complete map" upgrade from stop-based observation to full access tracing.

**Gate:** available once the QEMU plugin headers are vendored (or the build
environment provides them). Does not block v0.1 — watchpoint recording plus
step traces already cover the common cases.

## R5. Fuzzing and mutation harness

Use AFL++ QEMU mode (or a custom mutator) against the rehosted firmware's
RPC input surface, with green-eye recording crash/trap paths and symbol
annotation. Requires R1/R2 for stable input plumbing. Output: a corpus of
malformed controls and the firmware's error paths, feeding the emulation's
fail-closed rules (project security hygiene).

## R6. Multi-version orchestration

Scripts that, given a set of firmware images and device profiles, run the
probe + rehost + compare pipeline for the whole matrix and emit the M1–M6
tables. This automates `07-PORTABILITY-PLAYBOOKS` P1–P3.

## R7. Ghidra two-way console

A Ghidra script/plugin that talks to a live green-eye session (via the CLI or
a local socket) to toggle breakpoints/watchpoints from the decompiler and to
highlight hit addresses. Until then, the hit-TSV + `MarkGreenEyeHits.java`
flow is the supported path.

## Not on the green-eye roadmap

* Graphics/display emulation, Windows guest internals, multi-tenant policy —
  these belong to the main project roadmap, not to this analysis tool.
* Replacing Ghidra: green-eye is the dynamic complement, never a decompiler.