1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# 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 |
| [11-GSP-RM-SERVICE-DEVELOPER-GUIDE](11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md) | writing/injecting/debugging RM services |
| [12-INJECTION-SDK](12-INJECTION-SDK.md) | injection blob/ABI specification |
| [13-GHIDRA-CONTROL](13-GHIDRA-CONTROL.md) | driving green-eye from Ghidra |
| [14-ADVERSARIAL-INTEROP-GUIDE](14-ADVERSARIAL-INTEROP-GUIDE.md) | adversarial firmware navigation |
| [15-AGENTIC-GSP-IDE](15-AGENTIC-GSP-IDE.md) | agentic workflows and runbooks |
| [16-CUSTOM-SIMULATOR](16-CUSTOM-SIMULATOR.md) | non-QEMU simulator design (later) |
| [GREEN-EYE-ROADMAP](../GREEN-EYE-ROADMAP.md) | long-term program H1–H7 |
## 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).
|
