diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/README.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/README.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/README.md b/debug/risc-v-gsp-rm-vm/README.md new file mode 100644 index 0000000..66f53fa --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/README.md @@ -0,0 +1,77 @@ +# 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 | |