# green-eye — GSP runtime analysis in a RISC-V QEMU VM

> **# 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. It is a development-only, out-of-tree tool: never a
> dependency of the shipped driver and never present in a guest.

green-eye boots GSP/uproc firmware in `qemu-system-riscv64`, attaches over
QEMU's gdbstub with a GDB-free Python client, and exposes Frida-like
instrumentation: hooks, breakpoints, watchpoints, memory dumping, structure
decoding, snapshot diffing, session recording, plugins and a Ghidra bridge.

Start with [`docs/00-OVERVIEW.md`](docs/00-OVERVIEW.md).

## Quick start

```bash
cd open-iov/debug/risc-v-gsp-rm-vm

make demo            # build the bundled RV64 uproc demo (clang + lld)
./greeneye.sh demo   # boot it, hook handlers, watch counters, record + analyze
./greeneye.sh info   # environment / tooling check
```

Interactively instrument a session:

```bash
./greeneye.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf
greeneye> bp rpc_sum
greeneye> watch gsp_ctrl+0x10 8 w
greeneye> x 0x80000840 64
greeneye> c 2
```

Or launch a target separately and attach to it by port:

```bash
./greeneye.sh launch --kernel <elf>      # prints the gdbstub port, keeps QEMU alive
./greeneye.sh attach --port <port> --kernel <elf>
```

Requirements: QEMU (`qemu-system-misc` on Ubuntu gives
`qemu-system-riscv64`), Python 3.10+, clang + lld for the demo firmware.
Everything else is Python stdlib.

## Layout

```
greeneye/           Python package: RSP client, session, memory, symbols,
                    structures, recording, analysis, probes, plugins, Ghidra bridge
firmware/uproc_demo/RV64 bare-metal demo "uproc" (mailbox RPC, state machine, trap)
qemu/               launch helper + optional TCG plugin for full memory tracing
ghidra/             Ghidra scripts (export symbols, annotate hit addresses)
plugins/            example plugin + authoring guide
examples/           Python instrumentation scripts and declarative probe specs
tests/              unit tests + QEMU integration smoke test
docs/               full documentation set (design, scripting, plugins, accuracy,
                    portability playbooks, roadmap, GSP firmware notes)
dumps/              recorded sessions (gitignored)
```

## Documentation map

| Doc | Content |
|---|---|
| [00-OVERVIEW](docs/00-OVERVIEW.md) | purpose, status, quickstart |
| [01-DESIGN](docs/01-DESIGN.md) | architecture and data model |
| [02-USAGE](docs/02-USAGE.md) | CLI and REPL recipes |
| [03-SCRIPTING](docs/03-SCRIPTING.md) | Python API + probe specs |
| [04-PLUGINS](docs/04-PLUGINS.md) | writing green-eye plugins |
| [05-GHIDRA-BRIDGE](docs/05-GHIDRA-BRIDGE.md) | static/dynamic address join |
| [06-ACCURACY](docs/06-ACCURACY.md) | simulation fidelity and measurement |
| [07-PORTABILITY-PLAYBOOKS](docs/07-PORTABILITY-PLAYBOOKS.md) | new GSP/device/arch runs |
| [08-ROADMAP](docs/08-ROADMAP.md) | MCP, custom simulator, device model |
| [09-GSP-FIRMWARE-NOTES](docs/09-GSP-FIRMWARE-NOTES.md) | uproc/falcon/NV-RISCV facts |
| [10-RELATED-WORK](docs/10-RELATED-WORK.md) | Frida/GDB/QEMU-plugin comparison |