# 02 — risc-v-gsp-rm-debugger usage

> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.

All commands are run from `open-iov/debug/risc-v-gsp-rm-vm/`.

## 0. Requirements

* `qemu-system-riscv64` (Ubuntu: `apt install qemu-system-misc`);
* Python 3.10+ (stdlib only);
* for the demo firmware: `clang` and `lld` (`apt install lld-18` provides
  `/usr/lib/llvm-18/bin/ld.lld`).

Check everything:

```bash
./risc-v-gsp-rm-debugger.sh info
make test          # builds the demo then runs unit + QEMU smoke tests
```

## 1. The canned demo (fastest way to see it work)

```bash
make demo
./risc-v-gsp-rm-debugger.sh demo
```

It boots `firmware/uproc_demo/build/uproc_demo.elf`, installs hooks on all
`rpc_*` handlers and a watchpoint on `rpc_count`, runs the firmware self-test,
injects a `PING` from the host, decodes and diffs the control block, then
injects `FAULT` to capture the `ebreak` trap. A session is recorded under
`dumps/` and a `summary.md` is written.

Options: `--no-build`, `--duration SECONDS`, `--kernel PATH`, `--record PATH`.

## 2. Interactive REPL

```bash
./risc-v-gsp-rm-debugger.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf
```

`attach` launches the target itself when `--port` is omitted. To share a
target between terminals, launch it separately and attach by port:

```bash
./risc-v-gsp-rm-debugger.sh launch --kernel <elf>     # prints: gdbstub: 127.0.0.1:<port>
./risc-v-gsp-rm-debugger.sh attach --port <port> --kernel <elf>
```

REPL commands:

| Command | Meaning |
|---|---|
| `regs` / `reg <name> [value]` | read/write registers |
| `x <addr> [len]` | annotated hexdump |
| `mem <addr> <len>` | raw bytes (hex) |
| `w <addr> <hex>` / `wstr <addr> <text>` | write memory |
| `bp <addr\|symbol> [sw\|hw]` | breakpoint that prints on hit |
| `hook <addr\|symbol>` | enter/leave hook with printing |
| `watch <addr\|symbol> [size] [w\|r\|a]` | watchpoint |
| `s [n]` / `c [seconds]` | step n; continue for N seconds |
| `snap <label> <addr> <len>` | snapshot a region into the session |
| `sym <addr\|name>` | symbol resolution |
| `events [n]` | tail the recorded event stream |
| `note <text>` | annotate the session |
| `quit` | close and exit |

Plugin-provided commands appear automatically (e.g. `gehits` from the example
plugin when loaded with `--plugin plugins/example_plugin.py`).

## 3. Scripted sessions

```bash
./risc-v-gsp-rm-debugger.sh run examples/scripts/trace_rpc.py
./risc-v-gsp-rm-debugger.sh run examples/scripts/dump_diff.py
./risc-v-gsp-rm-debugger.sh run my_script.py --kernel <elf> --plugin plugins/example_plugin.py
```

The script runs with `ge`, `s`/`session`, `memory`, `symbols`, `recorder` in
scope and is recorded by default. See [03-SCRIPTING](03-SCRIPTING.md).

## 4. Recording, analysis, comparison

```bash
./risc-v-gsp-rm-debugger.sh record --duration 2.0 --watch gsp_ctrl+0x10:8 --snapshot gsp_ctrl:392
./risc-v-gsp-rm-debugger.sh analyze dumps/20261002-082721-demo
./risc-v-gsp-rm-debugger.sh analyze dumps/<a> --symbols symbols.json > a.md
./risc-v-gsp-rm-debugger.sh compare dumps/<run-a> dumps/<run-b> --symbols
```

`analyze` prints a markdown report: event counts, breakpoint hits by symbol,
watchpoint hits, written pages, stepped coverage, snapshot inventory and a
timeline. `compare` diffs two sessions symbolically (hit-count deltas, watch
deltas, written-page deltas) — the A/B primitive for bare-metal vs
vfio-mdev and old-firmware vs new-firmware runs.

## 5. Probing an arbitrary firmware image

```bash
./risc-v-gsp-rm-debugger.sh probe                       # the project's TU104 570.144 fwimage
./risc-v-gsp-rm-debugger.sh probe path/to/fw.elf --duration 0.5
./risc-v-gsp-rm-debugger.sh probe --instructions 2000 --no-relocate
```

Segments are flattened into a raw kernel loaded at `0x80000000`; because QEMU
starts raw kernels at the load base, a tiny PC-relative trampoline at offset 0
jumps to the image's real (relocated) entry. The run is bounded and the report
shows the **first exception** (faulting instruction, access address/size,
cause) plus the QEMU log tail. For the real GSP image expect an early
load-access fault on an unmodelled GPU register — that is the honest result
(see [06-ACCURACY](06-ACCURACY.md)).

## 6. Symbol databases

```bash
./risc-v-gsp-rm-debugger.sh symbols export \
    --names ../../userspace/cuda/570.144/annotations/names.tsv \
    --index <run>/analysis/decompiled/decompiled_index.tsv \
    --callgraph <run>/analysis/elf-index/callgraph.tsv \
    --bias 0x100000 -o symbols-570.json
./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-570.json 0x453ef0
```

`--bias` normalises file vaddrs to runtime addresses (`0x100000` is the
libcuda Ghidra image base; use 0 for firmware linked at its load address).

## 7. Plugins

```bash
./risc-v-gsp-rm-debugger.sh plugins
./risc-v-gsp-rm-debugger.sh run examples/scripts/trace_rpc.py --plugin plugins/example_plugin.py
GREENEYE_PLUGINS=/path/to/plugins ./risc-v-gsp-rm-debugger.sh demo
```

See [04-PLUGINS](04-PLUGINS.md).

## 8. Make targets

| Target | Action |
|---|---|
| `make demo` | build the demo firmware |
| `make test` | build + unit tests + live QEMU smoke |
| `make demo-run` | `greeneye demo --no-build` |
| `make probe-real` | run the TU104 fwimage probe |
| `make plugin` | build the optional TCG plugin |
| `make clean` | remove builds, dumps and `__pycache__` |

## 9. Troubleshooting

* **`qemu-system-riscv64 not found`** — install `qemu-system-misc` or set
  `GREENEYE_QEMU`.
* **`gdbstub port not ready`** — QEMU exited early; the error includes its
  stderr. Check the ELF actually loads (`./risc-v-gsp-rm-debugger.sh info`).
* **A run seems stuck** — sessions never `pkill -f greeneye` (it matches the
  invoking shell). Use `pkill -9 -f '[q]emu-system-riscv64'` to clean up
  leftover emulators.
* **Target stops immediately at `0x1000`** — the firmware was not passed to
  QEMU; check the `-kernel` path (known historical bug, fixed).
* **`Permission denied` on `/dev/kvm`** — not needed here; QEMU `virt` may
  fall back to TCG. For speed, ensure the user can use KVM.

## 10. Safety

risc-v-gsp-rm-debugger touches no GPU, no mdev, no kernel module and no host driver. It
runs unprivileged QEMU instances on loopback gdbstub ports. The only host
side effects are temporary directories under `/tmp` and `dumps/` under the
tool tree. It is safe to run alongside the CUDA/PLAN-B work, but keep an eye
on RAM/CPU if large snapshots are recorded.