diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md | 28 |
1 files changed, 14 insertions, 14 deletions
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) | |