# 00 — green-eye overview

> **# TOOL IN DEVELOPMENT - NOT READY YET!**
> Experimental tooling for simulating and inspecting the GSP firmware's
> runtime memory, for `gsp-rm-vfio` accuracy measurements and GSP/uproc
> reverse engineering. Interfaces and file formats may change without notice.
> It is development-only: never shipped, never a dependency of the emulation,
> never present in a guest.

## What problem it solves

Open-IOV emulates the GSP interface and (in the physical backend) boots the
real GSP firmware. Both efforts need the same missing capability: to *watch
the firmware do things* — which handler runs, what it reads and writes, what
it returns, how its state machine evolves — without a physical GPU, without
WPR2/hazard exposure, and repeatably.

green-eye runs uproc/GSP firmware in `qemu-system-riscv64` and gives the
developer Frida-like instrumentation over its memory and execution:

* breakpoints and enter/leave **hooks** (RV64 ABI aware),
* **watchpoints** on firmware variables,
* **memory** read/write/hexdump/search/scan,
* **structure decoding** from schemas,
* **snapshot + diff** of memory regions,
* **sessions**: a recorded, replayable dump of runtime memory activity,
* **post-run analysis** with symbol annotation,
* **plugins** for new tools, harnesses and virtualization updates,
* a **Ghidra bridge** joining static addresses to runtime hits,
* A/B tooling for **bare-metal vs vfio-mdev** result comparison.

It is deliberately not a GDB wrapper: a pure-Python RSP client makes the
whole stack scriptable, and QEMU is just the first execution backend.

## Status (v0.1, 2026-10-02)

| Capability | State |
|---|---|
| RV64 QEMU boot + gdbstub transport (no GDB) | working, live-verified |
| Hooks / breakpoints / watchpoints / step / continue | working, live-verified |
| Memory tools + struct decode + snapshot diff | working, live-verified |
| Session recording + `analyze` report | working, live-verified |
| Declarative probe specs | working, live-verified |
| Plugin loader + example plugin | working |
| Test suite | 22 tests green (live QEMU smoke included) |
| Ghidra bridge | scripts + docs |
| Real GSP `.fwimage` probe (first-fault report) | working (honest: it does not boot without a TU104 model — see 06) |
| TCG full-memory tracing plugin | source + optional build |
| MCP server / custom simulator / full device model | roadmap only (08) |

## Quick start

```bash
cd open-iov/debug/risc-v-gsp-rm-vm
make demo                 # build the bundled RV64 uproc demo
./greeneye.sh demo        # canned instrumentation pass, records a session
./greeneye.sh info        # environment check
./greeneye.sh probe       # run the real GSP fwimage and report first divergence
```

Interactively:

```bash
./greeneye.sh demo --no-build --duration 0   # launches; prints the gdbstub port
./greeneye.sh attach --port <port> --kernel firmware/uproc_demo/build/uproc_demo.elf
```

## Document map

| Doc | Read it for |
|---|---|
| [01-DESIGN](01-DESIGN.md) | how the pieces fit, transport, data model, limits |
| [02-USAGE](02-USAGE.md) | CLI and REPL recipes |
| [03-SCRIPTING](03-SCRIPTING.md) | writing programs against the API |
| [04-PLUGINS](04-PLUGINS.md) | extending green-eye |
| [05-GHIDRA-BRIDGE](05-GHIDRA-BRIDGE.md) | static/dynamic address join |
| [06-ACCURACY](06-ACCURACY.md) | what the simulation does and does not prove |
| [07-PORTABILITY-PLAYBOOKS](07-PORTABILITY-PLAYBOOKS.md) | new GSP / device / architecture |
| [08-ROADMAP](08-ROADMAP.md) | MCP, custom simulator, device model |
| [09-GSP-FIRMWARE-NOTES](09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts used here |
| [10-RELATED-WORK](10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison |

## Where this fits in the Open-IOV workflow

green-eye is a **development and research** tool, alongside the Ghidra corpus
and the guest diagnostics. It does not replace either:

* **Ghidra** answers *what is the code*; green-eye answers *what did it do*.
* **Guest diagnostics** (`tools/guest-diag`) answer *what did the guest
  driver do*; green-eye answers *what did the firmware server do*.
* **The physical backend** (PLAN B) answers *what does real silicon do*;
  green-eye provides a safe place to repeat, mutate and single-step the same
  firmware when the hardware path is hazardous or unavailable.

The intended accuracy loop is: run the same workload against the real
GSP-RM (hardware or mdev), record its RPC/state behaviour, then run the
firmware in green-eye, record the same events, and compare with `compare`
(see 06 and 07).