# risc-v-gsp-rm-debugger — GSP runtime analysis in a RISC-V QEMU VM > Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > The 2026-10-03 Phase S simulator docs (30–40: cycle model, device model, > A/B verdict, triage) remain **in development** and are labelled as such. > Experimental tooling for simulating and inspecting the GSP firmware's > runtime memory, for `vgsp` 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. risc-v-gsp-rm-debugger 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. An optional deterministic native RV64IMAC backend (M1) runs the same Session in-process: `--backend native` or `ge.launch(..., backend="native")`, with an in-process exec/access trace (M1.5/R4) written as a session blob and rendered by `analyze` (`--trace`, `--trace-start/--trace-end`, `--trace-exec on|off`). 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) ./risc-v-gsp-rm-debugger.sh demo # boot it, hook handlers, watch counters, record + analyze ./risc-v-gsp-rm-debugger.sh demo --backend native # same run on the deterministic native sim ./risc-v-gsp-rm-debugger.sh record --backend native --trace --duration 0.5 # exec/access trace ./risc-v-gsp-rm-debugger.sh info # environment / tooling check ``` Interactively instrument a session: ```bash ./risc-v-gsp-rm-debugger.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf risc-v-gsp-rm-debugger> bp rpc_sum risc-v-gsp-rm-debugger> watch gsp_ctrl+0x10 8 w risc-v-gsp-rm-debugger> x 0x80000840 64 risc-v-gsp-rm-debugger> c 2 ``` Or launch a target separately and attach to it by port: ```bash ./risc-v-gsp-rm-debugger.sh launch --kernel # prints the gdbstub port, keeps QEMU alive ./risc-v-gsp-rm-debugger.sh attach --port --kernel ``` 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 sim/ deterministic native RV64IMAC simulator (M1: decode, RAM, UART; M1.5: exec/access trace in sim/trace.py) firmware/uproc_demo/RV64 bare-metal demo "uproc" (mailbox RPC, state machine, trap) sdk/ injected-service SDK (position-independent RV64 blobs) qemu/ launch helper + optional TCG plugin for full memory tracing ghidra/ Ghidra scripts (export symbols, annotate hits, control bridge) plugins/ example plugin, MCP server, RM-harness plugin + authoring guide examples/ Python instrumentation scripts and declarative probe specs harness/ automation harness (mutation, portability, version diff, control discovery/reachability, value-validation demos, S4 A/B + new-version triage: sim_qemu_line.py, triage.py) rmharness/ host RM oracle wrappers + read-only capture harness gpgpu-sim/ Phase G overlay scaffold (configs, patches, scripts; docs/30) tests/ unit tests + QEMU integration smoke tests docs/ full documentation set (design, scripting, plugins, accuracy, portability playbooks, roadmap, service/injection guides, simulator device model/cycle/A-B/review docs 30-40) dumps/ recorded sessions (gitignored) SIMULATOR-WORK-BOUNDARY.txt scope contract for the 2026-10-03 simulator wave ``` ## 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 risc-v-gsp-rm-debugger 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 | | [11-GSP-RM-SERVICE-DEVELOPER-GUIDE](docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md) | writing, injecting and debugging firmware services | | [12-INJECTION-SDK](docs/12-INJECTION-SDK.md) | injection blob/ABI specification | | [13-GHIDRA-CONTROL](docs/13-GHIDRA-CONTROL.md) | driving risc-v-gsp-rm-debugger from GhidraScripts | | [14-ADVERSARIAL-INTEROP-GUIDE](docs/14-ADVERSARIAL-INTEROP-GUIDE.md) | navigating unpredictable/adversarial firmware change | | [15-AGENTIC-GSP-IDE](docs/15-AGENTIC-GSP-IDE.md) | agentic workflows and runbooks | | [16-CUSTOM-SIMULATOR](docs/16-CUSTOM-SIMULATOR.md) | non-QEMU simulator design; M1 native backend + M1.5 trace status/usage | | [17-RM-HARNESS](docs/17-RM-HARNESS.md) | host RM oracle harness (`rmharness`, wrappers, capture) | | [18-HARNESS-AUTOMATION](docs/18-HARNESS-AUTOMATION.md) | mutation/portability automation harness | | [19-CONTROL-DISCOVERY](docs/19-CONTROL-DISCOVERY.md) | unknown-call discovery and reachability | | [20-MCP-SERVER](docs/20-MCP-SERVER.md) | bundled MCP server plugin | | [21-CI-RELEASE-PIPELINE](docs/21-CI-RELEASE-PIPELINE.md) | release triage pipeline (`harness/ci_release.py`) | | [22-PORTING-CUDA-AND-DEVICES](docs/22-PORTING-CUDA-AND-DEVICES.md) | portability playbook for new CUDA/devices | | [23-RM610-READINESS](docs/23-RM610-READINESS.md) | RM 610 readiness checklist | | [24-DEVICE-MAP](docs/24-DEVICE-MAP.md) | versioned first-touch MMIO device map | | [25-VALUE-VALIDATION](docs/25-VALUE-VALIDATION.md) | value-validation demos (s01–s10) | | [26-ARCHITECTURE](docs/26-ARCHITECTURE.md) | full architecture/API surface map | | [27-TOOL-AUDIT](docs/27-TOOL-AUDIT.md) | tool audit: purpose, tests, usage, status | | [28-PORTING-AUTOMATION](docs/28-PORTING-AUTOMATION.md) | driver-version sweep and new-device scaffolds (pilot, dry-run default) | | [29-PACKAGING-AND-TRIALING](docs/29-PACKAGING-AND-TRIALING.md) | trial simulation packages (pilot) | | [30-GPGPU-SIM-INTEGRATION](docs/30-GPGPU-SIM-INTEGRATION.md) | GPGPU-Sim overlay: scaffold, build port, admission drafts (Phase G) | | [31-TURING-TU104-PARAMETERS](docs/31-TURING-TU104-PARAMETERS.md) | Turing TU104 parameter dossier (public sources) | | [32-GSP-CYCLE-MODEL](docs/32-GSP-CYCLE-MODEL.md) | modeled per-instruction cycle accounting (not silicon timing) | | [33-AMPERE-PARAMETERS](docs/33-AMPERE-PARAMETERS.md) | Ampere parameter dossier (public sources) | | [34-BLACKWELL-SOURCES](docs/34-BLACKWELL-SOURCES.md) | Blackwell source classification (public/private leads) | | [35-GREENEYE-SIMULATOR-DESIGN](docs/35-GREENEYE-SIMULATOR-DESIGN.md) | standalone GSP simulator design; Phase S/G scope and gates | | [36-GSP-DEVICE-MODEL](docs/36-GSP-DEVICE-MODEL.md) | S1 device model, versioned profiles, boot ladder B0–B2 | | [37-SIM-QEMU-LINE](docs/37-SIM-QEMU-LINE.md) | simulator-vs-QEMU A/B harness and measured line verdict | | [38-GSP-EM-API](docs/38-GSP-EM-API.md) | TLV boundary between the GSP emulator and a system simulator (design) | | [39-RE-WORKFLOW-REVIEW](docs/39-RE-WORKFLOW-REVIEW.md) | reverse-engineering workflow review: time sinks and upgrades | | [40-NEW-VERSION-TRIAGE](docs/40-NEW-VERSION-TRIAGE.md) | one-command new-version triage (`harness/triage.py`, `./risc-v-gsp-rm-debugger.sh triage`) | | [41-STABILITY-AND-TIME-TO-VALUE](docs/41-STABILITY-AND-TIME-TO-VALUE.md) | formal stability/value report: phased improvements, proof, adversarial review, conditions | | [RISC-V-GSP-RM-DEBUGGER-ROADMAP](RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) | the long-term program (H1–H7) | Scope contract for the current simulator wave: [`SIMULATOR-WORK-BOUNDARY.txt`](SIMULATOR-WORK-BOUNDARY.txt).