diff options
| author | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 11:44:31 -0400 |
|---|---|---|
| committer | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 11:44:31 -0400 |
| commit | 1c99bfbeffff04529f6f669601fdf835a73778da (patch) | |
| tree | 5867bab46e5848541df36c703f6fd8d6d0256e54 /debug/risc-v-gsp-rm-vm/docs | |
| parent | 2fd653044127a665e4677a2cdfb58120d7b3e16b (diff) | |
| download | open-iov-1c99bfbeffff04529f6f669601fdf835a73778da.tar.gz open-iov-1c99bfbeffff04529f6f669601fdf835a73778da.zip | |
rename (cosmetic): green-eye -> risc-v-gsp-rm-debugger in user-facing names, docs, CLI, launcher and CI workflow; internal greeneye package/module identifiers unchanged (includes in-flight greeneye module edits present in the tree)
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/docs')
30 files changed, 256 insertions, 257 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md b/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md index e4906cc..f09d576 100644 --- a/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md +++ b/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md @@ -1,4 +1,4 @@ -# 00 — green-eye overview +# 00 — risc-v-gsp-rm-debugger overview > **# TOOL IN DEVELOPMENT - NOT READY YET!** > Experimental tooling for simulating and inspecting the GSP firmware's @@ -15,7 +15,7 @@ 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. -green-eye runs uproc/GSP firmware in `qemu-system-riscv64` and gives the +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), @@ -60,16 +60,16 @@ whole stack scriptable, and QEMU is just the first execution backend. ```bash cd open-iov/debug/risc-v-gsp-rm-vm make demo # build the bundled RV64 uproc demo -./greeneye.sh demo # canned instrumentation pass, records a session -./greeneye.sh info # environment check -./greeneye.sh probe # run the real GSP fwimage and report first divergence +./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 -./greeneye.sh demo --no-build --duration 0 # launches; prints the gdbstub port -./greeneye.sh attach --port <port> --kernel firmware/uproc_demo/build/uproc_demo.elf +./risc-v-gsp-rm-debugger.sh demo --no-build --duration 0 # launches; prints the gdbstub port +./risc-v-gsp-rm-debugger.sh attach --port <port> --kernel firmware/uproc_demo/build/uproc_demo.elf ``` ## Document map @@ -79,7 +79,7 @@ Interactively: | [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 green-eye | +| [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 | @@ -88,7 +88,7 @@ Interactively: | [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 green-eye from Ghidra | +| [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) | @@ -105,23 +105,23 @@ Interactively: | [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) | -| [GREEN-EYE-ROADMAP](../GREEN-EYE-ROADMAP.md) | long-term program H1–H7 | +| [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 -green-eye is a **development and research** tool, alongside the Ghidra corpus +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*; green-eye answers *what did it do*. +* **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*; green-eye answers *what did the firmware server do*. + 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*; - green-eye provides a safe place to repeat, mutate and single-step the same + 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 green-eye, record the same events, and compare with `compare` +firmware in risc-v-gsp-rm-debugger, record the same events, and compare with `compare` (see 06 and 07). <!-- change (2026-10-02): add docs 28/29 to the status table and document map diff --git a/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md b/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md index c5de2da..034f87c 100644 --- a/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md +++ b/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md @@ -1,4 +1,4 @@ -# 01 — green-eye design +# 01 — risc-v-gsp-rm-debugger design > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. @@ -73,7 +73,7 @@ the plugin layer, not the transport. same return address are queued (LIFO). Tail calls and asynchronous interrupts are not tracked — documented limitation. * **Watchpoints**: `Z2/Z3/Z4` (write/read/access). QEMU stops *at* the - accessing instruction, so green-eye temporarily clears the watch, steps one + accessing instruction, so risc-v-gsp-rm-debugger temporarily clears the watch, steps one instruction, and re-arms it. Without this the target livelocks on the same store. * **Stop dispatch**: every stop reads the register file, resolves the PC to a @@ -144,7 +144,7 @@ declarative so they can come from a Ghidra type export or a plugin later. * The **kernel fast path** passes `-kernel <elf>`; QEMU loads segments and sets PC. * The **probe path** passes each PT_LOAD segment as a raw loader device and - green-eye sets PC through the gdbstub — this lets a firmware linked for GPU + risc-v-gsp-rm-debugger sets PC through the gdbstub — this lets a firmware linked for GPU physical addresses be relocated into RAM for observation. * A **custom simulator** can be added as a session backend later (roadmap, not v0.1) because `Session` only assumes the RSP-like operations. 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 diff --git a/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md b/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md index 89c61c4..93dfccf 100644 --- a/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md +++ b/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md @@ -1,9 +1,9 @@ -# 03 — green-eye scripting +# 03 — risc-v-gsp-rm-debugger scripting > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. -green-eye scripts are ordinary Python programs run with -`./greeneye.sh run <script.py>` (or `python3 -m greeneye run …`). The +risc-v-gsp-rm-debugger scripts are ordinary Python programs run with +`./risc-v-gsp-rm-debugger.sh run <script.py>` (or `python3 -m greeneye run …`). The names `ge`, `session`/`s`, `memory`, `symbols`, `recorder` are preloaded, and `__file__` points at the script path (use it to locate bundled assets). @@ -214,7 +214,7 @@ finally: ## 13. Errors and timeouts -All green-eye errors derive from `greeneye.GreenEyeError`: +All risc-v-gsp-rm-debugger errors derive from `greeneye.GreenEyeError`: `RspTimeout` (transport), `RspProtocolError`, `TargetError`, `SymbolNotFound`, `StructError`. `RspClient.timeout` (default 10 s) bounds a single packet read; `run`'s budget bounds the whole pass. diff --git a/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md b/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md index db9ee27..b0e6767 100644 --- a/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md +++ b/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md @@ -1,11 +1,11 @@ -# 04 — writing green-eye plugins +# 04 — writing risc-v-gsp-rm-debugger plugins > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. A plugin is a Python module exposing `register(ge)`. It is loaded before the session runs (CLI `--plugin PATH`, `GREENEYE_PLUGINS`, or the bundled `plugins/` directory) and can add instrumentation, CLI commands and harness -logic without touching green-eye itself. +logic without touching risc-v-gsp-rm-debugger itself. ## 1. The API object @@ -46,7 +46,7 @@ findings are replayable and comparable like any other event. ## 3. The four plugin classes -**(a) Runtime RE tools** — add analysis that green-eye does not have: +**(a) Runtime RE tools** — add analysis that risc-v-gsp-rm-debugger does not have: ```python def register(ge): @@ -103,15 +103,15 @@ def register(ge): Run it with: ```bash -./greeneye.sh run examples/scripts/trace_rpc.py --plugin plugins/example_plugin.py +./risc-v-gsp-rm-debugger.sh run examples/scripts/trace_rpc.py --plugin plugins/example_plugin.py ``` ## 5. Testing a plugin -1. Load it against the demo firmware (`./greeneye.sh demo --plugin …`) — the +1. Load it against the demo firmware (`./risc-v-gsp-rm-debugger.sh demo --plugin …`) — the session must remain green and the plugin's events must appear in `events.jsonl`. -2. Unit-test pure logic outside green-eye; keep hooks small. +2. Unit-test pure logic outside risc-v-gsp-rm-debugger; keep hooks small. 3. Never let a plugin assume a particular firmware: gate on `ge.symbols.get(name)` and log a skip instead of failing. diff --git a/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md b/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md index f7f46c3..4f41d33 100644 --- a/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md +++ b/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md @@ -2,7 +2,7 @@ > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. -Ghidra answers *what is the code*; green-eye answers *what did it do*. The +Ghidra answers *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. The bridge joins them in both directions: Ghidra symbols into the runtime session, runtime hit addresses back into the Ghidra project. @@ -19,13 +19,13 @@ runtime hit addresses back into the Ghidra project. * CUDA `libcuda` in the host oracle: runtime base from `/proc/<pid>/maps`; `--bias` normalises it if you want runtime addresses in the DB. * The project's `decompiled_index.tsv`/bucket TSVs carry **both** program and - file addresses; green-eye parses both and stores the program address in + file addresses; risc-v-gsp-rm-debugger parses both and stores the program address in `symbol.extras["program_addr"]`. ## 2. Build a symbol DB from Ghidra exports ```bash -./greeneye.sh symbols export \ +./risc-v-gsp-rm-debugger.sh symbols export \ --names ../../userspace/cuda/570.144/annotations/names.tsv \ --index ../../userspace/cuda/570.144/run/analysis/decompiled/decompiled_index.tsv \ --exports ../../userspace/cuda/570.144/run/analysis/elf-index/exports.tsv \ @@ -38,7 +38,7 @@ the existing export scripts (`ExportFunctionIndex.java`, `DecompileFunctions.java`, …) to produce TSVs, then: ```bash -./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-gsp.json +./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-gsp.json ``` `load_index_tsv` is column-aware: it accepts @@ -62,7 +62,7 @@ live hit to the decompiled body. ## 4. Annotate hits back into Ghidra ```bash -./greeneye.sh analyze dumps/<run> --symbols symbols-gsp.json --out run.md +./risc-v-gsp-rm-debugger.sh analyze dumps/<run> --symbols symbols-gsp.json --out run.md python3 - <<'PY' from greeneye.ghidra import export_hits from greeneye.symbols import SymbolDB @@ -81,7 +81,7 @@ $GHIDRA/support/analyzeHeadless <proj_dir> <project> -process <program> -noanaly ``` `ExportForGreenEye.java` is the reverse helper: it walks the current program -and writes a green-eye-compatible `addr<TAB>name<TAB>size` TSV. +and writes a risc-v-gsp-rm-debugger-compatible `addr<TAB>name<TAB>size` TSV. `greeneye.ghidra.render_ghidra_command(proj_dir, project, program, hits_tsv)` renders the `analyzeHeadless … MarkGreenEyeHits.java` command line above for @@ -92,11 +92,11 @@ scripts (the helper is not wired into the CLI). Two practical routes today: 1. `greeneye decompose/decompile` → note the file vaddr → script - `s.hook("0x…")` (green-eye translates to runtime via the bias you loaded). + `s.hook("0x…")` (risc-v-gsp-rm-debugger translates to runtime via the bias you loaded). 2. Use `symbols export` from the Ghidra index, then `s.hook("<name>")` by name — the most robust route across recompilations. -A future Ghidra-side green-eye console (roadmap item) can call +A future Ghidra-side risc-v-gsp-rm-debugger console (roadmap item) can call `greeneye` through its CLI to set breakpoints directly from the tool. ## 6. Limits @@ -104,6 +104,6 @@ A future Ghidra-side green-eye console (roadmap item) can call * Wrapper-generated functions are re-laid-out between driver patch versions; transfer names, never raw wrapper addresses (the CUDA playbook's lesson). * The decompiler does not recover struct types; structure schemas for - green-eye decoding must be written or exported separately. + risc-v-gsp-rm-debugger decoding must be written or exported separately. * `decompiled_index.tsv` buckets are large and gitignored; keep symbol JSONs small (name/size/subsystem only) if they must be tracked. diff --git a/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md b/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md index 1a1ae82..47854d1 100644 --- a/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md +++ b/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md @@ -1,4 +1,4 @@ -# 06 — Accuracy: what the green-eye test bed does and does not prove +# 06 — Accuracy: what the risc-v-gsp-rm-debugger test bed does and does not prove > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. > This document is deliberately conservative. Treat every claim without a @@ -6,7 +6,7 @@ ## 1. Purpose -green-eye exists to measure how accurately Open-IOV's GSP emulation +risc-v-gsp-rm-debugger exists to measure how accurately Open-IOV's GSP emulation (`gsp-rm-vfio` and the in-kernel emulation) reproduces the behaviour of the real GSP firmware, and to make the firmware itself analysable. That makes accuracy a first-class deliverable, not an assumption. This document defines @@ -15,14 +15,14 @@ conclusions. ## 2. Fidelity levels -| Level | Property | green-eye today | +| Level | Property | risc-v-gsp-rm-debugger today | |---|---|---| | **L0 — instruction semantics** | RV64IMAC executes as on the device core | high (QEMU TCG, same ISA family) | | **L1 — memory behaviour** | reads/writes/ordering as firmware expects | high for RAM-resident code, *conditional* on mapping the same physical layout | | **L2 — time/concurrency** | cycle counts, DMA latency, interrupt timing | **not modelled** (do not claim) | | **L3 — device environment** | falcon windows, WPR2, CSB/TRANSCOM, PMU, timers, FB DMA, IRQ routing | **absent** (roadmap) | -The practical reading: green-eye is an **execution and memory** microscope, +The practical reading: risc-v-gsp-rm-debugger is an **execution and memory** microscope, not a timing or silicon model. Conclusions of the form "the firmware writes X before Y" are in scope; "the firmware takes N µs" is not. @@ -79,7 +79,7 @@ Define these metrics once and use them everywhere: | # | Metric | How it is measured | |---|---|---| -| M1 | **Inventory coverage** | set of controls/RPCs observed in a real run vs the emulation's handled set (and green-eye's observed set) | +| M1 | **Inventory coverage** | set of controls/RPCs observed in a real run vs the emulation's handled set (and risc-v-gsp-rm-debugger's observed set) | | M2 | **Reply agreement** | field-by-field diff of replies (real vs emulated); canonical-size and consumed-field checks included | | M3 | **Ordering agreement** | sequence alignment of the control/event stream (edit distance / LCS) | | M4 | **State agreement** | state-machine transitions observed in the firmware vs the emulation's internal state model | @@ -90,7 +90,7 @@ Define these metrics once and use them everywhere: Reference capture: * real hardware/backend: the project's existing RPC logs (module trace, `gsp-phys-log-dump`, status-queue drains) and the static-config oracle; -* green-eye: `events.jsonl` + snapshots, symbol-annotated. +* risc-v-gsp-rm-debugger: `events.jsonl` + snapshots, symbol-annotated. Comparison: `greeneye compare dumps/real-<run> dumps/greeneye-<run> --symbols`, then a short table of M1–M6 with counts. Never publish a single @@ -98,7 +98,7 @@ Comparison: `greeneye compare dumps/real-<run> dumps/greeneye-<run> ## 6. Adversarial interoperability use -green-eye is also a safe place to be adversarial: corrupt a reply, flip a +risc-v-gsp-rm-debugger is also a safe place to be adversarial: corrupt a reply, flip a capability bit, truncate a control payload, or inject a fault at a chosen firmware PC, then observe whether the emulation and the firmware agree on the failure path. The rules: @@ -112,7 +112,7 @@ failure path. The rules: ## 7. Validating the tool itself -Before trusting a green-eye session: +Before trusting a risc-v-gsp-rm-debugger session: * the demo firmware self-test must pass (`greeneye demo`, `make test`); * the session must contain the expected `hook`/`watch` registrations and a diff --git a/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md b/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md index 5426bf1..b0c8c3f 100644 --- a/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md +++ b/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md @@ -5,7 +5,7 @@ These playbooks cover the three churn axes the project expects: a new GSP firmware version, the same firmware on a new device, and a new GPU architecture (e.g. GB10 / DGX Spark / Surface-class). They reuse the -project's existing version discipline and add green-eye's runtime layer. +project's existing version discipline and add risc-v-gsp-rm-debugger's runtime layer. ## 0. Common setup @@ -16,7 +16,7 @@ project's existing version discipline and add green-eye's runtime layer. 3. Build a symbol DB for the new image: * import the fwimage into the existing Ghidra project tooling (`tools/ghidra/analyze_fwimage.py`, `DecompileFunctions.java`), - * `./greeneye.sh symbols export --index <export.tsv> -o symbols-<ver>.json`. + * `./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> -o symbols-<ver>.json`. 4. Record a baseline session of the previous version (see P1.4) so the comparison has an anchor. @@ -29,7 +29,7 @@ emulation is adjusted. fwimage, diff the RPC dispatcher, subcommands, message layouts and version strings against the previous version (`cudatool.py delta`-style discipline for firmware; `diff_corpus.py` for the corpus). -2. **Probe the new image** — `./greeneye.sh probe <new.fwimage>`: record the +2. **Probe the new image** — `./risc-v-gsp-rm-debugger.sh probe <new.fwimage>`: record the first divergence and the first MMIO/read/write addresses. Compare with the previous version's probe; changed first-touch addresses are early structure-change signals. @@ -40,7 +40,7 @@ emulation is adjusted. * `greeneye record --kernel <rehosted elf> --duration N --snapshot <regions>` or the scripted harness (`run`), * the real-backend reference traces for the same workload. -5. **Compare** — `./greeneye.sh compare dumps/<old> dumps/<new> --symbols`: +5. **Compare** — `./risc-v-gsp-rm-debugger.sh compare dumps/<old> dumps/<new> --symbols`: hit-count deltas per function, watchpoint deltas, written-page deltas. Investigate every function whose call-count changed before touching the emulation. @@ -60,7 +60,7 @@ emulation is adjusted. 2. Verify the firmware pairing: the image family (TU10x/GH100/LS10 …), FMC partition manifests, and the version string; a mismatched pairing presents as an emulation bug (the project learned this with 570.144 vs 570.211). -3. `./greeneye.sh probe <device fwimage>` on the new device image; compare +3. `./risc-v-gsp-rm-debugger.sh probe <device fwimage>` on the new device image; compare first-divergence maps with the reference device. Differences here usually point at profile data, not logic. 4. Re-run the P1.4/1.5 loop with the device profile applied; record probe + @@ -77,7 +77,7 @@ newer PMU/SEC2 images and possibly RV64GC rather than RV64IMAC). 1. **Confirm the ISA and image shape** — `file`/`readelf` the new fwimage: ISA string, segments, entry, compressed/float extensions. Update the rehost build flags (`-march=…`) accordingly; note that QEMU supports - RV64GC even if green-eye's demo uses IMAC. + RV64GC even if risc-v-gsp-rm-debugger's demo uses IMAC. 2. **Check the platform's boot variant** — newer platforms use FMC/manifest partition models (`uproc/*_riscv/fmc`, `safety/PMU-*`, `conf_compute` Init→ACR→RM flow). Record which partition model the image uses; the @@ -89,7 +89,7 @@ newer PMU/SEC2 images and possibly RV64GC rather than RV64IMAC). 4. **Run the P1 loop** with the new architecture profile; expect the probe to show *different* first-touch addresses (new register windows). Update the device-model scope in `08-ROADMAP.md` with what the probe revealed. -5. **Host portability** — green-eye itself is Python and QEMU; on aarch64 +5. **Host portability** — risc-v-gsp-rm-debugger itself is Python and QEMU; on aarch64 hosts install `qemu-system-misc` there and the same commands run. Keep host-specific paths out of session metadata. @@ -104,7 +104,7 @@ real firmware for a chosen workload. * or the vfio-mdev path with the same workload. Save the reference event stream in a session-compatible form (or the vendor logs plus a conversion note). -2. **green-eye capture:** run the same workload's firmware-side stimulus in +2. **risc-v-gsp-rm-debugger capture:** run the same workload's firmware-side stimulus in the rehosted simulator; record hooks, watchpoints, snapshots. 3. **Compare:** `greeneye compare` for hit/watch/write profiles; for RPC payloads use M2 field agreement and M3 ordering (a small script or a diff --git a/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md b/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md index 5d8a9b1..3a518c4 100644 --- a/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md +++ b/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md @@ -1,16 +1,16 @@ -# 08 — green-eye roadmap +# 08 — risc-v-gsp-rm-debugger roadmap > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. > This is the **near-term, committed** roadmap (rungs R0–R7 below). The > **long-term program** — adversarial firmware navigation, adjacent > microcontrollers, a non-QEMU custom simulator, a Verilog soft-processor > environment and the agentic platform — lives in -> [`../GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md). +> [`../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). > Items here are **not** v0.1. Do not start them ad hoc; each has a gate. ## R0. Product principles -* green-eye stays a **development tool**: no shipped dependencies, no guest +* risc-v-gsp-rm-debugger stays a **development tool**: no shipped dependencies, no guest presence, no kernel-module coupling. * Fidelity improvements must be *measurable* (metrics table in 06) and must not slow the fast path (demo + probe) below usefulness. @@ -72,7 +72,7 @@ only after the guest-bridge work (PLAN B) no longer depends on it. [20-MCP-SERVER](20-MCP-SERVER.md) for the live tool list, transports and capability flags. The text below is the original design sketch. -**Why:** expose green-eye sessions to AI harnesses and other agents under the +**Why:** expose risc-v-gsp-rm-debugger sessions to AI harnesses and other agents under the plugin model the user requested. **Shape:** a plugin (`plugins/mcp_server.py` when built) that wraps the @@ -101,7 +101,7 @@ step traces already cover the common cases. ## R5. Fuzzing and mutation harness Use AFL++ QEMU mode (or a custom mutator) against the rehosted firmware's -RPC input surface, with green-eye recording crash/trap paths and symbol +RPC input surface, with risc-v-gsp-rm-debugger recording crash/trap paths and symbol annotation. Requires R1/R2 for stable input plumbing. Output: a corpus of malformed controls and the firmware's error paths, feeding the emulation's fail-closed rules (project security hygiene). @@ -114,13 +114,13 @@ tables. This automates `07-PORTABILITY-PLAYBOOKS` P1–P3. ## R7. Ghidra two-way console -A Ghidra script/plugin that talks to a live green-eye session (via the CLI or +A Ghidra script/plugin that talks to a live risc-v-gsp-rm-debugger session (via the CLI or a local socket) to toggle breakpoints/watchpoints from the decompiler and to highlight hit addresses. Until then, the hit-TSV + `MarkGreenEyeHits.java` flow is the supported path. -## Not on the green-eye roadmap +## Not on the risc-v-gsp-rm-debugger roadmap * Graphics/display emulation, Windows guest internals, multi-tenant policy — these belong to the main project roadmap, not to this analysis tool. -* Replacing Ghidra: green-eye is the dynamic complement, never a decompiler. +* Replacing Ghidra: risc-v-gsp-rm-debugger is the dynamic complement, never a decompiler. diff --git a/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md b/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md index 216bf93..b930cb9 100644 --- a/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md +++ b/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md @@ -1,4 +1,4 @@ -# 09 — GSP/uproc firmware notes used by green-eye +# 09 — GSP/uproc firmware notes used by risc-v-gsp-rm-debugger > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. > Exact local-source provenance is recorded in the local task record; this @@ -55,7 +55,7 @@ Two OS layers appear in the vendor snapshots: paid for. This is the direction the GSP stack evolves toward. **Implication for the simulator:** the scheduler is not the interesting part -for RPC accuracy; the task/dispatcher semantics are. Green-eye's demo mirrors +for RPC accuracy; the task/dispatcher semantics are. Risc-V GSP-RM debugger's demo mirrors that shape (mailbox → dispatcher → handler → counters), and a rehost shim should stub the scheduler while keeping task entry points and message handling real. @@ -73,7 +73,7 @@ handling real. a live GSP with a debug command (`nvwatch …`) for bring-up. These models matter for portability: a new architecture may change the -partition layout or boot order, and green-eye's probe is the quickest way to +partition layout or boot order, and risc-v-gsp-rm-debugger's probe is the quickest way to see the new first-touch sequence before a device model exists. ## 5. Memory, DMA and registers @@ -84,14 +84,14 @@ see the new first-touch sequence before a device model exists. * The engines exchange data over **CSB/TRANSCOM windows and mailboxes** with DMA into host/FB memory; the physical backend work in Open-IOV already models the message-queue side (status/command queues, doorbells) — that is - the layer green-eye can emulate first when R1 lands. + the layer risc-v-gsp-rm-debugger can emulate first when R1 lands. * The GSP kernel's start path receives its memory permissions as boot args from the bootloader rather than discovering them, which is why a re-host should pass the same structure rather than re-derive it. -## 6. How green-eye models this today (and honestly, does not) +## 6. How risc-v-gsp-rm-debugger models this today (and honestly, does not) -| Firmware aspect | green-eye v0.1 | +| Firmware aspect | risc-v-gsp-rm-debugger v0.1 | |---|---| | Task/dispatcher/state-machine logic | modelled faithfully by the demo and by rehosted code | | RPC handler input/output behaviour | observable and recordable; schemas decode structures | diff --git a/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md index a2a45db..90ca799 100644 --- a/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md +++ b/debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md @@ -11,7 +11,7 @@ frida-agent requires a hosted OS process. The GSP image is bare-metal RV64 with its own libos; there is nothing to inject into, and even a hypothetical RISC-V port would need an OS layer the firmware does not have. -**Where the Frida *idea* lives in green-eye:** the scripting model. `Session` +**Where the Frida *idea* lives in risc-v-gsp-rm-debugger:** the scripting model. `Session` offers `hook`/`watch`/`memory`/`events` with Python callbacks, which is the part of Frida that matters for this workflow. The difference is transport: RSP to QEMU instead of an injected agent. @@ -24,23 +24,23 @@ guest today. ## 2. GDB / gdbstub QEMU's gdbstub is the transport both tools share. GDB itself is still useful -for *debugging green-eye* (stub behaviour, protocol traces), and `gdb +for *debugging risc-v-gsp-rm-debugger* (stub behaviour, protocol traces), and `gdb -multiarch` can inspect the same target interactively. It is not the instrumentation layer here because: * every operation becomes a subprocess/parse problem instead of an API call; * recording, symbol annotation, structure decoding and session diffing would have to be rebuilt around GDB/MI anyway; -* the project already uses GDB Python scripts for the CUDA corpus; green-eye +* the project already uses GDB Python scripts for the CUDA corpus; risc-v-gsp-rm-debugger is the equivalent for firmware, with a stronger data model. ## 3. QEMU TCG plugins The correct complement, not a competitor: plugins execute inside QEMU and can observe **every** instruction and memory access, which gdbstub breakpoints -cannot. green-eye's `qemu/greeneye_trace.c` emits a JSONL access trace for +cannot. risc-v-gsp-rm-debugger's `qemu/greeneye_trace.c` emits a JSONL access trace for exactly this; integrating it into the session format is R4 on the roadmap. -Rule of thumb: use green-eye hooks for semantics ("handler X ran with these +Rule of thumb: use risc-v-gsp-rm-debugger hooks for semantics ("handler X ran with these args") and TCG plugins for coverage/heatmaps ("every write to this window"). ## 4. Unicorn / emulator libraries @@ -55,17 +55,17 @@ reason the roadmap defers that work. `rr` does not support RISC-V guests and records at the host-process level. QEMU's own record/replay (`-icount`) can provide deterministic reruns later; -green-eye's session recording occupies a different niche (semantic events, +risc-v-gsp-rm-debugger's session recording occupies a different niche (semantic events, not full replay) and can coexist. ## 6. Comparison table -| Tool | Layer | RISC-V firmware | green-eye relationship | +| Tool | Layer | RISC-V firmware | risc-v-gsp-rm-debugger relationship | |---|---|---|---| | Frida | userland process injection | no | conceptual model only | -| GDB + gdbstub | execution control | yes (transport) | debugging green-eye; same stub | +| GDB + gdbstub | execution control | yes (transport) | debugging risc-v-gsp-rm-debugger; same stub | | QEMU TCG plugin | full instruction/memory trace | yes | complement (R4) | -| green-eye | semantic instrumentation + recording + analysis | yes | this tool | +| risc-v-gsp-rm-debugger | semantic instrumentation + recording + analysis | yes | this tool | | Unicorn/rv8/etc. | CPU emulation library | yes | R2 candidate | | Ghidra | static decompilation | yes | symbol/hit bridge (05) | diff --git a/debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md b/debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md index 6ba8d69..db5109c 100644 --- a/debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md +++ b/debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md @@ -9,13 +9,13 @@ The GSP runs a resource manager (RM) as **services**: message handlers, state machines and engines that own objects (devices, address spaces, channels, memory, notifiers) and answer controls. Open-IOV emulates those services; the -long-term goal of green-eye is to let a developer **write, inject, run and +long-term goal of risc-v-gsp-rm-debugger is to let a developer **write, inject, run and debug their own versions of these services** before (or instead of) changing the product emulation. This guide teaches the loop on the demo uproc — which implements the same shape as a GSP service — and maps each step to the future GSP-RM work in -[`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) H1.3. +[`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H1.3. ## 2. Service anatomy @@ -62,7 +62,7 @@ entry points, which is also the interception point). ## 4. Injecting and invoking ```bash -./greeneye.sh inject --service sdk/build/injected_demo.elf \ +./risc-v-gsp-rm-debugger.sh inject --service sdk/build/injected_demo.elf \ --cmd 1 --arg0 0x41 --arg1 0x42 ``` @@ -107,10 +107,9 @@ behaviour before the product emulation implements it. ## 6. Resource surfaces an engine can use -Category map (details are RM-version-specific and tracked privately where -provenance requires it): +Category map (details are RM-version-specific): -| Surface | Purpose | How green-eye helps today | +| Surface | Purpose | How risc-v-gsp-rm-debugger helps today | |---|---|---| | Memory / descriptors | allocate, map, free, register host or vidmem ranges | watchpoints on allocation state; snapshot/diff; schema decode | | Address spaces / page tables | GPU VA translation, mapping updates | hooks on map/unmap routines; memory diffs; TCG trace of accesses | @@ -165,10 +164,10 @@ case 7: ```bash make -C sdk -./greeneye.sh inject --cmd 7 --arg0 0xab --arg1 0xcd +./risc-v-gsp-rm-debugger.sh inject --cmd 7 --arg0 0xab --arg1 0xcd # direct call -> 0xcdab # firmware call -> 0xcdab -./greeneye.sh analyze <printed session dir> # event/hit report +./risc-v-gsp-rm-debugger.sh analyze <printed session dir> # event/hit report ``` ## 10. What comes next (roadmap) diff --git a/debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md b/debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md index 26f1ffb..65ebb1d 100644 --- a/debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md +++ b/debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md @@ -1,7 +1,7 @@ # 12 — Injection SDK specification (v1, demo ABI) > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status and -> [`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) §H1/H3 for the program. +> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) §H1/H3 for the program. ## 1. Goals and non-goals diff --git a/debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md b/debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md index 26e534d..4d45160 100644 --- a/debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md +++ b/debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md @@ -2,7 +2,7 @@ > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. -The bridge lets a GhidraScript drive a live green-eye session: execute the +The bridge lets a GhidraScript drive a live risc-v-gsp-rm-debugger session: execute the target until a point **chosen in the decompiler**, set/clear breakpoints, read memory and registers, make remote calls, and export hit lists back into the Ghidra project. Nothing about the firmware has to be rebuilt or re-hosted to @@ -18,7 +18,7 @@ Ghidra (Java script) ── JSON lines over localhost ──► greeneye gdbridg ```bash # Terminal 1: a live target + bridge (records by default) -./greeneye.sh ghidra --kernel firmware/uproc_demo/build/uproc_demo.elf --bridge-port 7000 +./risc-v-gsp-rm-debugger.sh ghidra --kernel firmware/uproc_demo/build/uproc_demo.elf --bridge-port 7000 # prints: ghidra bridge on 127.0.0.1:7000 # Terminal 2: Ghidra headless, run until the decompiler's address @@ -120,7 +120,7 @@ the decompiler (unit-test style), then inspect memory with ## 5. Address conventions Ghidra shows **program addresses** (e.g. libcuda file vaddr + image base). -green-eye resolves **runtime addresses**. For firmware linked at its load +risc-v-gsp-rm-debugger resolves **runtime addresses**. For firmware linked at its load address these coincide; otherwise export symbols with the right bias (docs/05-GHIDRA-BRIDGE.md) and prefer `resolve(name)` over hardcoded numbers. @@ -140,7 +140,7 @@ address these coincide; otherwise export symbols with the right bias | Symptom | Cause / fix | |---|---| | `Connection refused` | bridge not started, wrong port, or it exited (`close`) | -| `green-eye bridge closed the connection` | the server was stopped or the target session closed | +| `risc-v-gsp-rm-debugger bridge closed the connection` | the server was stopped or the target session closed | | timeout on `run_until` | address not executed; check symbol bias and that the target is not wedged | | empty `hits` | the session was started without recording; use the CLI (records by default) | | Java compile error on script load | Ghidra API drift; the script targets Ghidra 11/12 `GhidraScript` | diff --git a/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md b/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md index fb78265..f5b2568 100644 --- a/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md +++ b/debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md @@ -1,4 +1,4 @@ -# 14 — Firmware adversarial interoperability research guide (green-eye + Ghidra) +# 14 — Firmware adversarial interoperability research guide (risc-v-gsp-rm-debugger + Ghidra) > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. @@ -8,10 +8,10 @@ Open-IOV's hard problem is not writing the GSP emulation once; it is keeping `open-iov-vfio` accurate while the firmware changes underneath it. New GSP images, device pairings and architectures arrive stripped, signed and hardware-coupled, and some actively resist analysis. This guide is the -practical companion to `GREEN-EYE-ROADMAP.md` H4: how to move from "the new +practical companion to `RISC-V-GSP-RM-DEBUGGER-ROADMAP.md` H4: how to move from "the new image does something different" to a reviewed product change with evidence. -Ghidra is the **static map**; green-eye is the **dynamic ground truth**; +Ghidra is the **static map**; risc-v-gsp-rm-debugger is the **dynamic ground truth**; recorded sessions are the **shared evidence**. Recipes use only the v0.1 surface, plus items explicitly labelled roadmap; see also docs/06-ACCURACY.md. @@ -41,16 +41,16 @@ hardware coupling a simulator cannot yet exercise. not proof of dead code. 4. Every claim carries its fidelity level (L0–L3, docs/06) and provenance. -## 3. The joint workflow: Ghidra, green-eye, sessions +## 3. The joint workflow: Ghidra, risc-v-gsp-rm-debugger, sessions ``` question > Ghidra (static): decompile, dispatcher tables, symbols - > green-eye (dynamic): same stimulus, hooks, watchpoints, trace + > risc-v-gsp-rm-debugger (dynamic): same stimulus, hooks, watchpoints, trace > sessions + hits TSV: greeneye compare -> triage -> evidence pack > open-iov-vfio change (with evidence) ``` -| Question | Ghidra answers | green-eye answers | Shared artifact | +| Question | Ghidra answers | risc-v-gsp-rm-debugger answers | Shared artifact | |---|---|---|---| | What is this code? | decompilation, call graph, xrefs | — | symbol DB (docs/05) | | Did it execute here? | hypothesis from xrefs | `bp_hit`/`watch_hit` events | `greeneye_hits.tsv` | @@ -73,22 +73,22 @@ emulation is touched. `addr<TAB>name<TAB>size`, which `symbols export --index` accepts: ```bash - ./greeneye.sh symbols export --index <new-export.tsv> --bias 0 -o symbols-new.json - ./greeneye.sh symbols export --index <old-export.tsv> --bias 0 -o symbols-old.json + ./risc-v-gsp-rm-debugger.sh symbols export --index <new-export.tsv> --bias 0 -o symbols-new.json + ./risc-v-gsp-rm-debugger.sh symbols export --index <old-export.tsv> --bias 0 -o symbols-old.json ``` 2. Probe each image for first-touch structure changes (docs/07 P1.2): ```bash - ./greeneye.sh probe <old.fwimage> --symbols symbols-old.json --record - ./greeneye.sh probe <new.fwimage> --symbols symbols-new.json --record + ./risc-v-gsp-rm-debugger.sh probe <old.fwimage> --symbols symbols-old.json --record + ./risc-v-gsp-rm-debugger.sh probe <new.fwimage> --symbols symbols-new.json --record ``` 3. Run the **same stimulus** against the re-hosted build of each version. Put it in a script so it is identical across runs: ```python - # run_stimulus.py -- ./greeneye.sh run run_stimulus.py --kernel <rehosted.elf> + # run_stimulus.py -- ./risc-v-gsp-rm-debugger.sh run run_stimulus.py --kernel <rehosted.elf> import greeneye as ge s = ge.launch(kernel="<rehosted.elf>", record=True, name="stim") ctrl = s.symbols.lookup("<control-symbol>") # demo: gsp_ctrl @@ -109,7 +109,7 @@ emulation is touched. delta and written-page delta: ```bash - ./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols ``` 5. Triage with a decision table rather than intuition: @@ -134,7 +134,7 @@ with the capability model the emulation assumes. 1. Instrument the object ranges the service owns (kinds `w`, `r`, `a`): ```python - # capability_probe.py -- ./greeneye.sh run capability_probe.py --kernel <elf> + # capability_probe.py -- ./risc-v-gsp-rm-debugger.sh run capability_probe.py --kernel <elf> import greeneye as ge s = ge.launch(kernel="<rehosted.elf>", record=True, name="caps") base = s.symbols.lookup("<object-symbol>") @@ -155,7 +155,7 @@ with the capability model the emulation assumes. -serial file:/tmp/uart.log -bios none -kernel <rehosted.elf> -S \ -gdb tcp:127.0.0.1:4444 \ -plugin qemu/greeneye-trace.so,path=/tmp/ge-trace.jsonl,start=0x80000000,end=0x81000000,exec=on - ./greeneye.sh attach --port 4444 --kernel <rehosted.elf> --plugin <capability-plugin.py> + ./risc-v-gsp-rm-debugger.sh attach --port 4444 --kernel <rehosted.elf> --plugin <capability-plugin.py> ``` `start=`/`end=` bound the trace, `exec=on` adds per-instruction records and @@ -183,7 +183,7 @@ roadmap R5; until then, bounded mutation over existing primitives is honest. 1. Mutate single fields deterministically and record each attempt: ```python - # mutate.py -- ./greeneye.sh run mutate.py --kernel <rehosted.elf> + # mutate.py -- ./risc-v-gsp-rm-debugger.sh run mutate.py --kernel <rehosted.elf> import greeneye as ge s = ge.launch(kernel="<rehosted.elf>", record=True, name="mutate") ctrl = s.symbols.lookup("<control-symbol>") @@ -205,12 +205,12 @@ roadmap R5; until then, bounded mutation over existing primitives is honest. ``` 3. Capture error paths with hooks/watchpoints on the dispatcher, fault - handlers and assert sites (symbol DB); `./greeneye.sh demo` records a trap. + handlers and assert sites (symbol DB); `./risc-v-gsp-rm-debugger.sh demo` records a trap. 4. Compare clean vs mutated sessions, keeping the mutation value in a `note` so the pack is self-describing: ```bash - ./greeneye.sh compare dumps/<clean-run> dumps/<mutated-run> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<clean-run> dumps/<mutated-run> --symbols ``` Every corpus entry needs the firmware hash; never run mutation against @@ -225,7 +225,7 @@ timing or integrity state, or contains bogus code paths. require the comparison to be empty: ```bash - ./greeneye.sh compare dumps/<run1> dumps/<run2> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<run1> dumps/<run2> --symbols ``` Any delta is a non-determinism candidate (scheduler, uninitialised read, time); record it. @@ -284,7 +284,7 @@ Goal: measure, not narrate. The contract is the M1–M6 table from docs/06: Procedure: (1) capture the reference on hardware/VFIO (docs/07 P4); (2) capture the simulator side with `record`/scripted `run`, hooks, watchpoints and -snapshots; (3) `./greeneye.sh compare dumps/<reference-dir> dumps/<greeneye-dir> +snapshots; (3) `./risc-v-gsp-rm-debugger.sh compare dumps/<reference-dir> dumps/<greeneye-dir> --symbols`, with a script or plugin for per-control M2/M3 payload events; (4) repeat with the injected-service path to test the service boundary; (5) escalate — divergence that would change emulation behaviour must be @@ -293,7 +293,7 @@ reproduced physically; simulator-only divergence becomes a fidelity gap. ### 4.6 From observation to reimplementation The canonical accuracy loop (roadmap H4.5): (1) observe on hardware/VFIO; -(2) observe in green-eye (replayable session); (3) `compare` + M1–M6; +(2) observe in risc-v-gsp-rm-debugger (replayable session); (3) `compare` + M1–M6; (4) implement in `open-iov-vfio` with the session directories attached as evidence; (5) re-run the same stimulus and require the metric table to improve or stay equal. @@ -307,7 +307,7 @@ changed; decoy or low-fidelity observations never justify a product change. Start the live bridge and drive it from the decompiler: ```bash -./greeneye.sh ghidra --kernel <rehosted.elf> --bridge-port 7000 +./risc-v-gsp-rm-debugger.sh ghidra --kernel <rehosted.elf> --bridge-port 7000 $GHIDRA/support/analyzeHeadless <proj> <name> -process <program> -noanalysis \ -scriptPath debug/risc-v-gsp-rm-vm/ghidra \ -postScript GreenEyeControl.java 7000 0x<decompiler-address> @@ -320,13 +320,13 @@ the bridge (`watch_set`) without a Java wrapper: `send("watch_set", {...})`. Address conventions and bias pitfalls (docs/05 §1): -* Ghidra shows **program addresses**; green-eye resolves **runtime addresses**. +* Ghidra shows **program addresses**; risc-v-gsp-rm-debugger resolves **runtime addresses**. For firmware linked at its load address they coincide; otherwise supply `--bias` when building the symbol DB (`ExportForGreenEye.java` emits program addresses). * The classic mistake is passing a program address to `hook()` when the image base is non-zero; prefer `s.hook("<name>")` and pass raw numbers through - `resolve`. `decompiled_index.tsv` carries both spaces; green-eye keeps the + `resolve`. `decompiled_index.tsv` carries both spaces; risc-v-gsp-rm-debugger keeps the program address in `symbol.extras["program_addr"]` for `bucket:line` mapping. * Wrapper-generated functions are re-laid-out between versions: transfer names, never raw wrapper addresses (docs/05 §6). diff --git a/debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md b/debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md index 79d17b8..1a4c62f 100644 --- a/debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md +++ b/debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md @@ -1,10 +1,10 @@ -# 15 — green-eye as an agentic integrated development, analysis and debugging environment for the GPU System Processor +# 15 — risc-v-gsp-rm-debugger as an agentic integrated development, analysis and debugging environment for the GPU System Processor > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. ## 1. Vision and what "agentic" means here -green-eye already has the two properties that make an agent loop possible: +risc-v-gsp-rm-debugger already has the two properties that make an agent loop possible: a **deterministic, scriptable harness** (`ge.launch`/`ge.attach`, `Session`, `record`, `compare`) and a **durable evidence format** (the session directory). "Agentic" here means: @@ -27,7 +27,7 @@ hooks that would make a full agent platform real. ``` +-------------------- agents (triage / hypothesis / RE / portability) ----+ | | - | CLI: ./greeneye.sh info|demo|run|attach|launch|probe|record|analyze| | + | CLI: ./risc-v-gsp-rm-debugger.sh info|demo|run|attach|launch|probe|record|analyze| | | compare|symbols|plugins|inject|ghidra | | Python: ge.launch/attach, Session.*, memory.*, symbols.*, structs, | | probes, plugins, ghidra.export_hits, inject.* | @@ -55,11 +55,11 @@ primitive: it turns two sessions into hit/watch/write deltas. Format ### 2.2 Surfaces an agent may use -* `./greeneye.sh …` — the stable CLI (all real subcommands listed above). -* `./greeneye.sh run script.py` — the preloaded Python namespace (`ge`, +* `./risc-v-gsp-rm-debugger.sh …` — the stable CLI (all real subcommands listed above). +* `./risc-v-gsp-rm-debugger.sh run script.py` — the preloaded Python namespace (`ge`, `session`/`s`, `memory`, `symbols`, `recorder`) makes a harness file the unit of automation. -* `./greeneye.sh ghidra` + `GreenEyeControl.java` — JSON-lines bridge for the +* `./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java` — JSON-lines bridge for the decompiler loop (`run_until`, `bp_set`, `read_mem`, `call`, `hits`, `export_hits`; protocol in docs/13 §3). * Plugins — the extension point (docs/04). A plugin's `register(ge)` can add @@ -103,17 +103,17 @@ Question template: "For control `<X>`, does the firmware set field `<Y>` of the reply/object, and in what order relative to `<Z>`?" 1. Frame it as A/B: the emulation's reply (reference capture, docs/07 P4) and - the firmware's reply in green-eye. One session alone cannot answer it. + the firmware's reply in risc-v-gsp-rm-debugger. One session alone cannot answer it. 2. Resolve the handler and object from the symbol DB; never hardcode: ```bash - ./greeneye.sh symbols resolve --db symbols-<ver>.json <handler-or-addr> + ./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-<ver>.json <handler-or-addr> ``` 3. Capture the firmware side with a hook + before/after snapshots: ```python - # reply_q.py -- ./greeneye.sh run reply_q.py --kernel <rehosted.elf> + # reply_q.py -- ./risc-v-gsp-rm-debugger.sh run reply_q.py --kernel <rehosted.elf> import greeneye as ge from greeneye import Memory @@ -144,7 +144,7 @@ the reply/object, and in what order relative to `<Z>`?" ``` 5. Compare against the reference capture with - `greeneye.analyze.compare_sessions(...)` / `./greeneye.sh compare …` for + `greeneye.analyze.compare_sessions(...)` / `./risc-v-gsp-rm-debugger.sh compare …` for ordering (M3) and state the field diff in words (M2). If the reply is in a different object, repeat step 3 on that object's address. 6. Report: question, session pair, `compare` output, M2/M3 rows, fidelity @@ -158,14 +158,14 @@ the reply/object, and in what order relative to `<Z>`?" $GHIDRA/support/analyzeHeadless <proj> <name> -process <program> -noanalysis \ -scriptPath debug/risc-v-gsp-rm-vm/ghidra \ -postScript ExportForGreenEye.java /tmp/symbols-<ver>.tsv - ./greeneye.sh symbols export --index /tmp/symbols-<ver>.tsv --bias 0 -o symbols-<ver>.json + ./risc-v-gsp-rm-debugger.sh symbols export --index /tmp/symbols-<ver>.tsv --bias 0 -o symbols-<ver>.json diff <(cut -f2 /tmp/symbols-old.tsv | sort) <(cut -f2 /tmp/symbols-new.tsv | sort) ``` 2. Probe the new image for early structure changes: ```bash - ./greeneye.sh probe <new.fwimage> --symbols symbols-<ver>.json --record + ./risc-v-gsp-rm-debugger.sh probe <new.fwimage> --symbols symbols-<ver>.json --record ``` 3. Record the same stimulus against each version. Hook the old handler name; @@ -175,8 +175,8 @@ the reply/object, and in what order relative to `<Z>`?" 4. Compare the sessions: ```bash - ./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols - ./greeneye.sh analyze dumps/<new-run> --symbols symbols-<ver>.json --out new.md + ./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols + ./risc-v-gsp-rm-debugger.sh analyze dumps/<new-run> --symbols symbols-<ver>.json --out new.md ``` 5. Classify the disappearance with the table below, then confirm in Ghidra: @@ -188,7 +188,7 @@ the reply/object, and in what order relative to `<Z>`?" | old function exists, zero hits under the standard stimulus | coverage gap or decoy | widen stimulus, check xrefs from the dispatch table | | dispatch table entry changed but code identical | behaviour moved (state/input) | inspect the table with bridge `read_mem`/snapshot | -6. With the bridge running (`./greeneye.sh ghidra --kernel <elf>`), execute +6. With the bridge running (`./risc-v-gsp-rm-debugger.sh ghidra --kernel <elf>`), execute until the dispatch site from the decompiler and set breakpoints: ```bash @@ -200,7 +200,7 @@ the reply/object, and in what order relative to `<Z>`?" 7. Export hits and annotate the old function's fate: ```bash - ./greeneye.sh analyze dumps/<new-run> --symbols symbols-<ver>.json --out new.md + ./risc-v-gsp-rm-debugger.sh analyze dumps/<new-run> --symbols symbols-<ver>.json --out new.md python3 - <<'PY' from greeneye.ghidra import export_hits from greeneye.symbols import SymbolDB @@ -225,7 +225,7 @@ the reply/object, and in what order relative to `<Z>`?" mailbox dispatch): ```bash - ./greeneye.sh inject --service sdk/build/injected_demo.elf \ + ./risc-v-gsp-rm-debugger.sh inject --service sdk/build/injected_demo.elf \ --cmd 1 --arg0 0x41 --arg1 0x42 ``` @@ -244,7 +244,7 @@ the reply/object, and in what order relative to `<Z>`?" 5. Compare two versions of the service to see the behavioural delta: ```bash - ./greeneye.sh compare dumps/<svc-v1> dumps/<svc-v2> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<svc-v1> dumps/<svc-v2> --symbols ``` 6. Stop condition: direct and firmware-dispatched results agree, the session @@ -257,13 +257,13 @@ the reply/object, and in what order relative to `<Z>`?" 1. Follow the P1 loop in docs/07-PORTABILITY-PLAYBOOKS.md with real commands: ```bash - ./greeneye.sh probe <old.fwimage> --symbols symbols-old.json --record - ./greeneye.sh probe <new.fwimage> --symbols symbols-new.json --record - ./greeneye.sh record --kernel <rehosted-old.elf> --duration 2.0 \ + ./risc-v-gsp-rm-debugger.sh probe <old.fwimage> --symbols symbols-old.json --record + ./risc-v-gsp-rm-debugger.sh probe <new.fwimage> --symbols symbols-new.json --record + ./risc-v-gsp-rm-debugger.sh record --kernel <rehosted-old.elf> --duration 2.0 \ --watch gsp_ctrl+0x10:8 --snapshot gsp_ctrl:392 - ./greeneye.sh record --kernel <rehosted-new.elf> --duration 2.0 \ + ./risc-v-gsp-rm-debugger.sh record --kernel <rehosted-new.elf> --duration 2.0 \ --watch gsp_ctrl+0x10:8 --snapshot gsp_ctrl:392 - ./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols ``` 2. Keep the stimulus identical across versions: use one script/probe spec and diff --git a/debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md b/debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md index 2f99f7b..a842368 100644 --- a/debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md +++ b/debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md @@ -4,10 +4,10 @@ ## 1. Purpose and status -This document is the design and delivery plan for a green-eye-native execution +This document is the design and delivery plan for a risc-v-gsp-rm-debugger-native execution backend: a small deterministic RISC-V machine (`libgreenmachine`) implementing the same `Session` contract as today's QEMU backend. It expands -`GREEN-EYE-ROADMAP.md` §H3 (H3.1–H3.4) and the §H6 soft-processor annex. +`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md` §H3 (H3.1–H3.4) and the §H6 soft-processor annex. **Beyond M1.5 (§1.1), nothing here exists yet.** The only production backend is `QemuTarget` + `RspClient` (`greeneye/target.py`, `greeneye/rsp.py`); M2+ of @@ -93,13 +93,13 @@ plugin and without leaving the process: ### 1.2 Usage ```bash -./greeneye.sh demo --backend native # the canned demo, native backend -./greeneye.sh run examples/scripts/trace_rpc.py --backend native -printf 'bp rpc_sum\nc 0.2\nquit\n' | ./greeneye.sh attach --backend native -./greeneye.sh record --backend native --trace --duration 0.5 -./greeneye.sh record --backend native --trace --trace-exec off \ +./risc-v-gsp-rm-debugger.sh demo --backend native # the canned demo, native backend +./risc-v-gsp-rm-debugger.sh run examples/scripts/trace_rpc.py --backend native +printf 'bp rpc_sum\nc 0.2\nquit\n' | ./risc-v-gsp-rm-debugger.sh attach --backend native +./risc-v-gsp-rm-debugger.sh record --backend native --trace --duration 0.5 +./risc-v-gsp-rm-debugger.sh record --backend native --trace --trace-exec off \ --trace-start 0x80000000 --trace-end 0x80010000 -./greeneye.sh analyze dumps/<stamp>-record # renders the trace coverage section +./risc-v-gsp-rm-debugger.sh analyze dumps/<stamp>-record # renders the trace coverage section python3 examples/scripts/sim_bench.py --trace # throughput + trace overhead python3 examples/scripts/sim_diff.py # QEMU/native profile diff ``` @@ -126,7 +126,7 @@ QEMU is an excellent execution engine and a poor *workflow* engine here. The limits below are consequences of QEMU being a whole-board emulator with a GDB stub as its scriptable surface; each maps to a §H3.1 requirement. -| QEMU property | Consequence for green-eye | Requirement it forces | +| QEMU property | Consequence for risc-v-gsp-rm-debugger | Requirement it forces | |---|---|---| | RSP serialises every access (hex frame, TCP round-trip, `PacketSize` chunking) | register/memory polling and watchpoint step-over are transport-bound; full-access tracing is impractical | in-process backend ABI with direct memory/register calls | | No cheap machine snapshots; `savevm` is board-level and not exposed over the stub | region snapshots are copied over RSP; no instant checkpoint exists | copy-on-write full-machine snapshot/restore | @@ -185,7 +185,7 @@ The control plane is unchanged: `Session`, hooks, watchpoints, `Memory`, bridge sit above a backend interface. The §H3.2 sketch becomes: ``` -+-------------------- green-eye Python control plane --------------------+ ++-------------------- risc-v-gsp-rm-debugger Python control plane --------------------+ | Session API, hooks/watchpoints, recorder, plugins, Ghidra/agent bridge | +---------------------------- Backend interface -------------------------+ | QEMU-RSP backend (today) | native backend (planned) diff --git a/debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md b/debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md index 59db437..effacb0 100644 --- a/debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md +++ b/debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md @@ -14,7 +14,7 @@ metrics in [06-ACCURACY](06-ACCURACY.md) need the real host RM as a reference: and engine inventory at a moment in time. `rmharness` packages the host-side oracle tools and wires their output into -green-eye sessions, so a simulator/emulation session and a host RM capture +risc-v-gsp-rm-debugger sessions, so a simulator/emulation session and a host RM capture can be recorded, diffed and cited together. It is the host half of the accuracy loop (H4.5), not a boot path or a replacement for PLAN B traces. @@ -67,7 +67,7 @@ access model as `nvidia-smi` and is safe alongside a running CUDA job. maps to the RM `deviceId`; `--device PATH` overrides the `/dev/nvidiaN` node. -## 5. green-eye integration +## 5. risc-v-gsp-rm-debugger integration Wrappers `rmharness/rmtool.sh`, `rmharness/rmtop.sh`, `rmharness/rmq.sh` locate and build the tools and pass arguments through. `rmharness/harness.sh` @@ -137,12 +137,12 @@ migrations, MIG or a second GPU. * **docs/06-ACCURACY** — recorded `rm_harness_run` blobs are the host reference for M1/M6; keep the JSON captures in the session directories cited by the metric table. -* **GREEN-EYE-ROADMAP H3** — the custom simulator's device map and RM-core +* **RISC-V-GSP-RM-DEBUGGER-ROADMAP H3** — the custom simulator's device map and RM-core interception need real control semantics (IDs, sizes, status values) to validate against; `rmtool` supplies that inventory before the H2.2 boot is reached, and the shared `rm_api.c` can become the simulator's host-RM client for differential tests. -* **GREEN-EYE-ROADMAP H4.5** — the canonical observe -> compare -> implement +* **RISC-V-GSP-RM-DEBUGGER-ROADMAP H4.5** — the canonical observe -> compare -> implement loop can now include a host capture (`harness.sh --session`) beside the simulator session, giving every emulation change an evidence pair. * **R4 (full-memory trace)** — the session-event schema already carries diff --git a/debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md b/debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md index ecd0614..4fbe4d9 100644 --- a/debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md +++ b/debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md @@ -45,7 +45,7 @@ python3 harness/portability_matrix.py \ --out dumps/matrix-570 ``` -Replacing the builtin scenario with a fixed green-eye script: +Replacing the builtin scenario with a fixed risc-v-gsp-rm-debugger script: ```bash python3 harness/portability_matrix.py --target <rehosted.elf> \ diff --git a/debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md b/debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md index 0f9afbe..67ef556 100644 --- a/debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md +++ b/debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md @@ -1,7 +1,7 @@ # 19 — Control discovery and hot-path reachability > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status and -> [`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) H4 for the program. +> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H4 for the program. Two harness tools close the loop between "a new firmware image does something we do not model" and "here is the code path, its trigger and its effects": @@ -14,7 +14,7 @@ we do not model" and "here is the code path, its trigger and its effects": Both are simulator-only, bounded, evidence-producing, and depend only on the public `Session`/hook/watch primitives (stdlib-only Python). They are the practical start of the "Sandsifter for RM" idea in -[`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) H4 and reuse the contracts +[`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H4 and reuse the contracts in [06-ACCURACY](06-ACCURACY.md) and [14-ADVERSARIAL-INTEROP-GUIDE](14-ADVERSARIAL-INTEROP-GUIDE.md). --- @@ -235,7 +235,7 @@ Flags: `--method auto|stimulus|trigger|run|call`, `--all-methods`, `--args`, `auto` tries methods in this order and stops at the first hit (use `--all-methods` to compare routes): -1. `stimulus` — run a green-eye script (or a probe spec's stimulus) with the +1. `stimulus` — run a risc-v-gsp-rm-debugger script (or a probe spec's stimulus) with the target hook and watchpoints armed. The script drives `session.run` itself. 2. `trigger` — read the surface's handler table, find the command ID(s) that resolve to the target, settle the firmware, apply that command and run diff --git a/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md b/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md index a3b6111..dbfbb36 100644 --- a/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md +++ b/debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md @@ -1,12 +1,12 @@ -# 20 — MCP server (green-eye agent interface) +# 20 — MCP server (risc-v-gsp-rm-debugger agent interface) > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. ## 1. What it is -`plugins/mcp_server.py` is the green-eye **MCP (Model Context Protocol) +`plugins/mcp_server.py` is the risc-v-gsp-rm-debugger **MCP (Model Context Protocol) server** — roadmap [`R3`](08-ROADMAP.md#r3-mcp-server-plugin) and -[`H7`](../GREEN-EYE-ROADMAP.md). It exposes the *active* `Session` as MCP +[`H7`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). It exposes the *active* `Session` as MCP tools so an AI agent (Claude Code, opencode, any MCP client) can inspect symbols, set breakpoints/watchpoints, run the target, read memory, snapshot, analyse/compare recordings, inject services, and drive the harnesses. @@ -14,7 +14,7 @@ analyse/compare recordings, inject services, and drive the harnesses. * **Stdlib-only**: JSON-RPC 2.0 over newline-delimited stdin/stdout, no MCP library, no network listener unless explicitly asked. * **Plugin first**: `register(ge)` adds an `mcp-serve` REPL/CLI command that - serves the session already loaded by green-eye. + serves the session already loaded by risc-v-gsp-rm-debugger. * **Standalone too**: the same file runs as a script that launches its own session (`--kernel`, `--backend`, `--record`) and then serves MCP. * **Read-only by default**: memory writes, remote calls and injection require @@ -24,7 +24,7 @@ analyse/compare recordings, inject services, and drive the harnesses. `not_available` tool error when the module/file is absent instead of crashing. The tool list always advertises every capability. -The core green-eye package is untouched; everything lives in the plugin. +The core risc-v-gsp-rm-debugger package is untouched; everything lives in the plugin. ## 2. Running it @@ -54,11 +54,11 @@ Logs go to stderr; **stdout carries protocol frames only**. ### 2.2 Plugin mode (serve a live session) ```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 \ --plugin plugins/mcp_server.py -greeneye> mcp-serve # read/observe -greeneye> mcp-serve --allow-write # + memory writes / remote calls -greeneye> mcp-serve --allow-inject # + service injection +risc-v-gsp-rm-debugger> mcp-serve # read/observe +risc-v-gsp-rm-debugger> mcp-serve --allow-write # + memory writes / remote calls +risc-v-gsp-rm-debugger> mcp-serve --allow-inject # + service injection ``` `mcp-serve` blocks until the MCP client disconnects or calls the `close` @@ -80,7 +80,7 @@ client configs use standalone mode. Use absolute paths. ```json { "mcpServers": { - "green-eye": { + "risc-v-gsp-rm-debugger": { "command": "python3", "args": [ "/home/rmcore/Git/integdev_gpu_drv/open-iov/debug/risc-v-gsp-rm-vm/plugins/mcp_server.py", @@ -94,7 +94,7 @@ client configs use standalone mode. Use absolute paths. } ``` -Or, one line: `claude mcp add green-eye -- python3 +Or, one line: `claude mcp add risc-v-gsp-rm-debugger -- python3 <tool-root>/plugins/mcp_server.py --stdio --record`. ### 3.2 opencode (`opencode.json`) @@ -103,7 +103,7 @@ Or, one line: `claude mcp add green-eye -- python3 { "$schema": "https://opencode.ai/config.json", "mcp": { - "green-eye": { + "risc-v-gsp-rm-debugger": { "type": "local", "command": [ "python3", @@ -227,7 +227,7 @@ recorded, and the session can be compared like any other run. 2. **No guest, no hardware.** The server drives the simulator/QEMU session only. It does not touch `/dev`, a kernel module, an mdev, a guest or a physical GPU; the agent runs against the simulator by default - ([H7](../GREEN-EYE-ROADMAP.md), [15-AGENTIC-GSP-IDE](15-AGENTIC-GSP-IDE.md) §5). + ([H7](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md), [15-AGENTIC-GSP-IDE](15-AGENTIC-GSP-IDE.md) §5). 3. **Read-only by default.** `--allow-write` enables `write_mem` and `call_function`; `--allow-inject` enables `inject_service`. The agent's client config decides which manifest class it gets; a read/observe agent is diff --git a/debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md b/debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md index aa71b54..d4d7680 100644 --- a/debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md +++ b/debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md @@ -13,7 +13,7 @@ playbook into one repeatable run and one attachable bundle: | `harness/version_diff.py` | old vs new target, section by section: image/shape, symbol inventory, decompiled corpus hints, bounded QEMU probe, shared-scenario behavior, M1–M6 skeleton | | `harness/ci_release.py` | runs version_diff → portability matrix → mutation smoke and hashes every artifact into `bundle-manifest.json` | -`.github/workflows/greeneye.yml` runs the tool's test suite on pushes/PRs that +`.github/workflows/risc-v-gsp-rm-debugger.yml` runs the tool's test suite on pushes/PRs that touch `debug/risc-v-gsp-rm-vm/**` or `tools/rm*/**`. The repository-level `.github/workflows/ci.yml` is independent and unchanged. @@ -65,7 +65,7 @@ section then reports `skipped` with a reason unless Ghidra/JSON sources are supplied. Flags: `--old/--new` (required), `--out` (required), `--old-label/--new-label/ ---release`, `--old-symbols/--new-symbols` (green-eye JSON), `--old-ghidra-names`, +--release`, `--old-symbols/--new-symbols` (risc-v-gsp-rm-debugger JSON), `--old-ghidra-names`, `--new-ghidra-names`, `--old-ghidra-index`, `--new-ghidra-index`, `--old-ghidra-exports`, `--new-ghidra-exports` (`--old-ghidra-bias`/ `--new-ghidra-bias`), `--corpus-diff OLD NEW`, `--corpus-report FILE`, @@ -84,7 +84,7 @@ never aborts the others. A failing QEMU probe or scenario is recorded as 2. **Symbol inventory.** ELF `.symtab` plus Ghidra `names.tsv`, `decompiled_index.tsv`/bucket TSVs, 4-column `exports.tsv` and the 3-column `ExportForGreenEye` form (`addr<TAB>name<TAB>size`), plus - green-eye `greeneye-symbols/1` JSON DBs. Matching follows + risc-v-gsp-rm-debugger `greeneye-symbols/1` JSON DBs. Matching follows `userspace/cuda/tools/diff_corpus.py`: named functions match by name (duplicates in address order), the address shift is the median of named deltas, and `FUN_*` functions match at the shifted address. The report @@ -240,7 +240,7 @@ the docs/14 §6 pack; the docs/23 §4 step 7 expected-artifact list maps 1:1. ## 5. CI workflow -`.github/workflows/greeneye.yml` (new; `ci.yml` is untouched): +`.github/workflows/risc-v-gsp-rm-debugger.yml` (new; `ci.yml` is untouched): * triggers on push/PR paths `debug/risc-v-gsp-rm-vm/**` and `tools/rm*/**`; * `ubuntu-latest`, no secrets, no hardware; diff --git a/debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md b/debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md index ad8a5e7..d92c0f0 100644 --- a/debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md +++ b/debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md @@ -1,8 +1,8 @@ -# 22 — Porting with green-eye: CUDA userspace, GSP firmware and new GPU devices +# 22 — Porting with risc-v-gsp-rm-debugger: CUDA userspace, GSP firmware and new GPU devices > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00-OVERVIEW for status. > This is the combined porting guide for the three churn axes the project -> faces. It joins the existing CUDA/GSP/firmware procedures with green-eye's +> faces. It joins the existing CUDA/GSP/firmware procedures with risc-v-gsp-rm-debugger's > runtime layer. Items marked "planned (docs/xx)" do not exist yet; do not > invent commands for them. @@ -68,19 +68,19 @@ tools/cudatool.py delta <old>/run/libcuda.so.<old> <new>/run/libcuda.so.<new> ### 2.2 Static analysis vs dynamic confirmation -| Step | Existing project tooling | green-eye addition | +| Step | Existing project tooling | risc-v-gsp-rm-debugger addition | |---|---|---| | Export/interface diff | `tools/cudatool.py delta` | — | | Function matching / name-transfer measurement | `tools/cudatool.py fdematch <old-lib> <new-lib> --names <names.tsv>` | — | | Corpus-level diff (added/removed/resized functions) | `tools/diff_corpus.py <old_index> <new_index>` | — | -| Name transfer + corpus annotation | `ApplyNameMap.java` (`--dry-run` first), `tools/annotate_corpus.py` | `./greeneye.sh symbols export` builds a runtime-address symbol DB from the same index/names | -| Driver-API smoke | `tools/test/cuda_drv_test.c` compiled as `/tmp/cdt` (prints `ALL OK`) | `./greeneye.sh symbols resolve --db ... <addr>` spot-checks transferred addresses per call path | -| Runtime workload | `tools/cuda-ab/ab.sh all` (`vector_add.cu`; `RESULT`/`STATUS` must match host) | session-format evidence and `./greeneye.sh compare` when firmware-side sessions exist | +| Name transfer + corpus annotation | `ApplyNameMap.java` (`--dry-run` first), `tools/annotate_corpus.py` | `./risc-v-gsp-rm-debugger.sh symbols export` builds a runtime-address symbol DB from the same index/names | +| Driver-API smoke | `tools/test/cuda_drv_test.c` compiled as `/tmp/cdt` (prints `ALL OK`) | `./risc-v-gsp-rm-debugger.sh symbols resolve --db ... <addr>` spot-checks transferred addresses per call path | +| Runtime workload | `tools/cuda-ab/ab.sh all` (`vector_add.cu`; `RESULT`/`STATUS` must match host) | session-format evidence and `./risc-v-gsp-rm-debugger.sh compare` when firmware-side sessions exist | | Guest-side control observation | `tools/guest-diag/ioctl_trace.c`, host module trace (`gsp-resman-vfio:`) | annotation of the firmware-side RPC path with the per-version symbol DB | -| Firmware-side confirmation | — | `./greeneye.sh probe` / `record` / `compare` against the paired firmware | +| Firmware-side confirmation | — | `./risc-v-gsp-rm-debugger.sh probe` / `record` / `compare` against the paired firmware | **Be honest about the execution boundary.** `cdt` and `vectorAdd` are x86_64 -guest binaries; the RISC-V simulator does not execute them. green-eye's +guest binaries; the RISC-V simulator does not execute them. risc-v-gsp-rm-debugger's contribution to a userspace port is the **symbol/evidence layer**: a runtime-address DB per `libcuda` version, per-address resolution checks for transferred names, and a recorded comparison format for the GSP-side behaviour @@ -109,17 +109,17 @@ remains the dynamic oracle. 5. **Transfer names and knowledge.** Apply the map with `ApplyNameMap.java` `--dry-run` first, then for real; translate the subsystem index; re-validate entries the delta marked as moved. -6. **Build the green-eye symbol DB** for the new version so runtime addresses +6. **Build the risc-v-gsp-rm-debugger symbol DB** for the new version so runtime addresses resolve: ```bash cd debug/risc-v-gsp-rm-vm - ./greeneye.sh symbols export \ + ./risc-v-gsp-rm-debugger.sh symbols export \ --names ../../userspace/cuda/<new>/annotations/names.tsv \ --index ../../userspace/cuda/<new>/run/analysis/decompiled/decompiled_index.tsv \ --callgraph ../../userspace/cuda/<new>/run/analysis/elf-index/callgraph.tsv \ --bias 0x100000 -o symbols-<new>.json - ./greeneye.sh symbols resolve --db symbols-<new>.json 0x<transferred-addr> + ./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-<new>.json 0x<transferred-addr> ``` `--bias 0x100000` is the Ghidra image base convention for `libcuda` @@ -143,7 +143,7 @@ remains the dynamic oracle. side is recorded, use the session compare primitive: ```bash - ./greeneye.sh compare dumps/<old-fw-run> dumps/<new-fw-run> --symbols + ./risc-v-gsp-rm-debugger.sh compare dumps/<old-fw-run> dumps/<new-fw-run> --symbols ``` For multi-target orchestration use the portability matrix (docs/18); note @@ -205,9 +205,9 @@ the top of the evidence pack. ### 3.3 Probe first-touch diff and symbol inventory ```bash -./greeneye.sh symbols export --index <new-export.tsv> --bias 0 -o symbols-<new>.json -./greeneye.sh probe <new-fwimage> --symbols symbols-<new>.json --record -./greeneye.sh probe <reference-fwimage> --symbols symbols-<ref>.json --record +./risc-v-gsp-rm-debugger.sh symbols export --index <new-export.tsv> --bias 0 -o symbols-<new>.json +./risc-v-gsp-rm-debugger.sh probe <new-fwimage> --symbols symbols-<new>.json --record +./risc-v-gsp-rm-debugger.sh probe <reference-fwimage> --symbols symbols-<ref>.json --record ``` The probe loads the segments, runs bounded and reports the first divergence @@ -253,7 +253,7 @@ The project's support ladder is `docs/06-portability/hardware-software-matrix.md ### 3.6 aarch64 host / GB10-class design notes -* **Host tooling** — green-eye is Python + QEMU; on aarch64 install +* **Host tooling** — risc-v-gsp-rm-debugger is Python + QEMU; on aarch64 install `qemu-system-misc` (provides `qemu-system-riscv64`) and the same commands run. Keep host-specific paths out of session metadata (docs/07 P3.5). `GREENEYE_QEMU` is the existing escape hatch if the binary lives elsewhere. diff --git a/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md b/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md index 72e0e62..7d18678 100644 --- a/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md +++ b/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md @@ -18,7 +18,7 @@ thing the approval message must acknowledge. | No acquisition | No 610 runfile, GSP `.fwimage`, driver package or firmware blob is fetched, extracted, copied or mirrored before approval. | | No analysis | No decompilation, symbol export, probe, corpus diff or pairing comparison against a 610 image before approval. | | No emulation edits | No version-keyed handler, signature entry or profile edit justified by "610" before approval; changes require current-version evidence. | -| No physical-GPU work | No unsupervised physical-GPU cycle, mdev claim or driver bind/unbind for 610; the project rule is no unattended physical-GPU cycles (GREEN-EYE-ROADMAP H7). | +| No physical-GPU work | No unsupervised physical-GPU cycle, mdev claim or driver bind/unbind for 610; the project rule is no unattended physical-GPU cycles (RISC-V-GSP-RM-DEBUGGER-ROADMAP H7). | | No support claims | 610 is not entered in the hardware/software matrix or the version matrix until it passes the docs/22 port checklists with evidence. | Precision notes: @@ -55,7 +55,7 @@ closed. |---|---|---|---|---| | C1 | All tools implemented and tested on the current driver/firmware | full test suites green (documents/demo/probe/inject/Ghidra/harness) | test logs attached to the request | tools implemented (docs/00); fresh full-suite run pending | | C2 | Tests green | `make test` and the harness/rmharness suites pass | transcript with date and commit | green at v0.1; re-run pending (155 tests, docs/27) | -| C3 | Demo, probe, inject, Ghidra work | `./greeneye.sh demo`, `probe`, `inject`, `ghidra` all demonstrated | session dirs + transcript | working per docs/00 | +| C3 | Demo, probe, inject, Ghidra work | `./risc-v-gsp-rm-debugger.sh demo`, `probe`, `inject`, `ghidra` all demonstrated | session dirs + transcript | working per docs/00 | | C4 | MCP monitoring works | MCP plugin implemented and exercised (roadmap R3, docs/08; docs/15) | tool list + a monitored run | implemented (docs/20); monitored run not yet attached | | C5 | CI pipeline works | release/CI pipeline implemented and exercised (docs/21) | pipeline run with artifacts | implemented (docs/21); current-version run pending | | C6 | Docs complete and accurate | doc review checklist (§3.2) signed | review record | to complete | @@ -78,14 +78,14 @@ make demo make test python3 -m unittest tests.test_harness -v python3 rmharness/tests/test_rmharness_plugin.py -./greeneye.sh info -./greeneye.sh demo -./greeneye.sh demo --backend native -./greeneye.sh probe -./greeneye.sh inject -./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json -./greeneye.sh analyze dumps/<run> --symbols symbols-<ver>.json -./greeneye.sh compare dumps/<a> dumps/<b> --symbols +./risc-v-gsp-rm-debugger.sh info +./risc-v-gsp-rm-debugger.sh demo +./risc-v-gsp-rm-debugger.sh demo --backend native +./risc-v-gsp-rm-debugger.sh probe +./risc-v-gsp-rm-debugger.sh inject +./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json +./risc-v-gsp-rm-debugger.sh analyze dumps/<run> --symbols symbols-<ver>.json +./risc-v-gsp-rm-debugger.sh compare dumps/<a> dumps/<b> --symbols ``` Plus, on the current version: @@ -120,8 +120,8 @@ Required results: current version, or C7 is explicitly waived; * [ ] `docs/21-CI-RELEASE-PIPELINE.md` exists and has run once on the current version, or C5 is explicitly waived; -* [ ] `GREEN-EYE-ROADMAP.md` and `docs/08` status claims match reality; -* [ ] no local source paths, no invented command names, no unsupported +* [ ] `RISC-V-GSP-RM-DEBUGGER-ROADMAP.md` and `docs/08` status claims match reality; +* [ ] no non-public source paths, no invented command names, no unsupported "supported/accurate" claims. ### 3.3 Golden sessions and regression data in place diff --git a/debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md b/debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md index 4430bf9..0dde6a8 100644 --- a/debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md +++ b/debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md @@ -62,7 +62,7 @@ absorbed; a read of a write-only register reads back zero. ```bash # 1) run a bounded probe against the real image (QEMU path, existing command) -./greeneye.sh probe # writes dumps/<stamp>-probe-<image>/ +./risc-v-gsp-rm-debugger.sh probe # writes dumps/<stamp>-probe-<image>/ # 2) turn that session into a device map python3 -m greeneye.device_map harvest dumps/<stamp>-probe-<image> \ diff --git a/debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md b/debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md index d47b8ea..3409039 100644 --- a/debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md +++ b/debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md @@ -9,7 +9,7 @@ ## 1. Why this document exists -green-eye is only worth its maintenance if it turns real firmware questions +risc-v-gsp-rm-debugger is only worth its maintenance if it turns real firmware questions into answers faster than static analysis and supervised hardware cycles. The project handoffs record those questions and their costs in wall-clock and cycles: the 0x59 RM-init chase (PART 91, 2026-10-01), the 20 GR counters @@ -17,7 +17,7 @@ cycles: the 0x59 RM-init chase (PART 91, 2026-10-01), the 20 GR counters P6 service wiring (PART 92 ADDENDA 5–11, 2026-10-02), and the version pairing question (570.144 vs 570.211). This document maps each of them to a runnable demonstration under [`harness/value_demos/`](../harness/value_demos/), states -the baseline cost from the handoffs, and measures the green-eye path. +the baseline cost from the handoffs, and measures the risc-v-gsp-rm-debugger path. ## 2. Methodology @@ -25,14 +25,14 @@ the baseline cost from the handoffs, and measures the green-eye path. | Class | Meaning | Where it appears | |---|---|---| -| **Measured (analog)** | Wall-clock of the green-eye path on the bundled `uproc_demo` firmware, native RV64 interpreter or QEMU; answers, counts, session bytes, trace slowdown | `result.json` per demo, `artifacts/results.json` | +| **Measured (analog)** | Wall-clock of the risc-v-gsp-rm-debugger path on the bundled `uproc_demo` firmware, native RV64 interpreter or QEMU; answers, counts, session bytes, trace slowdown | `result.json` per demo, `artifacts/results.json` | | **Recorded (real baseline)** | Cost actually paid on the physical path, as recorded in the handoffs (dates, cycles, PARTs, wall spans) | `real_case.static_baseline` in each `result.json`, §5 below | | **Projected** | What the same tool path would save on the real firmware once H2.2 executes it; labelled `projected` | `real_case.projection`; never presented as a result | | **Blocked** | Real firmware access requires the H2.2 QEMU device model; `blocked_on_device_model: true` | every real `.fwimage` scenario here | Fidelity is exactly docs/06: L0 instruction semantics and L1 memory behaviour are exercised; **L2 time/concurrency is not modelled** and **L3 device -environment is absent**. A green-eye observation is evidence about the +environment is absent**. A risc-v-gsp-rm-debugger observation is evidence about the firmware, and anything that would change `open-iov-vfio` is escalated to a physical capture before the product changes (docs/06 §6, docs/14 §7). @@ -76,7 +76,7 @@ Measured on the reference host (CPython 3.12); numbers regenerate with `python3 harness/value_demos/run_all.py`. Times below are from the `run_all` aggregate (~18.4 s total). -| # | Real scenario (source, date) | Green-eye tool | Static/Ghidra-only baseline (recorded) | Analog (measured) | Real-case projection | +| # | Real scenario (source, date) | Risc-V GSP-RM debugger tool | Static/Ghidra-only baseline (recorded) | Analog (measured) | Real-case projection | |---|---|---|---|---|---| | s01 | 0x59 RM-init chase; fn72/fn73 (PART 91 + ADDENDA 2–7, 2026-10-01) | hook dispatcher, watch `result`, decode reply | cycles 2–13, ~11:40→16:52 ≈ 5 h 10 m; 10+ supervised boots (~5–6 min each); reply was generic `0x59` | **1.14 s**; 3/3 commands consumed and decoded; FAULT traps before the reply store | one hook + one watchpoint per command once H2.2 boots the image (blocked) | | s02 | 20 GR per-channel counters (PARTs 46–64, 2026-09-24…29) | watch publication field, per-slot readback | ~5 days; PART 49 “only 4 of 20 counters ever moved”; ~2–3 s pin vs ~2 s client deadline | **1.34 s**; 20/20 slots published, 28 stores, store PCs captured | per-channel page watchpoints on real counter pages (blocked) | @@ -280,7 +280,7 @@ every later version. ## 7. OODA-loop compression -| Stage | Before (real path, as recorded) | After (green-eye analog, measured) | +| Stage | Before (real path, as recorded) | After (risc-v-gsp-rm-debugger analog, measured) | |---|---|---| | **Observe** | one supervised boot + capture per hypothesis: 5–6 min, fail-safe discipline, one device-write experiment per cycle | launch 0.001–0.13 s, then hooks/watchpoints and bounded runs: 0.2–5.8 s per question | | **Orient** | manual LOGINIT/LOGRM/NOCAT ring decode, static reports (REPORT3–10), hours per campaign; the ring was invisible until cycle 11 | `analyze`/`compare`/`Memory.diff` with named symbols: seconds, e.g. s05 attributes every changed byte to a schema field | @@ -288,7 +288,7 @@ every later version. | **Act** | rebuild + supervised boot; escalate every conclusion to a physical capture | re-run the session (seconds); product change still gated on physical confirmation (docs/06 §6, docs/14 §7) | The compression is not “the simulator replaces the hardware”; it is the loop -around each physical experiment. green-eye reduces the number of physical +around each physical experiment. risc-v-gsp-rm-debugger reduces the number of physical cycles needed to reach a confident hypothesis and produces the evidence pack that makes the eventual physical confirmation cheap (s10). diff --git a/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md b/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md index ab8414a..d8c30dd 100644 --- a/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md +++ b/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md @@ -1,14 +1,14 @@ -# 26 — green-eye architecture: full picture, workflow and API surfaces +# 26 — risc-v-gsp-rm-debugger architecture: full picture, workflow and API surfaces > **# TOOL IN DEVELOPMENT - NOT READY YET!** -> The architecture map for the green-eye suite: how the pieces fit, which +> The architecture map for the risc-v-gsp-rm-debugger suite: how the pieces fit, which > surface to call, and which document specifies each part. Every claim here is > implemented in the tree or explicitly marked as a gated roadmap design. > Development-only: never shipped, never a driver dependency, never in a guest. -## 1. What green-eye is (and is not) +## 1. What risc-v-gsp-rm-debugger is (and is not) -green-eye runs GSP/uproc firmware in a controllable machine, observes it with +risc-v-gsp-rm-debugger runs GSP/uproc firmware in a controllable machine, observes it with Frida-like primitives, records a durable session, changes the machine's inputs (including injected code), and compares runs as evidence for `open-iov-vfio` emulation changes. @@ -224,7 +224,7 @@ sequenceDiagram | `greeneye.ghidra.export_hits` | session hits → `addr<TAB>hits<TAB>symbol<TAB>annotation` | 05 | | `ExportForGreenEye.java` | Ghidra → `addr<TAB>name<TAB>size` TSV | 05 | | `MarkGreenEyeHits.java` | annotate functions with runtime hits + bookmarks | 05 | -| `GreenEyeControl.java` + `greeneye.sh ghidra` | drive a live session from GhidraScripts over localhost JSON-lines | [13](13-GHIDRA-CONTROL.md) | +| `GreenEyeControl.java` + `risc-v-gsp-rm-debugger.sh ghidra` | drive a live session from GhidraScripts over localhost JSON-lines | [13](13-GHIDRA-CONTROL.md) | Bridge commands: `ping`, `info`, `resolve`, `bp_set`, `bp_clear`, `bp_list`, `watch_set`, `run_until`, `run`, `step`, `read_mem`, `write_mem`, `read_reg`, @@ -343,7 +343,7 @@ The canonical loop (H4.5, 06 §5, 07 P4, 25 §7). Each stage names its gate. | 5. Compare | `compare` against a reference (old firmware, hardware/VFIO capture, self-diff) | deltas explained symbolically; self-diff is zero | unexplained hit/watch/write delta → investigate first | | 6. Decide | fill M1–M6 with the reference method (06 §5); mutation/triage for error paths | metric table improves or stays equal | metric claimed without a reference capture | | 7. Implement | change `open-iov-vfio` (never the simulator for a product fix); keep the stimulus | physical confirmation for behaviour changes (06 §6, 14 §7) | product change from a simulator-only observation | -| 8. Regression | re-run step 3 with an unchanged stimulus; golden sessions/CI (`make test`, `greeneye.yml`) | profile improves or stays equal; CI green | regression → revert and re-derive | +| 8. Regression | re-run step 3 with an unchanged stimulus; golden sessions/CI (`make test`, `risc-v-gsp-rm-debugger.yml`) | profile improves or stays equal; CI green | regression → revert and re-derive | ```mermaid flowchart LR @@ -358,12 +358,12 @@ flowchart LR ``` OODA compression evidence (analog, measured) is in 25 §7: hardware cycles are -minutes and campaigns hours/days; the green-eye path for the same question +minutes and campaigns hours/days; the risc-v-gsp-rm-debugger path for the same question class is sub-second to seconds plus scripting. ## 12. API surfaces by tool -### 12.1 CLI (`greeneye.sh`, `greeneye/cli.py`; usage in [02](02-USAGE.md)) +### 12.1 CLI (`risc-v-gsp-rm-debugger.sh`, `greeneye/cli.py`; usage in [02](02-USAGE.md)) | Command | Purpose | Not for | |---|---|---| @@ -447,7 +447,7 @@ dispatch (01, 03); §4 backends (01 §8, 16 §4–5); §5 recording (01 §6, 09, §6, 16 §10, 17 §5); §6 injection (11, 12); §7 Ghidra (05, 13); §8 MCP (20); §9 harness (18, 19, 21, 28, 29); §10 device map (24, 16 §7); §11 OODA (06, 07 P4, 25 §7). Roadmap keys: R3 = MCP (08), R5 = mutation (18), R6 = multi-version (18, -21), H1.3 = RM service injection (GREEN-EYE-ROADMAP), H2.2 = QEMU device +21), H1.3 = RM service injection (RISC-V-GSP-RM-DEBUGGER-ROADMAP), H2.2 = QEMU device model, H3/M1–M6 = native simulator (16), H4 = adversarial navigation (14), H7 = agentic platform (15, 20). diff --git a/debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md b/debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md index 86f2b06..9c4f61e 100644 --- a/debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md +++ b/debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md @@ -1,4 +1,4 @@ -# 27 — green-eye tool audit +# 27 — risc-v-gsp-rm-debugger tool audit > **# TOOL IN DEVELOPMENT - NOT READY YET!** See [00-OVERVIEW](00-OVERVIEW.md) > for status and [06-ACCURACY](06-ACCURACY.md) for fidelity limits. @@ -17,7 +17,7 @@ Environment: QEMU 8.2.2 (`qemu-system-riscv64`), Python 3.12, clang/lld. Every safe smoke below was executed from the tool root; device/WPR paths were not touched. -* all 13 `./greeneye.sh <cmd> --help` parsers, `--version`; +* all 13 `./risc-v-gsp-rm-debugger.sh <cmd> --help` parsers, `--version`; * `info`, `demo --backend native`, `record --backend native --trace`, `analyze`, `compare`, `plugins`, `inject --backend native`; * `probe --instructions 400` against the real 570.144 `.fwimage`; @@ -44,11 +44,11 @@ tests/demos/docs), `not used yet` (no caller found; decision recorded), `needs improvement` (concrete weakness; fixed where safe), `prune candidate` (clearly dead; none found). -## 1. Master table — `greeneye.sh` CLI +## 1. Master table — `risc-v-gsp-rm-debugger.sh` CLI | surface | purpose | API / entry points | tests | used by | status | notes/actions | |---|---|---|---|---|---|---| -| `info` | environment/tooling check | `greeneye/cli.py:173`, `greeneye.sh info` | indirect (smoke) | README, 00, 02 | verified useful | ran; native sim + fwimage + CUDA names detection all correct | +| `info` | environment/tooling check | `greeneye/cli.py:173`, `risc-v-gsp-rm-debugger.sh info` | indirect (smoke) | README, 00, 02 | verified useful | ran; native sim + fwimage + CUDA names detection all correct | | `demo` | canned demo boot + hooks/watch/diff/trap | `cli.py:209` | smoke via `test_smoke_qemu.py` | README, 00, 02; `make demo-run` | verified useful | ran on `--backend native`; 17 hook lines, diff + trap work | | `run` | run a Python instrumentation script | `cli.py:272` | `test_injection.py` (REPL), `test_sim_trace.py` | 02, 03, examples scripts | needs improvement (fixed) | the exec namespace lacked `__file__`, so the documented `dump_diff.py` failed; namespace now sets `__file__`/`__name__`, doc 03 notes it | | `attach` | interactive REPL | `cli.py:486`, `GreenEyeRepl` | `test_injection.py:68` | README, 02 | verified useful | REPL commands all back onto tested Session APIs | @@ -105,21 +105,21 @@ tests/demos/docs), `not used yet` (no caller found; decision recorded), | `plugins/mcp_server.py` | MCP server (stdio/loopback) | `--stdio`, `--tcp`, `--allow-write`, `--allow-inject` | `test_mcp.py` (431 lines) | 08/R3, 15, 20 | verified useful | read-only default; structured `not_available` fallbacks | | `plugins/rmharness_plugin.py` | REPL commands for host RM oracle | `register(ge)`; commands `rmtool/rmtop/rmq` | `rmharness/tests/test_rmharness_plugin.py` (3 tests) | 17, 23 | verified useful | write-named args refused (`rm_harness_skip`) | | `qemu/greeneye_trace.c` | full TCG exec/access JSONL trace | `make -C qemu`; `-plugin greeneye-trace.so,path=…` | none automated; **live-verified in this audit** | 10, 16, 14 | verified useful | 8M exec events in 1 s on the demo; vendored `qemu-plugin.h` builds out of the box | -| `qemu/launch.sh` | one-line `greeneye launch` wrapper | `qemu/launch.sh --kernel <elf>` | smoke | qemu/README | verified useful | thin `exec` of `greeneye.sh launch` | +| `qemu/launch.sh` | one-line `greeneye launch` wrapper | `qemu/launch.sh --kernel <elf>` | smoke | qemu/README | verified useful | thin `exec` of `risc-v-gsp-rm-debugger.sh launch` | | `ghidra/*.java` (Export/Mark/Control) | static/dynamic join inside Ghidra | `analyzeHeadless -postScript …` | protocol counterpart covered by `test_bridge.py`; no Ghidra installed here | 05, 13 | verified useful (static) | README documents exact command lines; Java not executed in this environment | | `rmharness/rmtool.sh` | RM oracle wrapper | passthrough to `tools/rmtool` | `harness.sh` capture smoke (`gpu list`) | 17, 23 | verified useful | builds tool on first use; read-only | | `rmharness/rmtop.sh` | dashboard wrapper | passthrough to `tools/rmtop` | `--help` | 17 | verified useful | `--once` for captures | | `rmharness/rmq.sh` | pre-existing rmq wrapper | passthrough to `tools/rmq` | `--help` | 17 | needs improvement (fixed) | `--help` used to fall through and open the RM; wrapper now answers help itself | -| `rmharness/harness.sh` | capture tool run into a green-eye session | `--session DIR -- TOOL ARGS` | capture smoke (verified event + blobs) | 17, 22 | verified useful | additive recording; read-only allowlist enforced | +| `rmharness/harness.sh` | capture tool run into a risc-v-gsp-rm-debugger session | `--session DIR -- TOOL ARGS` | capture smoke (verified event + blobs) | 17, 22 | verified useful | additive recording; read-only allowlist enforced | | `rmharness/tests/` | plugin registration check | `python3 rmharness/tests/test_rmharness_plugin.py` | 3 tests, run and green | 17 | needs improvement (open) | not part of `tests/` discovery nor CI; kept separate by design, documented in 17/README — consider CI step when the workflow is next edited | | `sdk/injected_demo.c` | position-independent service SDK | `make sdk` | `test_injection.py`; `inject` smoke | 11, 12 | verified useful | direct + firmware call paths | | `firmware/uproc_demo/` | bundled RV64 uproc (mailbox RPC/state/trap) | `make demo` | many integration tests | README, 00, 02 | verified useful | self-test + scripted stimulus work | -| `examples/scripts/dump_diff.py` | schema decode + snapshot diff demo | `./greeneye.sh run examples/scripts/dump_diff.py` | verified after `__file__` fix | 02 | needs improvement (fixed) | was broken by the `run` namespace gap; now prints decoded ctrl + changed bytes | -| `examples/scripts/trace_rpc.py` | hook every RPC handler | `./greeneye.sh run …` | ran | 02, 16, 18 | verified useful | 17 hook events from the demo | +| `examples/scripts/dump_diff.py` | schema decode + snapshot diff demo | `./risc-v-gsp-rm-debugger.sh run examples/scripts/dump_diff.py` | verified after `__file__` fix | 02 | needs improvement (fixed) | was broken by the `run` namespace gap; now prints decoded ctrl + changed bytes | +| `examples/scripts/trace_rpc.py` | hook every RPC handler | `./risc-v-gsp-rm-debugger.sh run …` | ran | 02, 16, 18 | verified useful | 17 hook events from the demo | | `examples/scripts/sim_bench.py` | native throughput benchmark | standalone CLI | ran (0.92 MIPS untraced, pure Python) | 16 | verified useful | self-bootstraps `sys.path`, works from anywhere | | `examples/scripts/sim_diff.py` | QEMU-vs-native differential | standalone CLI | ran: `PARITY: OK` | 16 | verified useful | exit 1 on divergence, 0 on skip | | `examples/probes/demo_probes.json` | declarative probe spec sample | loaded by `greeneye.probes.install` | installed + fired via `greeneye run` | 03 §9 | verified useful | 3 probes, hits `[1, 3, 0]` on the demo | -| `tests/` (15 files) | unit + live QEMU integration | `python3 -m unittest discover -s tests -t .` | **155 tests OK** | CI (`greeneye.yml`) | verified useful | includes live QEMU, native parity, MCP, bridge, harness, value demos | +| `tests/` (15 files) | unit + live QEMU integration | `python3 -m unittest discover -s tests -t .` | **155 tests OK** | CI (`risc-v-gsp-rm-debugger.yml`) | verified useful | includes live QEMU, native parity, MCP, bridge, harness, value demos | ## 4. Scripting API purpose review @@ -177,7 +177,7 @@ Nothing was deleted. ## 7. Portability / extensibility / discoverability checks -* **Portability.** Stdlib-only Python; `greeneye.sh` pins `PYTHONPATH` to the +* **Portability.** Stdlib-only Python; `risc-v-gsp-rm-debugger.sh` pins `PYTHONPATH` to the tool root. Harness tools and `run_all.py` bootstrap their own `sys.path`. QEMU is optional (integration tests skip cleanly); the native backend makes the suite largely hardware-free. `qemu-plugin.h` is vendored so the TCG @@ -188,17 +188,17 @@ Nothing was deleted. (`greeneye-device-map/1`, doc 24). * **Discoverability.** `README.md` + `docs/00-OVERVIEW.md` doc maps were completed for docs 17–27 (previously they stopped at 16); `plugins/` and - `harness/` are now listed in the README layout. `greeneye.sh --help` and + `harness/` are now listed in the README layout. `risc-v-gsp-rm-debugger.sh --help` and `plugins/mcp_server.py --help` are self-describing. -* **CI.** `.github/workflows/greeneye.yml` builds SDK+demo and runs the main +* **CI.** `.github/workflows/risc-v-gsp-rm-debugger.yml` builds SDK+demo and runs the main suite on Linux; `rmharness/tests` is the only suite the workflow misses. ## 8. How to tell if a tool is misbehaving (symptom → check → fix) | tool | symptom | check | fix | |---|---|---|---| -| `greeneye.sh` / CLI | `greeneye error: …` on a valid path | `./greeneye.sh info` shows resolved paths; `--help` for arguments | correct the path/arg; check `GREENEYE_QEMU`/`GREENEYE_DUMPS`; bad symbol DBs now fail with a clear message | -| `run` scripts | `NameError: __file__` (pre-fix) or names missing | `./greeneye.sh run` preloads `ge/session/s/memory/symbols/recorder/__file__`; run with `--backend native` to remove QEMU | keep scripts inside the tool tree and invoke through `greeneye.sh run`, not bare `python3` | +| `risc-v-gsp-rm-debugger.sh` / CLI | `greeneye error: …` on a valid path | `./risc-v-gsp-rm-debugger.sh info` shows resolved paths; `--help` for arguments | correct the path/arg; check `GREENEYE_QEMU`/`GREENEYE_DUMPS`; bad symbol DBs now fail with a clear message | +| `run` scripts | `NameError: __file__` (pre-fix) or names missing | `./risc-v-gsp-rm-debugger.sh run` preloads `ge/session/s/memory/symbols/recorder/__file__`; run with `--backend native` to remove QEMU | keep scripts inside the tool tree and invoke through `risc-v-gsp-rm-debugger.sh run`, not bare `python3` | | hooks/watchpoints | callback never fires | hook an obviously-hit symbol (`rpc_sum`), `record` + `analyze`; check the session event counts | re-run demo to confirm firmware self-test; ensure the target is resumed (`run`) and the symbol exists (`symbols.get`) | | `probe` | 0 faults reported | check `dumps/<run>/blobs/qemu.log` and `recorder.meta["qemu_fault_count"]` | expected for images that stay in mapped memory; use `--instructions` for a bounded step instead of `--duration` | | native backend / trace | QEMU-vs-native diff fails | `python3 examples/scripts/sim_diff.py`; `analyze` on the trace blob | divergence means a real backend bug: capture both sessions and diff `exec`/`access` counts (see 16) | diff --git a/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md b/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md index 4669f93..f75c8ed 100644 --- a/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md +++ b/debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md @@ -1,7 +1,7 @@ # 28 — Porting automation: driver-version sweep and new-device scaffold > **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status and -> [`GREEN-EYE-ROADMAP.md`](../GREEN-EYE-ROADMAP.md) H4/R6 for the program. +> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H4/R6 for the program. Two stdlib-only orchestrators turn the docs/07 P1/P2 playbooks and the docs/22 porting guide into one repeatable chain: a **driver-version sweep** @@ -228,7 +228,7 @@ Output tree: <out>/<device>/ device-port.json / device-port.md port-checklist.json / port-checklist.md - symbols/<device>.json merged ELF/Ghidra/green-eye DB + provenance + symbols/<device>.json merged ELF/Ghidra/risc-v-gsp-rm-debugger DB + provenance sessions/<firmware>-probe/ recorded first-touch session portability-matrix/ matrix report + sessions + compare bundle-manifest.json sha256 of every artifact diff --git a/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md b/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md index 8be3704..c87806b 100644 --- a/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md +++ b/debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md @@ -8,7 +8,7 @@ ## 1. Purpose -green-eye can already load an injected service into the native simulator and +risc-v-gsp-rm-debugger can already load an injected service into the native simulator and invoke it (docs/12, docs/16 §1.1, `harness/value_demos/s06_inject_service.py`). That evidence lives in the tool tree: a reviewer needs the checkout, the built demo and SDK, and the exact command sequence. `harness/package_sim.py` turns @@ -111,7 +111,7 @@ not overwrite. 1. Receive `<package>.tar.gz` plus its sha256 out of band; verify `sha256sum <package>.tar.gz`. 2. Extract and run: `./run.sh` (add `--budget N` for image packages). The - script finds the green-eye tree by walking up, or via + script finds the risc-v-gsp-rm-debugger tree by walking up, or via `GREENEYE_HOME=/path/to/risc-v-gsp-rm-vm`. Exit codes: `0` pass (or the documented blocked image status), `1` assertion failure, `3` tree not found. 3. Read `results/results.md` first, then `results/results.json` for machines. @@ -119,7 +119,7 @@ not overwrite. flake: `assertions.failed` names the check (`handlers_slot_registered`, `remote_ping`, `routes_agree`, `dispatch_hook_hits`, `uart_banner`, ...). 4. For deeper review, point the tools at `results/session/`: - `./greeneye.sh analyze <pkg>/results/session` and + `./risc-v-gsp-rm-debugger.sh analyze <pkg>/results/session` and `python3 -m greeneye compare baseline/results/session candidate/results/session`. 5. Verify provenance: each `components[].sha256` must match the packaged file; `target.sha256`/`service.sha256` identify the inputs. |