From ba58dcdc5ad6ca021c723d279f33e3f14e1184df Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 08:36:35 -0400 Subject: debug: add green-eye GSP/uproc RISC-V VM runtime analysis tooling Adds open-iov/debug/risc-v-gsp-rm-vm: a GDB-free instrumentation stack that boots uproc/GSP firmware in qemu-system-riscv64 and provides Frida-like hooks, breakpoints, watchpoints, memory dumps, structure decoding, snapshot diffs, recorded sessions, declarative probes, a plugin API and a Ghidra symbol/hit bridge. Verified: 25 tests green (including a live QEMU smoke test); the demo uproc boots with correct hook/leave/watch/schema/snapshot/fault evidence; the optional TCG trace plugin builds and recorded 15M trace lines in 3 s; the TU104 570.144 fwimage probe reports its first exception (load access fault at firmware vaddr 0x4009014 reading 0x2000000000000A00). Documentation: lean tool docs under debug/risc-v-gsp-rm-vm/docs/00-10, a new docs/05-operations/03-risc-v-gsp-rm-vm.md debugging document, and '# TOOL IN DEVELOPMENT - NOT READY YET!' markers in docs/README.md, the onboarding tooling table and the debugging workflows doc. Vendors qemu-plugin.h from QEMU v8.2.2 (GPL-2.0-or-later), with its license header intact, so the optional TCG plugin builds without a QEMU source tree. --- debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md | 76 ++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md (limited to 'debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md') diff --git a/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md new file mode 100644 index 0000000..a2a45db --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md @@ -0,0 +1,76 @@ +# 10 — related work: why not Frida, and what each tool is for + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. + +## 1. Frida + +**Verdict for the firmware VM: not applicable.** Upstream Frida ships no +RISC-V target (checked against the 17.20 release assets: x86/x86_64, +arm/arm64, mips, macOS/Windows/QNX/Prospero — no `linux-riscv64`), and +frida-agent requires a hosted OS process. The GSP image is bare-metal RV64 +with its own libos; there is nothing to inject into, and even a hypothetical +RISC-V port would need an OS layer the firmware does not have. + +**Where the Frida *idea* lives in green-eye:** the scripting model. `Session` +offers `hook`/`watch`/`memory`/`events` with Python callbacks, which is the +part of Frida that matters for this workflow. The difference is transport: +RSP to QEMU instead of an injected agent. + +**Where Frida is applicable in the project:** host- or guest-userland x86_64 +work (e.g. the CUDA userspace layer) if a dynamic tracer is ever wanted there. +That is outside this tool's scope; the existing ptrace tracer covers the +guest today. + +## 2. GDB / gdbstub + +QEMU's gdbstub is the transport both tools share. GDB itself is still useful +for *debugging green-eye* (stub behaviour, protocol traces), and `gdb +-multiarch` can inspect the same target interactively. It is not the +instrumentation layer here because: + +* every operation becomes a subprocess/parse problem instead of an API call; +* recording, symbol annotation, structure decoding and session diffing would + have to be rebuilt around GDB/MI anyway; +* the project already uses GDB Python scripts for the CUDA corpus; green-eye + is the equivalent for firmware, with a stronger data model. + +## 3. QEMU TCG plugins + +The correct complement, not a competitor: plugins execute inside QEMU and can +observe **every** instruction and memory access, which gdbstub breakpoints +cannot. green-eye's `qemu/greeneye_trace.c` emits a JSONL access trace for +exactly this; integrating it into the session format is R4 on the roadmap. +Rule of thumb: use green-eye hooks for semantics ("handler X ran with these +args") and TCG plugins for coverage/heatmaps ("every write to this window"). + +## 4. Unicorn / emulator libraries + +Unicorn (and similar CPU emulators) can execute RV64 code faster to set up +than QEMU and embed cleanly in Python, but they model no board at all and +have weaker debug infrastructure. They are candidates for the **custom +simulator** (R2) once the required device semantics are known — the same +reason the roadmap defers that work. + +## 5. `rr` / record-replay + +`rr` does not support RISC-V guests and records at the host-process level. +QEMU's own record/replay (`-icount`) can provide deterministic reruns later; +green-eye's session recording occupies a different niche (semantic events, +not full replay) and can coexist. + +## 6. Comparison table + +| Tool | Layer | RISC-V firmware | green-eye relationship | +|---|---|---|---| +| Frida | userland process injection | no | conceptual model only | +| GDB + gdbstub | execution control | yes (transport) | debugging green-eye; same stub | +| QEMU TCG plugin | full instruction/memory trace | yes | complement (R4) | +| green-eye | semantic instrumentation + recording + analysis | yes | this tool | +| Unicorn/rv8/etc. | CPU emulation library | yes | R2 candidate | +| Ghidra | static decompilation | yes | symbol/hit bridge (05) | + +## 7. Reading list + +* `docs/01-DESIGN.md` — where each layer sits. +* `docs/05-GHIDRA-BRIDGE.md` — the static/dynamic join. +* `docs/08-ROADMAP.md` — R1 device model, R2 custom simulator, R3 MCP. -- cgit v1.2.3