# 00 — risc-v-gsp-rm-debugger 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. risc-v-gsp-rm-debugger 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 | | Native RV64IMAC simulator (M1, `--backend native`) | working; QEMU-parity differential test | | Native exec/access trace (M1.5, R4): `--trace`, analyzer coverage | working; trace blob + determinism test | | Test suite | 155 tests green (live QEMU + native differential 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 (verified live) | | Automation harness (mutation/portability/version diff) + value demos | working (18/19/21/25) | | Host RM oracle harness (`rmharness`) | wrappers + capture working; device tables depend on driver permissions (17) | | First-touch device map + lenient native MMIO | working (24) | | MCP server (`plugins/mcp_server.py`) | working (20); stdlib-only, read-only by default | | Porting automation + trial packaging (28/29) | scaffolds + tests present; unadmitted pilots (dry-run default) | | Native M2+ device model | roadmap only (08, 16) | ## Quick start ```bash cd open-iov/debug/risc-v-gsp-rm-vm make demo # build the bundled RV64 uproc demo ./risc-v-gsp-rm-debugger.sh demo # canned instrumentation pass, records a session ./risc-v-gsp-rm-debugger.sh info # environment check ./risc-v-gsp-rm-debugger.sh probe # run the real GSP fwimage and report first divergence ``` Interactively: ```bash ./risc-v-gsp-rm-debugger.sh demo --no-build --duration 0 # launches; prints the gdbstub port ./risc-v-gsp-rm-debugger.sh attach --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 risc-v-gsp-rm-debugger | | [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 risc-v-gsp-rm-debugger 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) | native simulator (M1/M1.5 implemented; M2+ design) | | [17-RM-HARNESS](17-RM-HARNESS.md) | host RM oracle harness (`rmharness`) | | [18-HARNESS-AUTOMATION](18-HARNESS-AUTOMATION.md) | mutation/portability automation | | [19-CONTROL-DISCOVERY](19-CONTROL-DISCOVERY.md) | unknown-call discovery and reachability | | [20-MCP-SERVER](20-MCP-SERVER.md) | bundled MCP server plugin | | [21-CI-RELEASE-PIPELINE](21-CI-RELEASE-PIPELINE.md) | release triage pipeline | | [22-PORTING-CUDA-AND-DEVICES](22-PORTING-CUDA-AND-DEVICES.md) | porting playbook | | [23-RM610-READINESS](23-RM610-READINESS.md) | RM 610 readiness checklist | | [24-DEVICE-MAP](24-DEVICE-MAP.md) | first-touch MMIO device map | | [25-VALUE-VALIDATION](25-VALUE-VALIDATION.md) | value-validation demos s01–s10 | | [26-ARCHITECTURE](26-ARCHITECTURE.md) | full architecture and API surface map | | [27-TOOL-AUDIT](27-TOOL-AUDIT.md) | tool audit: purpose, tests, usage, status | | [28-PORTING-AUTOMATION](28-PORTING-AUTOMATION.md) | driver-version sweep and new-device scaffolds (pilot) | | [29-PACKAGING-AND-TRIALING](29-PACKAGING-AND-TRIALING.md) | trial simulation packages (pilot) | | [RISC-V-GSP-RM-DEBUGGER-ROADMAP](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) | long-term program H1–H7 | ## Where this fits in the Open-IOV workflow risc-v-gsp-rm-debugger 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*; risc-v-gsp-rm-debugger answers *what did it do*. * **Guest diagnostics** (`tools/guest-diag`) answer *what did the guest driver do*; risc-v-gsp-rm-debugger answers *what did the firmware server do*. * **The physical backend** (PLAN B) answers *what does real silicon do*; risc-v-gsp-rm-debugger 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 risc-v-gsp-rm-debugger, record the same events, and compare with `compare` (see 06 and 07).