diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/docs/02-USAGE.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/02-USAGE.md | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md b/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md new file mode 100644 index 0000000..53cf19f --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md @@ -0,0 +1,168 @@ +# 02 — green-eye 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 +./greeneye.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 +./greeneye.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 +./greeneye.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 +./greeneye.sh launch --kernel <elf> # prints: gdbstub: 127.0.0.1:<port> +./greeneye.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 +./greeneye.sh run examples/scripts/trace_rpc.py +./greeneye.sh run examples/scripts/dump_diff.py +./greeneye.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 +./greeneye.sh record --duration 2.0 --watch gsp_ctrl+0x10:8 --snapshot gsp_ctrl:392 +./greeneye.sh analyze dumps/20261002-082721-demo +./greeneye.sh analyze dumps/<a> --symbols symbols.json > a.md +./greeneye.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 +./greeneye.sh probe # the project's TU104 570.144 fwimage +./greeneye.sh probe path/to/fw.elf --duration 0.5 +./greeneye.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 +./greeneye.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 +./greeneye.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 +./greeneye.sh plugins +./greeneye.sh run examples/scripts/trace_rpc.py --plugin plugins/example_plugin.py +GREENEYE_PLUGINS=/path/to/plugins ./greeneye.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 (`./greeneye.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 + +green-eye 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. |