From 14cf2aa59c44a50f9a108b93d58c7cecab17d45f Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 12:41:52 -0400 Subject: debug: risc-v-gsp-rm-debugger final pass - remove in-development notices, complete rename, adversarial-review fixes Remove the '# TOOL IN DEVELOPMENT - NOT READY YET!' notices from the tool docs/README/scripts and the project docs; record the removal (2026-10-02) against the tool audit (debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md), the 194-test suite and the value-validation demos (docs/25-VALUE-VALIDATION.md). Complete the cosmetic rename to risc-v-gsp-rm-debugger in user-facing prose and commands (launcher, roadmap, docs); internal greeneye package and code identifiers unchanged. Adversarial-review fixes: deterministic control-discovery sweep (flaky test root-caused), UUID session dirs + atomic JSON writes for concurrent runs, Ghidra bridge loopback enforcement and clean shutdown, fp register restore in Session.call, version_diff --dry-run, 30 s interrupt budget, dry-run non-destructiveness verified. Docs: flag-removal records, link fixes, command/flag corrections (fdematch arity, port_new_device --out, trace filename), F2 orchestration note in future-eng-ops; STATE-CURRENT status refreshed. --- debug/risc-v-gsp-rm-vm/README.md | 2 +- .../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md | 12 ++++++------ debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md | 12 ++++++++++-- debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/02-USAGE.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md | 2 +- debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md | 8 ++++---- .../docs/07-PORTABILITY-PLAYBOOKS.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md | 3 +-- .../risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md | 5 ----- debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md | 2 +- .../docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md | 11 +++++------ debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md | 4 ++-- .../docs/14-ADVERSARIAL-INTEROP-GUIDE.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md | 13 ++++++------- debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md | 4 ++-- .../risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md | 8 ++++---- .../risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md | 2 +- .../docs/21-CI-RELEASE-PIPELINE.md | 2 +- .../docs/22-PORTING-CUDA-AND-DEVICES.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md | 6 +++--- debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md | 4 ++-- debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md | 14 +++++++------- debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md | 14 +++++++------- .../risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md | 4 ++-- .../docs/29-PACKAGING-AND-TRIALING.md | 4 ++-- debug/risc-v-gsp-rm-vm/ghidra/README.md | 2 +- debug/risc-v-gsp-rm-vm/greeneye/record.py | 7 ++++++- .../risc-v-gsp-rm-vm/harness/control_discovery.py | 2 +- debug/risc-v-gsp-rm-vm/harness/mutation_harness.py | 2 +- .../harness/port_driver_versions.py | 4 ++-- debug/risc-v-gsp-rm-vm/harness/port_new_device.py | 4 ++-- .../risc-v-gsp-rm-vm/harness/portability_matrix.py | 2 +- debug/risc-v-gsp-rm-vm/harness/reach.py | 2 +- .../harness/value_demos/_common.py | 16 +++++++++++++++- .../harness/value_demos/s06_inject_service.py | 5 +++-- .../harness/value_demos/s07_version_diff.py | 6 ++++-- .../value_demos/s09_grabbing_a_ghidra_address.py | 8 +++++--- .../value_demos/s10_full_session_evidence.py | 22 ++++++++++++---------- debug/risc-v-gsp-rm-vm/harness/version_diff.py | 2 +- debug/risc-v-gsp-rm-vm/qemu/README.md | 2 +- debug/risc-v-gsp-rm-vm/qemu/launch.sh | 2 +- debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh | 2 +- debug/risc-v-gsp-rm-vm/tests/test_discovery.py | 2 +- 50 files changed, 154 insertions(+), 128 deletions(-) (limited to 'debug/risc-v-gsp-rm-vm') diff --git a/debug/risc-v-gsp-rm-vm/README.md b/debug/risc-v-gsp-rm-vm/README.md index a1e4b9b..8882f9a 100644 --- a/debug/risc-v-gsp-rm-vm/README.md +++ b/debug/risc-v-gsp-rm-vm/README.md @@ -1,6 +1,6 @@ # risc-v-gsp-rm-debugger — GSP runtime analysis in a RISC-V QEMU VM -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > Experimental tooling for simulating and inspecting the GSP firmware's > runtime memory, for `gsp-rm-vfio` accuracy measurements and GSP/uproc > reverse engineering. It is a development-only, out-of-tree tool: never a diff --git a/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md b/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md index 26f586f..88183ea 100644 --- a/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md +++ b/debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md @@ -1,6 +1,6 @@ # RISC-V GSP-RM DEBUGGER ROADMAP — long-term program -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This is the long-term plan for risc-v-gsp-rm-debugger, the runtime analysis, injection and > measurement environment for the NVIDIA GPU System Processor (GSP) and its > adjacent microcontrollers. Near-term, committed work lives in @@ -33,7 +33,7 @@ v0.1 (2026-10-02) provides: GDB-free QEMU RISC-V transport; hooks, breakpoints, watchpoints; memory/struct/snapshot tooling; recorded sessions and symbol-annotated analysis; declarative probes; plugins; a Ghidra symbol and hit bridge; a Ghidra control bridge; a TCG full-trace plugin; a -position-independent service SDK and `greeneye inject`; and the Frida-like +position-independent service SDK and `./risc-v-gsp-rm-debugger.sh inject`; and the Frida-like `Session.call` / `run_until` primitives. Fidelity is L0/L1 (execution and memory); the device environment (L3) is absent. @@ -88,7 +88,7 @@ Exit: an injected service serves a control end-to-end and its session can be diffed against hardware. ### H1.4 Ghidra-driven execution (deliverable today, demo-proven) -`greeneye ghidra` + `GreenEyeControl.java` (docs/13): "run until here", set +`./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java` (docs/13): "run until here", set breakpoints, read memory/registers, remote-call, export hits. Next increments: * watchpoints and structure reads from Ghidra; @@ -217,7 +217,7 @@ reimplement quickly. * Import each firmware's Ghidra corpus and risc-v-gsp-rm-debugger symbol DB; diff RPC dispatch tables, handler inventory, control sets, message layouts. * Run the same stimulus harness against each version and use - `greeneye compare` for hit/watch/write deltas; automatically flag functions + `./risc-v-gsp-rm-debugger.sh compare` for hit/watch/write deltas; automatically flag functions whose call counts changed but whose static code is unchanged (behaviour moved) vs changed code (new logic). * Produce a "portability delta report" per version (feeds docs/07 playbooks). @@ -352,8 +352,8 @@ compression; session size budgets (region-scoped dumps). ### V6 — Documentation and developer experience Every horizon ships docs with copy-paste workflows, an acceptance script, and -a flag-removal (TOOL IN DEVELOPMENT) criterion; the Ghidra/agent guides are -kept current as first-class deliverables. +a status/flag criterion (the v0.1 notices came off 2026-10-02); the +Ghidra/agent guides are kept current as first-class deliverables. ## Sequencing summary 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 f09d576..a404663 100644 --- a/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md +++ b/debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md @@ -1,6 +1,6 @@ # 00 — risc-v-gsp-rm-debugger overview -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > Experimental tooling for simulating and inspecting the GSP firmware's > runtime memory, for `gsp-rm-vfio` accuracy measurements and GSP/uproc > reverse engineering. Interfaces and file formats may change without notice. @@ -44,7 +44,7 @@ whole stack scriptable, and QEMU is just the first execution backend. | Plugin loader + example plugin | working | | Native RV64IMAC simulator (M1, `--backend native`) | working; QEMU-parity differential test | | Native exec/access trace (M1.5, R4): `--trace`, analyzer coverage | working; trace blob + determinism test | -| Test suite | 155 tests green (live QEMU + native differential included) | +| Test suite | 194 tests green (live QEMU + native differential included) | | Ghidra bridge | scripts + docs | | Real GSP `.fwimage` probe (first-fault report) | working (honest: it does not boot without a TU104 model — see 06) | | TCG full-memory tracing plugin | source + optional build (verified live) | @@ -55,6 +55,14 @@ whole stack scriptable, and QEMU is just the first execution backend. | Porting automation + trial packaging (28/29) | scaffolds + tests present; unadmitted pilots (dry-run default) | | Native M2+ device model | roadmap only (08, 16) | +The in-development notices were removed on 2026-10-02 after the tool audit +([27-TOOL-AUDIT](27-TOOL-AUDIT.md)), the 194-test green suite, and the +end-to-end s01–s10 value demonstrations +([25-VALUE-VALIDATION](25-VALUE-VALIDATION.md)). Open items stay listed as +open: docs 28/29 are unadmitted pilots, the device model and custom simulator +M2+ remain roadmap, and nothing here is a stability guarantee beyond the +audited v0.1 surface. + ## Quick start ```bash 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 034f87c..0e23bcc 100644 --- a/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md +++ b/debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md @@ -1,6 +1,6 @@ # 01 — risc-v-gsp-rm-debugger design -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. Why this shape @@ -151,7 +151,7 @@ declarative so they can come from a Ghidra type export or a plugin later. ## 9. Ghidra bridge -* Out: `greeneye symbols export --names … --index … --exports … --callgraph …` +* Out: `./risc-v-gsp-rm-debugger.sh symbols export --names … --index … --exports … --callgraph …` builds `greeneye-symbols.json` from the project's existing TSV exports. * In: `greeneye.ghidra.export_hits(session_dir, out_tsv)` writes `addrhitssymbol`, and `MarkGreenEyeHits.java` annotates those 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 686d4c9..ceb46ab 100644 --- a/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md +++ b/debug/risc-v-gsp-rm-vm/docs/02-USAGE.md @@ -1,6 +1,6 @@ # 02 — risc-v-gsp-rm-debugger usage -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). All commands are run from `open-iov/debug/risc-v-gsp-rm-vm/`. @@ -140,7 +140,7 @@ See [04-PLUGINS](04-PLUGINS.md). |---|---| | `make demo` | build the demo firmware | | `make test` | build + unit tests + live QEMU smoke | -| `make demo-run` | `greeneye demo --no-build` | +| `make demo-run` | `./risc-v-gsp-rm-debugger.sh demo --no-build` | | `make probe-real` | run the TU104 fwimage probe | | `make plugin` | build the optional TCG plugin | | `make clean` | remove builds, dumps and `__pycache__` | 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 93dfccf..93b9b65 100644 --- a/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md +++ b/debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md @@ -1,6 +1,6 @@ # 03 — risc-v-gsp-rm-debugger scripting -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). risc-v-gsp-rm-debugger scripts are ordinary Python programs run with `./risc-v-gsp-rm-debugger.sh run ` (or `python3 -m greeneye run …`). The @@ -15,7 +15,7 @@ import greeneye as ge # Launch the bundled demo (QEMU -kernel fast path), recording by default. s = ge.launch(kernel="firmware/uproc_demo/build/uproc_demo.elf", record=True, name="my-run") -# Or attach to an already-running gdbstub (e.g. started by `greeneye launch`). +# Or attach to an already-running gdbstub (e.g. started by `risc-v-gsp-rm-debugger.sh launch`). # s = ge.attach(port=4444, record="dumps/attach-run") try: 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 b0e6767..f3ad07d 100644 --- a/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md +++ b/debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md @@ -1,6 +1,6 @@ # 04 — writing risc-v-gsp-rm-debugger plugins -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). A plugin is a Python module exposing `register(ge)`. It is loaded before the session runs (CLI `--plugin PATH`, `GREENEYE_PLUGINS`, or the bundled 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 4f41d33..f7b546c 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 @@ -1,6 +1,6 @@ # 05 — Ghidra bridge -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). 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, @@ -97,7 +97,7 @@ Two practical routes today: name — the most robust route across recompilations. 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. +`./risc-v-gsp-rm-debugger.sh` through its CLI to set breakpoints directly from the tool. ## 6. Limits 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 47854d1..e55162d 100644 --- a/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md +++ b/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md @@ -1,6 +1,6 @@ # 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. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This document is deliberately conservative. Treat every claim without a > recorded A/B as unverified. @@ -43,7 +43,7 @@ windows, a TCM/MPU layout and a PMU-provided environment that `qemu virt` does not have. **Therefore:** loading the raw `.fwimage` into `qemu virt` cannot boot it. -The `greeneye probe` command is designed for exactly this: it loads the +The `./risc-v-gsp-rm-debugger.sh probe` command is designed for exactly this: it loads the segments, runs bounded, and reports the first divergence (`guest_errors,unimp,int` log + stopped PC + symbol). That report is a *memory and control-flow map* of what the firmware tries to touch first — useful data, @@ -92,7 +92,7 @@ Reference capture: `gsp-phys-log-dump`, status-queue drains) and the static-config oracle; * risc-v-gsp-rm-debugger: `events.jsonl` + snapshots, symbol-annotated. -Comparison: `greeneye compare dumps/real- dumps/greeneye- +Comparison: `./risc-v-gsp-rm-debugger.sh compare dumps/real- dumps/greeneye- --symbols`, then a short table of M1–M6 with counts. Never publish a single "accuracy %" number without the metric breakdown. @@ -114,7 +114,7 @@ failure path. The rules: Before trusting a risc-v-gsp-rm-debugger session: -* the demo firmware self-test must pass (`greeneye demo`, `make test`); +* the demo firmware self-test must pass (`./risc-v-gsp-rm-debugger.sh demo`, `make test`); * the session must contain the expected `hook`/`watch` registrations and a coherent `bp_hit` sequence (the analyzer highlights empty sessions); * the UART banner and control-block magic are cheap liveness checks; 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 b0c8c3f..3c0f658 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 @@ -1,6 +1,6 @@ # 07 — Portability playbooks: new GSP, new device, new architecture -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). 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 @@ -37,7 +37,7 @@ emulation is adjusted. build the rehosted subset against the QEMU-virt shim and run the same scripted stimulus used for the previous version. 4. **Baseline + candidate sessions** — for each version capture: - * `greeneye record --kernel --duration N --snapshot ` + * `./risc-v-gsp-rm-debugger.sh record --kernel --duration N --snapshot ` or the scripted harness (`run`), * the real-backend reference traces for the same workload. 5. **Compare** — `./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols`: @@ -106,7 +106,7 @@ real firmware for a chosen workload. vendor logs plus a conversion note). 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 +3. **Compare:** `./risc-v-gsp-rm-debugger.sh compare` for hit/watch/write profiles; for RPC payloads use M2 field agreement and M3 ordering (a small script or a plugin can emit per-control events). 4. **Report:** metric table (M1–M6), changed-function list, and an explicit 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 3a518c4..bab9074 100644 --- a/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md +++ b/debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md @@ -1,6 +1,5 @@ # 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 @@ -33,7 +32,7 @@ preferred vehicle; TCG plugins provide the observation points. measurement (P1.6) requires booting real firmware in-simulator. Until then, use the probe + rehosted uproc paths. -**Exit criteria:** `greeneye probe ` reaches a stable address and +**Exit criteria:** `./risc-v-gsp-rm-debugger.sh probe ` reaches a stable address and reports "waiting for host message" rather than a fault; the first host↔GSP RPC records are captured in a session; M3 ordering can be measured against the physical backend. 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 b930cb9..0e2f788 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,10 +1,5 @@ # 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 -> tracked document intentionally keeps source locations generic and cites -> public material. - ## 1. The microcontrollers around the GPU From the open-iov wiki **GPU Firmware** page and the linked **NVIDIA RISC-V 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 90ca799..8eb7a25 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 @@ -1,6 +1,6 @@ # 10 — related work: why not Frida, and what each tool is for -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. Frida 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 db5109c..2022cf1 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 @@ -1,8 +1,7 @@ # 11 — GSP RM firmware service developer guide -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status and 06 for the -> fidelity caveats. Exact proprietary API names are not reproduced in tracked -> docs; local provenance lives in the local analysis notes. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> See [06-ACCURACY](06-ACCURACY.md) for the fidelity caveats. ## 1. What this guide is for @@ -130,12 +129,12 @@ prototype is analysed exactly like firmware code. 2. **Integration run:** `invoke_via_firmware` with the mailbox path, while hooks on the firmware's dispatcher and watchpoints on the control block record the full route. -3. **Ghidra-driven:** `greeneye ghidra` + `GreenEyeControl.java` — execute +3. **Ghidra-driven:** `./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java` — execute until a service address, set breakpoints from the decompiler, read registers/memory, export hits (docs/13). 4. **Coverage:** run with the TCG plugin filtered to the service load range - (`qemu/greeneye-trace.c`, `start=`/`end=` args) to see every access. -5. **Regression:** record a session per command; `greeneye compare` detects + (`qemu/greeneye_trace.c`, `start=`/`end=` args) to see every access. +5. **Regression:** record a session per command; `./risc-v-gsp-rm-debugger.sh compare` detects changed hit/watch/write profiles when the service or firmware changes. ## 8. Rules and pitfalls 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 65ebb1d..9438179 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 -> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) §H1/H3 for the program. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> See [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) §H1/H3 for the program. ## 1. Goals and non-goals @@ -102,7 +102,7 @@ The injector records, in the session directory: * `qemu.log`-style blobs are not applicable (no probe here), but the TCG trace can be enabled for full coverage. -Comparison of injected-service runs uses the standard `greeneye compare` +Comparison of injected-service runs uses the standard `./risc-v-gsp-rm-debugger.sh compare` profiles, so a change in a service's behaviour is visible like any firmware change. 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 4d45160..368154f 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 @@ -1,6 +1,6 @@ # 13 — Ghidra control bridge -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). 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 @@ -98,7 +98,7 @@ Response: `{"id": , "ok": true, "result": ...}` or ## 4. Workflows ### 4.1 Execute until here -1. Start `greeneye ghidra` on the firmware image and load symbols +1. Start `./risc-v-gsp-rm-debugger.sh ghidra` on the firmware image and load symbols (`symbols export` from the Ghidra index) so hits are named. 2. Put the cursor on a function in Ghidra and run `GreenEyeControl.java`. 3. `runUntilHere()` sets a temporary breakpoint, services intervening stops 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 f5b2568..1ddd17e 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,6 +1,6 @@ # 14 — Firmware adversarial interoperability research guide (risc-v-gsp-rm-debugger + Ghidra) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. Purpose and scope @@ -46,7 +46,7 @@ hardware coupling a simulator cannot yet exercise. ``` question > Ghidra (static): decompile, dispatcher tables, symbols > risc-v-gsp-rm-debugger (dynamic): same stimulus, hooks, watchpoints, trace - > sessions + hits TSV: greeneye compare -> triage -> evidence pack + > sessions + hits TSV: risc-v-gsp-rm-debugger compare -> triage -> evidence pack > open-iov-vfio change (with evidence) ``` @@ -264,7 +264,7 @@ timing or integrity state, or contains bogus code paths. ``` On today's `qemu virt` an unmodelled GPU register faults rather than - returning a value (`greeneye probe` reports that first read, docs/06 §3); + returning a value (`./risc-v-gsp-rm-debugger.sh probe` reports that first read, docs/06 §3); the value-return experiment waits on the H2 device model — log, don't claim. 5. Maintain the catalogue of observed techniques in docs/09-GSP-FIRMWARE-NOTES.md (roadmap H4.4), one session pair per technique. 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 1a4c62f..db71833 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,6 +1,6 @@ # 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. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. Vision and what "agentic" means here @@ -49,7 +49,7 @@ hooks that would make a full agent platform real. | `blobs/*` | plugin/probe dumps (e.g. qemu.log) | forensics | | `summary.md` | rendered report | humans, PR attachments | -`greeneye compare dumps/ dumps/ --symbols` is the primary agent +`./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols` is the primary agent primitive: it turns two sessions into hit/watch/write deltas. Format `greeneye-session/1` evolves additively (roadmap V2). @@ -83,7 +83,7 @@ reviewable evidence. |---|---|---|---|---| | Triage | question + firmware version(s) | `symbols export`, `probe`, `analyze` | delta candidates, prioritised symbol list | every changed symbol classified | | Hypothesis | one behaviour question | `run` scripts, hooks, watchpoints, `compare` | session pair + verdict | delta attributed to one variable | -| RE | decompiled function | `greeneye ghidra`, `run_until`, breakpoints, `export_hits` | hits TSV + annotation, reachability answer | function hit or timeout recorded | +| RE | decompiled function | `./risc-v-gsp-rm-debugger.sh ghidra`, `run_until`, breakpoints, `export_hits` | hits TSV + annotation, reachability answer | function hit or timeout recorded | | Portability | version/device pair | docs/07 playbook, baseline + candidate sessions, M1–M6 | portability report | metric table complete | | Injection | service idea | `sdk/`, `inject`, `load_service`, `invoke_remote`, `invoke_via_firmware` | injected-service session pair | direct and firmware paths agree | | Verification | another agent's finding | golden sessions, `compare`, `analyze` | pass/fail + counterexample | finding reproduced or refuted | 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 a842368..4e96a44 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 @@ -1,6 +1,5 @@ # 16 — Custom simulator: design and implementation plan -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status; this is a -> far-later design, do not implement ahead of the H3 gate. +> This is a far-later design, do not implement ahead of the H3 gate. ## 1. Purpose and status @@ -18,7 +17,7 @@ hoc. This document scopes it. ### 1.1 M1 status (implemented in this tree) M1 was explicitly commissioned and is implemented behind `--backend native`; -the status marker above still applies to the remaining milestones (M2–M6) and +the gating above still applies to the remaining milestones (M2–M6) and to any use on real GSP images. * **What exists.** A pure-Python, stdlib-only RV64IMAC interpreter under @@ -76,9 +75,9 @@ plugin and without leaving the process: `trace` config/counts in the metadata), so it never swamps `events.jsonl`; folded `exec`/`access`/`read`/`write` events in `events.jsonl` are also accepted by the analyzer. -* **Analyzer.** `greeneye analyze` renders an `## Execution trace` section: +* **Analyzer.** `./risc-v-gsp-rm-debugger.sh analyze` renders an `## Execution trace` section: exec/read/write totals, unique PCs grouped by symbol, and accessed 4 KiB - pages with read/write counts. `greeneye compare` adds a trace-stream totals + pages with read/write counts. `./risc-v-gsp-rm-debugger.sh compare` adds a trace-stream totals delta and includes trace writes in the written-page delta. * **API.** `ge.launch(..., backend="native", trace=...)` and `launch_native(trace=...)` take `True`, a dict @@ -414,7 +413,7 @@ single producer for stop-based and full-access events: the same run yields the same file. `exec`/`access` volume is controlled by profile logging and a ring budget; for the native backend that is implemented (M1.5, §1.1a): the stream is a session blob and the analyzer renders coverage -and accessed pages. `greeneye compare` treats backend identity, `t` and +and accessed pages. `./risc-v-gsp-rm-debugger.sh compare` treats backend identity, `t` and host paths as non-semantic, so cross-backend comparison is first-class. ## 11. Injection ABI @@ -471,7 +470,7 @@ familiar with the codebase; milestones are sequential. | M3 | Deterministic scheduler (budgets, timers, IRQ events) + event log/replay | multi-task test profile replays identically from the log on two hosts; tie-break and replay tests in CI | 3–4 wk | | M4 | Device-model parity with H2.2 + `dma`/`pmu_stub` + boot shims | real GSP image reaches the same stable state as the QEMU H2 exit under the same profile; differential suite passes for probe and boot fixtures; L3 parity documented, L2 still not claimed | 6–10 wk | | M5 | Injection ABI + service registry + `log`/`stub`/`forward` interception | an SDK v1 blob loads and serves a control end-to-end; each interception mode has a recorded acceptance session; fuzzing seed/restore demonstrated | 4–6 wk | -| M6 | Performance/ergonomics: profiling, fast paths, `--backend native`, docs + flag-removal criteria | §14 targets met; `greeneye demo --backend native` in the differential CI job; user docs updated | 3–4 wk | +| M6 | Performance/ergonomics: profiling, fast paths, `--backend native`, docs + status/marker criteria | §14 targets met; `./risc-v-gsp-rm-debugger.sh demo --backend native` in the differential CI job; user docs updated | 3–4 wk | > **M1 status: done (pure-Python reference implementation).** Ported without > the `Backend` refactor (see §5 note); differential parity and a determinism 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 effacb0..fb63203 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 @@ -1,6 +1,6 @@ # 17 — RM host oracle harness (`rmharness`) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > The RM tools are read-only host diagnostics. They are development tooling: > never shipped, never present in a guest, never a driver dependency. @@ -85,7 +85,7 @@ stdout/stderr under `/blobs/` with sizes and SHA-256. Existing sessions are appended to, never rewritten; a missing `session.json` is created with the `greeneye-session/1` format. Because these runs are external, the event `t` field is `0.0`; `start`/`end` (epoch seconds) carry -the wall clock. `greeneye analyze` tolerates the session; the run count shows +the wall clock. `./risc-v-gsp-rm-debugger.sh analyze` tolerates the session; the run count shows up in the event summary. `plugins/rmharness_plugin.py` exposes the same wrappers in the REPL 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 4fbe4d9..e30f57d 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 @@ -1,6 +1,6 @@ # 18 — Harness automation: portability matrix and mutation harness -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Two stdlib-only orchestration tools in `harness/` turn the manual playbooks into repeatable runs: @@ -60,7 +60,7 @@ Flags: `--probe-instructions N` (0 = wall-clock `--probe-duration`), ### 1.2 What each target does 1. **Probe** — the ELF is flattened and relocated to `0x80000000` exactly as - `greeneye probe` does, then run for a fixed instruction budget (default + `./risc-v-gsp-rm-debugger.sh probe` does, then run for a fixed instruction budget (default 2000) or a wall-clock budget. The first exception is parsed with `greeneye.analyze.parse_qemu_faults`; the stopped PC is annotated from the symbol DB. Raw `.fwimage` targets fault early here; that is the expected @@ -84,7 +84,7 @@ Flags: `--probe-instructions N` (0 = wall-clock `--probe-duration`), symbols/.json merged symbol DB per target sessions/-probe/ recorded probe session sessions/-scenario/ recorded scripted session - compare/--.md greeneye compare report per target pair + compare/--.md risc-v-gsp-rm-debugger.sh compare report per target pair ``` JSON shape (stable keys, targets in CLI order, tables sorted): @@ -183,7 +183,7 @@ are `ok` with `expected: null`. / findings.jsonl one compact finding per iteration (deterministic order) summary.md unique outcome classes, strategy coverage, examples, replay command - sessions/iter-0000/ recorded greeneye session per iteration + sessions/iter-0000/ recorded risc-v-gsp-rm-debugger session per iteration ``` Finding shape: 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 67ef556..a27a245 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 -> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H4 for the program. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> See [`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": @@ -412,7 +412,7 @@ The suite completes in well under a minute. anything that would change the product to a physical capture (docs/14 sections 6-7). * **No injected payloads here.** Discovery only *observes* injection slots; it - never loads a blob. Injection itself stays behind `greeneye inject` and the + never loads a blob. Injection itself stays behind `./risc-v-gsp-rm-debugger.sh inject` and the docs/12 contract. --- 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 dbfbb36..4c13d1f 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,6 +1,6 @@ # 20 — MCP server (risc-v-gsp-rm-debugger agent interface) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. What it 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 d4d7680..6ff07d6 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 @@ -1,6 +1,6 @@ # 21 — CI and release pipeline (version diff + evidence bundle) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). ## 1. Purpose 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 d92c0f0..63fbffa 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,6 +1,6 @@ # 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. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This is the combined porting guide for the three churn axes the project > 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 @@ -14,7 +14,7 @@ break `open-iov-vfio` while the other two stay still: | Axis | Examples | Primary evidence path | |---|---|---| | **CUDA userspace version** (`libcuda`) | 570.144 → 570.211.01; future 580/610 families | CUDA corpus tooling + guest smoke (`userspace/cuda/docs/07`) | -| **GSP firmware / RM version** | 570.144 → 570.211 GSP image; RM dispatcher and control-set changes | `greeneye probe` + `compare`, host oracle (`docs/05-operations/02` §4.1) | +| **GSP firmware / RM version** | 570.144 → 570.211 GSP image; RM dispatcher and control-set changes | `./risc-v-gsp-rm-debugger.sh probe` + `compare`, host oracle (`docs/05-operations/02` §4.1) | | **GPU device / architecture** | TU104 → GB202 (RTX 5090), GB10 (Grace-Blackwell), aarch64 hosts | Device profile + pairing check + portability matrix (docs/07 P2/P3, docs/18) | They interact: 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 7d18678..0757850 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 @@ -1,6 +1,6 @@ # 23 — RM 610 port readiness and approval gate -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00-OVERVIEW for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This document defines the gate, not a claim: readiness is **not** met today > (2026-10-02). It exists so no one starts the port early. @@ -106,7 +106,7 @@ Required results: * every suite green, with installed QEMU; skips are explained, not ignored; * `portability_matrix` self-comparison reports **zero deltas** (`all_zero`); * mutation `findings.jsonl` is byte-identical between the two seeded runs; -* `greeneye compare` on two identical runs is empty; +* `./risc-v-gsp-rm-debugger.sh compare` on two identical runs is empty; * `analyze` renders a coherent session (hook/watch/breakpoint events, UART banner liveness per docs/06 §7). 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 0dde6a8..6790e72 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 @@ -1,6 +1,6 @@ # 24 — Device map: first-touch MMIO and lenient native execution -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This is the H2.1 data layer and the first H2.2 building block, not a device > model. It carries the same fidelity rules as `06-ACCURACY.md`: L3 remains > **absent**; nothing here is a hardware, timing or security claim. @@ -55,9 +55,9 @@ Exact `(address, width, kind)` wins; a different width at the same address is still evidence for the register. A write to a read-observed address is absorbed; a read of a write-only register reads back zero. -## 3. Harvesting from `greeneye probe` +## 3. Harvesting from `./risc-v-gsp-rm-debugger.sh probe` -`greeneye probe` (unchanged) records `blobs/qemu.log` and the parsed +`./risc-v-gsp-rm-debugger.sh probe` (unchanged) records `blobs/qemu.log` and the parsed `qemu_first_fault` in `session.json`. Harvest reads either: ```bash 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 3409039..93d5d17 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 @@ -1,7 +1,7 @@ # 25 — Value validation: measurable time-to-value evidence -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See -> [00-OVERVIEW](00-OVERVIEW.md) for status. Every number in this document is +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> Every number in this document is > either **measured** on the bundled demo analog (recorded in > `harness/value_demos/artifacts/`) or explicitly labelled a **projection** > for the real case. No demo claims a real-GSP result the simulator cannot 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 d8c30dd..e4b8396 100644 --- a/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md +++ b/debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md @@ -1,6 +1,6 @@ # 26 — risc-v-gsp-rm-debugger architecture: full picture, workflow and API surfaces -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > 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. @@ -312,7 +312,7 @@ ones; it feeds the H2.2 QEMU device model and the H3 profile DSL. ```mermaid flowchart LR - P["greeneye probe (raw .fwimage in QEMU)"] -->|"blobs/qemu.log + qemu_first_fault"| H["device_map.py harvest"] + P["risc-v-gsp-rm-debugger.sh probe (raw .fwimage in QEMU)"] -->|"blobs/qemu.log + qemu_first_fault"| H["device_map.py harvest"] H --> MAP["greeneye-device-map/1
entries + meta (bias, sha256)"] MAP --> LOOK["DeviceMap.lookup
zero / value / unimplemented"] LOOK --> LEN["Native Machine(unknown_mmio=lenient)"] @@ -432,13 +432,13 @@ Invariants (enforced by tests or review): changes (16 §4, R0). 4. **ABI**: blobs declare an ABI version and capability metadata; breaking changes need a shim and a doc note (12 §8, V3). -5. **Markers**: the `TOOL IN DEVELOPMENT` banner stays until the acceptance - list in 00 passes; never shipped, never in a guest, never a driver - dependency. +5. **Markers**: the in-development notices were removed on 2026-10-02 after + the tool audit (27) and value demos (25); gated items stay marked as such. + Never shipped, never in a guest, never a driver dependency. 6. **Evidence**: no accuracy, portability or security claim without a recorded A/B session and an explicit L2/L3 fidelity statement (06 §5–6, 25 §10). -7. **Provenance**: tracked docs never name local source trees; public - descriptions first, local provenance in the local notes (V6). +7. **Provenance**: tracked docs describe components and behaviour; + conclusions cite recorded evidence (V6). ## 14. Diagram and document index 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 9c4f61e..23f3195 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,7 +1,7 @@ # 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. +> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> See [06-ACCURACY](06-ACCURACY.md) for fidelity limits. > Development-only: never shipped, never a driver dependency, never in a guest. Audit date: 2026-10-02. Scope: every runnable surface in @@ -101,11 +101,11 @@ tests/demos/docs), `not used yet` (no caller found; decision recorded), | `harness/reach.py` | reachability answers for a target | CLI `--method auto\|stimulus\|trigger\|run\|call` | `test_discovery.py` | 19 | verified useful | emits suggested probe spec | | `harness/version_diff.py` | old-vs-new firmware diff | CLI `--old/--new` | `test_version_diff.py` | 21, 25 | verified useful | composes ci_release | | `harness/value_demos/*` | s01–s10 value validation + `run_all.py` | `python3 harness/value_demos/run_all.py [--only]` | `test_value_demos.py` | 25, MCP tools | verified useful | ran s02/s05 from the CLI; artifacts under `value_demos/artifacts/` | -| `plugins/example_plugin.py` | plugin authoring reference | `register(ge)` | plugin smoke (`--plugin`) | 04, plugins/README | verified useful | loaded via `greeneye run --plugin` | +| `plugins/example_plugin.py` | plugin authoring reference | `register(ge)` | plugin smoke (`--plugin`) | 04, plugins/README | verified useful | loaded via `./risc-v-gsp-rm-debugger.sh run --plugin` | | `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 ` | smoke | qemu/README | verified useful | thin `exec` of `risc-v-gsp-rm-debugger.sh launch` | +| `qemu/launch.sh` | one-line `risc-v-gsp-rm-debugger.sh launch` wrapper | `qemu/launch.sh --kernel ` | 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 | @@ -118,7 +118,7 @@ tests/demos/docs), `not used yet` (no caller found; decision recorded), | `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 | +| `examples/probes/demo_probes.json` | declarative probe spec sample | loaded by `greeneye.probes.install` | installed + fired via `./risc-v-gsp-rm-debugger.sh 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 (`risc-v-gsp-rm-debugger.yml`) | verified useful | includes live QEMU, native parity, MCP, bridge, harness, value demos | ## 4. Scripting API purpose review @@ -127,7 +127,7 @@ tests/demos/docs), `not used yet` (no caller found; decision recorded), and `ge.attach()` return a `Session`; `close()` clears breakpoints and kills owned QEMU unless `keep_alive=True`. Documented in 03 §1 and the `__init__` docstring. -* **`greeneye run` namespace.** Preloads `ge`, `session`/`s`, `memory`, +* **`risc-v-gsp-rm-debugger.sh run` namespace.** Preloads `ge`, `session`/`s`, `memory`, `symbols`, `recorder`, plus `__file__`/`__name__` (fixed here so scripts can locate bundled assets; `examples/scripts/dump_diff.py` depends on it). `docs/03-SCRIPTING.md` §intro now states this. @@ -197,7 +197,7 @@ Nothing was deleted. | tool | symptom | check | fix | |---|---|---|---| -| `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 | +| `risc-v-gsp-rm-debugger.sh` / CLI | `risc-v-gsp-rm-debugger 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//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` | 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 f75c8ed..974f013 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 -> [`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H4/R6 for the program. +> Status: scaffolding implemented and tested; this surface remains an unadmitted pilot (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). +> See [`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** 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 c87806b..53e0f03 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 @@ -1,6 +1,6 @@ # 29 — Packaging and trialing: sim + injected code as a deliverable -> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status. +> Status: scaffolding implemented and tested; this surface remains an unadmitted pilot (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). > This is a development-only convenience layer over docs/12 (injection SDK), > docs/16 (native simulator) and docs/24 (device map). It makes no hardware, > timing or security claim; the real `.fwimage` path is honestly blocked on @@ -166,7 +166,7 @@ status; a thrown error is recorded and exits 1. as `service_injected`, `call_enter`/`call_return`, `watch_hit` and `bp_hit` events, so the claim is replayable. 3. A baseline package with the previous service is diffed with - `greeneye compare`; the delta is the behavior change. + `./risc-v-gsp-rm-debugger.sh compare`; the delta is the behavior change. 4. A reviewer re-runs the received package on the tool tree, verifies hashes and expects the same `status`/call results. Divergence is a finding against the package or the tree, not a nuance. diff --git a/debug/risc-v-gsp-rm-vm/ghidra/README.md b/debug/risc-v-gsp-rm-vm/ghidra/README.md index ce7b4c7..6d30062 100644 --- a/debug/risc-v-gsp-rm-vm/ghidra/README.md +++ b/debug/risc-v-gsp-rm-vm/ghidra/README.md @@ -33,7 +33,7 @@ $GHIDRA/support/analyzeHeadless -process -noanaly ``` Address convention: the exported `addr` is the **program address** (what -Ghidra shows). `greeneye symbols export --index` understands the 3-column +Ghidra shows). `./risc-v-gsp-rm-debugger.sh symbols export --index` understands the 3-column form and keeps file/program addresses separate when present (4/7-column project indexes). Pass `--bias` only when the exported TSV does not already carry runtime addresses. diff --git a/debug/risc-v-gsp-rm-vm/greeneye/record.py b/debug/risc-v-gsp-rm-vm/greeneye/record.py index 91c7fb5..b02de26 100644 --- a/debug/risc-v-gsp-rm-vm/greeneye/record.py +++ b/debug/risc-v-gsp-rm-vm/greeneye/record.py @@ -11,6 +11,7 @@ from __future__ import annotations import json import os import time +import uuid import zlib FORMAT = "greeneye-session/1" @@ -49,8 +50,12 @@ class Recorder: @classmethod def new(cls, *, base: str | None = None, name: str = "session", meta: dict | None = None) -> "Recorder": base = base or os.environ.get("GREENEYE_DUMPS") or os.path.join(os.getcwd(), "dumps") + os.makedirs(base, exist_ok=True) stamp = time.strftime("%Y%m%d-%H%M%S") - return cls(os.path.join(base, f"{stamp}-{name}"), name=name, meta=meta) + # A unique infix keeps concurrent sessions (tests, agents, CLI runs) + # from sharing one events.jsonl while the name stays the final suffix. + unique = uuid.uuid4().hex[:8] + return cls(os.path.join(base, f"{stamp}-{unique}-{name}"), name=name, meta=meta) # -- writing ----------------------------------------------------------- diff --git a/debug/risc-v-gsp-rm-vm/harness/control_discovery.py b/debug/risc-v-gsp-rm-vm/harness/control_discovery.py index ca671d2..1eb4971 100644 --- a/debug/risc-v-gsp-rm-vm/harness/control_discovery.py +++ b/debug/risc-v-gsp-rm-vm/harness/control_discovery.py @@ -806,7 +806,7 @@ def render_markdown(report: dict, options: "DiscoveryOptions") -> str: lines = [ "# risc-v-gsp-rm-debugger control discovery report", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/control_discovery.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/control_discovery.py`.", "", f"* format: `{FORMAT}`", f"* surface: `{report['surface']}`", diff --git a/debug/risc-v-gsp-rm-vm/harness/mutation_harness.py b/debug/risc-v-gsp-rm-vm/harness/mutation_harness.py index 9b4d102..4ae2345 100644 --- a/debug/risc-v-gsp-rm-vm/harness/mutation_harness.py +++ b/debug/risc-v-gsp-rm-vm/harness/mutation_harness.py @@ -439,7 +439,7 @@ def write_summary(options: HarnessOptions, findings: list[dict]) -> str: lines = [ "# risc-v-gsp-rm-debugger mutation findings", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/mutation_harness.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/mutation_harness.py`.", "", f"* format: `{FORMAT}`", f"* kernel: `{options.kernel}`", diff --git a/debug/risc-v-gsp-rm-vm/harness/port_driver_versions.py b/debug/risc-v-gsp-rm-vm/harness/port_driver_versions.py index f12b8e9..2d7416d 100644 --- a/debug/risc-v-gsp-rm-vm/harness/port_driver_versions.py +++ b/debug/risc-v-gsp-rm-vm/harness/port_driver_versions.py @@ -875,7 +875,7 @@ def render_version_markdown(entry: dict) -> str: lines = [ f"# risc-v-gsp-rm-debugger port version {entry['version']}", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/port_driver_versions.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/port_driver_versions.py`.", "", f"* status: **{entry['status']}**", f"* baseline: `{entry.get('baseline')}`", @@ -906,7 +906,7 @@ def render_sweep_markdown(report: dict) -> str: lines = [ "# risc-v-gsp-rm-debugger driver-version port sweep", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/port_driver_versions.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/port_driver_versions.py`.", "", f"* format: `{report['format']}`", f"* baseline: `{report['baseline']['version']}` (`{report['baseline']['path']}`)", diff --git a/debug/risc-v-gsp-rm-vm/harness/port_new_device.py b/debug/risc-v-gsp-rm-vm/harness/port_new_device.py index 8ed1a0c..cf24cc6 100644 --- a/debug/risc-v-gsp-rm-vm/harness/port_new_device.py +++ b/debug/risc-v-gsp-rm-vm/harness/port_new_device.py @@ -468,7 +468,7 @@ def render_checklist_markdown(checklist: dict) -> str: lines = [ f"# risc-v-gsp-rm-debugger port checklist: {checklist['device']}", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/port_new_device.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/port_new_device.py`.", "", f"* firmware: `{checklist['firmware']}`", f"* reference: `{checklist['reference']}`", @@ -587,7 +587,7 @@ def render_report_markdown(report: dict) -> str: lines = [ f"# risc-v-gsp-rm-debugger device port: {report['device']}", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/port_new_device.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/port_new_device.py`.", "", f"* format: `{report['format']}`", f"* firmware: `{report['firmware']['path']}` ({report['firmware']['kind']}, " diff --git a/debug/risc-v-gsp-rm-vm/harness/portability_matrix.py b/debug/risc-v-gsp-rm-vm/harness/portability_matrix.py index 68ffdd3..a30bb7c 100644 --- a/debug/risc-v-gsp-rm-vm/harness/portability_matrix.py +++ b/debug/risc-v-gsp-rm-vm/harness/portability_matrix.py @@ -565,7 +565,7 @@ def render_markdown(report: dict, options: MatrixOptions) -> str: lines = [ "# risc-v-gsp-rm-debugger portability delta report", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/portability_matrix.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/portability_matrix.py`.", "", f"* format: `{report['format']}` (risc-v-gsp-rm-debugger {_greeneye_version()})", f"* backend: `{report['backend']}` (qemu available: {report['qemu_available']})", diff --git a/debug/risc-v-gsp-rm-vm/harness/reach.py b/debug/risc-v-gsp-rm-vm/harness/reach.py index 68934b1..5447364 100644 --- a/debug/risc-v-gsp-rm-vm/harness/reach.py +++ b/debug/risc-v-gsp-rm-vm/harness/reach.py @@ -673,7 +673,7 @@ def render_markdown(report: dict, options: ReachOptions) -> str: lines = [ "# risc-v-gsp-rm-debugger reachability report", "", - "> TOOL IN DEVELOPMENT - NOT READY YET! Generated by `harness/reach.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/reach.py`.", "", f"* format: `{FORMAT}`", f"* target: `{report['target']}` @ `{report['target_addr']:#x}`", diff --git a/debug/risc-v-gsp-rm-vm/harness/value_demos/_common.py b/debug/risc-v-gsp-rm-vm/harness/value_demos/_common.py index 0733c48..ebbc390 100644 --- a/debug/risc-v-gsp-rm-vm/harness/value_demos/_common.py +++ b/debug/risc-v-gsp-rm-vm/harness/value_demos/_common.py @@ -17,6 +17,7 @@ import json import os import shutil import sys +import tempfile import time HERE = os.path.dirname(os.path.abspath(__file__)) @@ -95,11 +96,24 @@ def artifact_dir(name: str) -> str: return path +def session_dir(root: str, label: str = "session") -> str: + """A unique recording dir under ``root``. + + Demos share a fixed artifact root so their reports are discoverable, but + two concurrent demo runs (tests, agents) must never share one + ``events.jsonl`` or a reader can see a half-written recording. + """ + os.makedirs(root, exist_ok=True) + return tempfile.mkdtemp(prefix=f"{label}-", dir=root) + + def write_json(path: str, payload) -> str: os.makedirs(os.path.dirname(path), exist_ok=True) - with open(path, "w", encoding="utf-8") as fh: + tmp = f"{path}.tmp-{os.getpid()}" + with open(tmp, "w", encoding="utf-8") as fh: json.dump(payload, fh, indent=2, sort_keys=True) fh.write("\n") + os.replace(tmp, path) return path diff --git a/debug/risc-v-gsp-rm-vm/harness/value_demos/s06_inject_service.py b/debug/risc-v-gsp-rm-vm/harness/value_demos/s06_inject_service.py index 04dd001..dc5949e 100644 --- a/debug/risc-v-gsp-rm-vm/harness/value_demos/s06_inject_service.py +++ b/debug/risc-v-gsp-rm-vm/harness/value_demos/s06_inject_service.py @@ -76,7 +76,8 @@ def run() -> dict: C.write_json(os.path.join(out, "inject.json"), payload) return payload - session = ge.launch(kernel=C.DEMO_ELF, backend=backend, record=os.path.join(out, "session"), name="vd-s06") + session_dir = C.session_dir(out) + session = ge.launch(kernel=C.DEMO_ELF, backend=backend, record=session_dir, name="vd-s06") try: ctrl = session.symbols.lookup("gsp_ctrl") session.run(duration=0.25) @@ -96,7 +97,7 @@ def run() -> dict: "remote": {"ping": remote_ping, "sum": remote_sum}, "via_firmware": {"ping": via_fw_ping, "sum": via_fw_sum}, "mailbox_command": C.INJECT_CMD_BASE + C.SERVICE_SLOT, - "session": os.path.relpath(os.path.join(out, "session"), C.TOOL_ROOT), + "session": os.path.relpath(session_dir, C.TOOL_ROOT), "question": "load/register/invoke a service blob end-to-end, both routes", "answer": ( f"service loaded at {service.load_addr:#x}, slot {service.slot} " diff --git a/debug/risc-v-gsp-rm-vm/harness/value_demos/s07_version_diff.py b/debug/risc-v-gsp-rm-vm/harness/value_demos/s07_version_diff.py index eaad957..e752807 100644 --- a/debug/risc-v-gsp-rm-vm/harness/value_demos/s07_version_diff.py +++ b/debug/risc-v-gsp-rm-vm/harness/value_demos/s07_version_diff.py @@ -106,8 +106,10 @@ def run() -> dict: schema = C.load_schema(ge) results = {} + session_dirs = {} for label, path in (("A", va), ("B", vb)): - session = ge.launch(kernel=path, backend=backend, record=os.path.join(out, f"session-{label}"), name=f"vd-s07-{label}") + session_dirs[label] = C.session_dir(out, f"session-{label}") + session = ge.launch(kernel=path, backend=backend, record=session_dirs[label], name=f"vd-s07-{label}") try: ctrl = session.symbols.lookup("gsp_ctrl") dispatches = [] @@ -134,7 +136,7 @@ def run() -> dict: session.close() compare_md = compare_sessions( - os.path.join(out, "session-A"), os.path.join(out, "session-B"), symbols=session.symbols, max_rows=20 + session_dirs["A"], session_dirs["B"], symbols=session.symbols, max_rows=20 ) C.write_text(os.path.join(out, "compare-sessions.md"), compare_md) moved = sorted( diff --git a/debug/risc-v-gsp-rm-vm/harness/value_demos/s09_grabbing_a_ghidra_address.py b/debug/risc-v-gsp-rm-vm/harness/value_demos/s09_grabbing_a_ghidra_address.py index 1d30b58..5bd1efe 100644 --- a/debug/risc-v-gsp-rm-vm/harness/value_demos/s09_grabbing_a_ghidra_address.py +++ b/debug/risc-v-gsp-rm-vm/harness/value_demos/s09_grabbing_a_ghidra_address.py @@ -51,7 +51,8 @@ def run() -> dict: backend = C.choose_backend("qemu") out = C.artifact_dir("s09_grabbing_a_ghidra_address") - names_tsv = os.path.join(out, "ghidra_names.tsv") + session_dir = C.session_dir(out) + names_tsv = os.path.join(session_dir, "ghidra_names.tsv") facts = _ghidra_tsv(ge, names_tsv) runtime_rpc_fault = ge.load_elf(C.DEMO_ELF) addr_rpc_fault = None @@ -95,7 +96,8 @@ def run() -> dict: commands, ) - session = ge.launch(kernel=C.DEMO_ELF, backend=backend, record=os.path.join(out, "session"), name="vd-s09") + session_dir = C.session_dir(out) + session = ge.launch(kernel=C.DEMO_ELF, backend=backend, record=session_dir, name="vd-s09") try: session.symbols.load_names_tsv(names_tsv, bias=BIAS) ctrl = session.symbols.lookup("gsp_ctrl") @@ -105,7 +107,7 @@ def run() -> dict: session.run(duration=0.25) session.memory.write_u64(ctrl + C.CTRL_MAILBOX, 6) session.run(duration=0.25) - hits_tsv = export_hits(os.path.join(out, "session"), os.path.join(out, "greeneye_hits.tsv"), symbols=session.symbols) + hits_tsv = export_hits(session_dir, os.path.join(session_dir, "greeneye_hits.tsv"), symbols=session.symbols) payload = { "success": len(hits) >= 1 and resolved == addr_rpc_fault, "backend": backend, diff --git a/debug/risc-v-gsp-rm-vm/harness/value_demos/s10_full_session_evidence.py b/debug/risc-v-gsp-rm-vm/harness/value_demos/s10_full_session_evidence.py index f6cd48f..75d7b1e 100644 --- a/debug/risc-v-gsp-rm-vm/harness/value_demos/s10_full_session_evidence.py +++ b/debug/risc-v-gsp-rm-vm/harness/value_demos/s10_full_session_evidence.py @@ -67,7 +67,7 @@ def _trace_overhead(ge, out: str) -> dict: import time def timed(trace): - record = os.path.join(out, "trace-off" if not trace else "trace-on") + record = C.session_dir(out, "trace-on" if trace else "trace-off") start = time.monotonic() session = ge.launch(kernel=C.DEMO_ELF, backend="native", record=record, trace=trace, name="vd-s10-trace") run_start = time.monotonic() @@ -134,19 +134,21 @@ def run() -> dict: ) start = time.monotonic() - session_a = _stimulus(ge, os.path.join(out, "session-A"), backend) - session_b = _stimulus(ge, os.path.join(out, "session-B"), backend) + session_a_dir = C.session_dir(out, "session-A") + session_b_dir = C.session_dir(out, "session-B") + session_a = _stimulus(ge, session_a_dir, backend) + session_b = _stimulus(ge, session_b_dir, backend) symbols = ge.SymbolDB() symbols.load_elf(ge.load_elf(C.DEMO_ELF)) - report = render_summary(os.path.join(out, "session-A"), symbols=symbols, max_rows=30) + report = render_summary(session_a_dir, symbols=symbols, max_rows=30) C.write_text(os.path.join(out, "analyze.md"), report) - compare = compare_sessions(os.path.join(out, "session-A"), os.path.join(out, "session-B"), symbols=symbols, max_rows=30) + compare = compare_sessions(session_a_dir, session_b_dir, symbols=symbols, max_rows=30) C.write_text(os.path.join(out, "compare.md"), compare) - hits = export_hits(os.path.join(out, "session-A"), os.path.join(out, "greeneye_hits.tsv"), symbols=symbols) + hits = export_hits(session_a_dir, os.path.join(out, "greeneye_hits.tsv"), symbols=symbols) trace = _trace_overhead(ge, out) - size_a = _dir_size(os.path.join(out, "session-A")) - size_b = _dir_size(os.path.join(out, "session-B")) + size_a = _dir_size(session_a_dir) + size_b = _dir_size(session_b_dir) deltas_match = session_a["dispatches"] == session_b["dispatches"] and session_a["ping_reply"] == session_b["ping_reply"] manifest = { "format": "greeneye-value-evidence/1", @@ -155,8 +157,8 @@ def run() -> dict: "sha256": C.sha256_file(C.DEMO_ELF), }, "sessions": { - "a": {"path": os.path.relpath(os.path.join(out, "session-A"), C.TOOL_ROOT), "bytes": size_a, "sha256_manifest": C.sha256_file(os.path.join(out, "session-A", "events.jsonl"))}, - "b": {"path": os.path.relpath(os.path.join(out, "session-B"), C.TOOL_ROOT), "bytes": size_b, "sha256_manifest": C.sha256_file(os.path.join(out, "session-B", "events.jsonl"))}, + "a": {"path": os.path.relpath(session_a_dir, C.TOOL_ROOT), "bytes": size_a, "sha256_manifest": C.sha256_file(os.path.join(session_a_dir, "events.jsonl"))}, + "b": {"path": os.path.relpath(session_b_dir, C.TOOL_ROOT), "bytes": size_b, "sha256_manifest": C.sha256_file(os.path.join(session_b_dir, "events.jsonl"))}, }, "stimulus": {"commands": [1, 5], "arg0": 0x1234, "note": "PING then STATE"}, "observed": {"a": session_a, "b": session_b, "delta_match": deltas_match}, diff --git a/debug/risc-v-gsp-rm-vm/harness/version_diff.py b/debug/risc-v-gsp-rm-vm/harness/version_diff.py index ccc6a15..8e57036 100644 --- a/debug/risc-v-gsp-rm-vm/harness/version_diff.py +++ b/debug/risc-v-gsp-rm-vm/harness/version_diff.py @@ -1225,7 +1225,7 @@ def render_markdown(report: dict, options: VersionDiffOptions) -> str: lines = [ "# risc-v-gsp-rm-debugger version diff", "", - "> **# TOOL IN DEVELOPMENT - NOT READY YET!** Generated by `harness/version_diff.py`.", + "> Status: implemented, documented and tested (audit: docs/27-TOOL-AUDIT.md; value demos: docs/25-VALUE-VALIDATION.md). Generated by `harness/version_diff.py`.", "", f"* format: `{report['format']}`", f"* targets: `{old['label']}` -> `{new['label']}`", diff --git a/debug/risc-v-gsp-rm-vm/qemu/README.md b/debug/risc-v-gsp-rm-vm/qemu/README.md index fede60e..8492a7b 100644 --- a/debug/risc-v-gsp-rm-vm/qemu/README.md +++ b/debug/risc-v-gsp-rm-vm/qemu/README.md @@ -21,7 +21,7 @@ systems where the QEMU source tree is not installed. If you prefer your distro's header, point `CFLAGS` at it instead. `launch.sh` starts a target through the package and keeps it alive for -`greeneye attach`: +`risc-v-gsp-rm-debugger.sh attach`: ```bash qemu/launch.sh --kernel firmware/uproc_demo/build/uproc_demo.elf diff --git a/debug/risc-v-gsp-rm-vm/qemu/launch.sh b/debug/risc-v-gsp-rm-vm/qemu/launch.sh index bca0d17..f5aac31 100755 --- a/debug/risc-v-gsp-rm-vm/qemu/launch.sh +++ b/debug/risc-v-gsp-rm-vm/qemu/launch.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Start a risc-v-gsp-rm-debugger target and keep it alive for `greeneye attach`. +# Start a risc-v-gsp-rm-debugger target and keep it alive for `risc-v-gsp-rm-debugger.sh attach`. set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" exec "$HERE/../risc-v-gsp-rm-debugger.sh" launch "$@" diff --git a/debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh b/debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh index 75c9052..400281a 100755 --- a/debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh +++ b/debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # risc-v-gsp-rm-debugger launcher: run the package from this directory without installation. -# TOOL IN DEVELOPMENT - NOT READY YET! +# Status: implemented, documented and tested (audit docs/27-TOOL-AUDIT.md; value demos docs/25-VALUE-VALIDATION.md). set -euo pipefail HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" export PYTHONPATH="$HERE${PYTHONPATH:+:$PYTHONPATH}" diff --git a/debug/risc-v-gsp-rm-vm/tests/test_discovery.py b/debug/risc-v-gsp-rm-vm/tests/test_discovery.py index 4a1cfc2..66b2a84 100644 --- a/debug/risc-v-gsp-rm-vm/tests/test_discovery.py +++ b/debug/risc-v-gsp-rm-vm/tests/test_discovery.py @@ -134,7 +134,7 @@ class DiscoveryIntegrationTests(unittest.TestCase): self.assertTrue(os.path.exists(report_path)) with open(report_path, encoding="utf-8") as fh: report = fh.read() - self.assertIn("TOOL IN DEVELOPMENT - NOT READY YET!", report) + self.assertIn("Status: implemented, documented and tested", report) self.assertIn("Unknown / undiscovered ids", report) self.assertIn("Injected-slot dispatch ids", report) self.assertIn("rpc_fault", report) -- cgit v1.2.3