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 | 46 |
1 files changed, 23 insertions, 23 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 index 53cf19f..686d4c9 100644 --- a/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md +++ b/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md @@ -1,4 +1,4 @@ -# 02 — green-eye usage +# 02 — risc-v-gsp-rm-debugger usage > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. @@ -14,7 +14,7 @@ All commands are run from `open-iov/debug/risc-v-gsp-rm-vm/`. Check everything: ```bash -./greeneye.sh info +./risc-v-gsp-rm-debugger.sh info make test # builds the demo then runs unit + QEMU smoke tests ``` @@ -22,7 +22,7 @@ make test # builds the demo then runs unit + QEMU smoke tests ```bash make demo -./greeneye.sh demo +./risc-v-gsp-rm-debugger.sh demo ``` It boots `firmware/uproc_demo/build/uproc_demo.elf`, installs hooks on all @@ -36,15 +36,15 @@ Options: `--no-build`, `--duration SECONDS`, `--kernel PATH`, `--record PATH`. ## 2. Interactive REPL ```bash -./greeneye.sh attach --kernel firmware/uproc_demo/build/uproc_demo.elf +./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 -./greeneye.sh launch --kernel <elf> # prints: gdbstub: 127.0.0.1:<port> -./greeneye.sh attach --port <port> --kernel <elf> +./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: @@ -71,9 +71,9 @@ 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 +./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 @@ -82,10 +82,10 @@ 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 +./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, @@ -97,9 +97,9 @@ 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 +./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 @@ -113,12 +113,12 @@ load-access fault on an unmodelled GPU register — that is the honest result ## 6. Symbol databases ```bash -./greeneye.sh symbols export \ +./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 -./greeneye.sh symbols resolve --db symbols-570.json 0x453ef0 +./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-570.json 0x453ef0 ``` `--bias` normalises file vaddrs to runtime addresses (`0x100000` is the @@ -127,9 +127,9 @@ 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 +./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). @@ -150,7 +150,7 @@ See [04-PLUGINS](04-PLUGINS.md). * **`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`). + 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. @@ -161,7 +161,7 @@ See [04-PLUGINS](04-PLUGINS.md). ## 10. Safety -green-eye touches no GPU, no mdev, no kernel module and no host driver. It +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 |