diff options
| author | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 12:41:52 -0400 |
|---|---|---|
| committer | Arthur Hanson Rasmusson <arthur@vgpu.io> | 2026-10-02 12:41:52 -0400 |
| commit | 271bb3251267fec68f5c9cec63314b22cfaefe75 (patch) | |
| tree | 7807872b74b49ba77a145c51c405f690425c6b43 | |
| parent | 05797fd8cf884bb680540dfc188f36836a215c9f (diff) | |
| download | open-iov-271bb3251267fec68f5c9cec63314b22cfaefe75.tar.gz open-iov-271bb3251267fec68f5c9cec63314b22cfaefe75.zip | |
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.
61 files changed, 231 insertions, 189 deletions
diff --git a/STATE-CURRENT.md b/STATE-CURRENT.md index 9078550..69f5574 100644 --- a/STATE-CURRENT.md +++ b/STATE-CURRENT.md @@ -133,8 +133,8 @@ chain succeeds. with a GDB stub and adds Frida-like runtime inspection, a scripting/plugin API and a Ghidra bridge for GSP-RM runtime-memory analysis and emulation-accuracy measurement. It is debug tooling only (no product code - changes) and is explicitly marked `# TOOL IN DEVELOPMENT - NOT READY YET!`; - see + changes); the in-development notices were removed 2026-10-02 after the tool + audit and value validation; see [`docs/05-operations/03-risc-v-gsp-rm-vm.md`](docs/05-operations/03-risc-v-gsp-rm-vm.md). - **P6a trigger-path fix landed (2026-10-02 07:10).** The debug copy triggers now resolve the guest page host-physical address at trigger time @@ -808,7 +808,10 @@ Experimental developer tooling (not part of the product path): **risc-v-gsp-rm-d (`debug/risc-v-gsp-rm-vm/`) boots GSP/uproc firmware in a RISC-V QEMU VM with a GDB stub and adds Frida-like runtime inspection, a scripting/plugin API and a Ghidra bridge for GSP-RM runtime-memory analysis and emulation-accuracy -measurement. It is marked `# TOOL IN DEVELOPMENT - NOT READY YET!`; see +measurement. Status is tracked by the tool audit +(`debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md`); the in-development notices +were removed 2026-10-02 after the 194-test suite and end-to-end value +demonstrations (`debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md`); see [`docs/05-operations/03-risc-v-gsp-rm-vm.md`](docs/05-operations/03-risc-v-gsp-rm-vm.md). | Wall | Fix | @@ -897,7 +900,7 @@ device. - [`docs/03-architecture/08-physical-gpu-integration.md`](docs/03-architecture/08-physical-gpu-integration.md) - chosen execution backend (module-owned GPU + real GSP session) - [`docs/03-architecture/09-full-system-picture.md`](docs/03-architecture/09-full-system-picture.md) - visual end-to-end system map with status tags - [`docs/03-architecture/10-interaction-and-scheduling.md`](docs/03-architecture/10-interaction-and-scheduling.md) - cross-component interaction, queues, interrupts, scheduling detail -- [`docs/05-operations/03-risc-v-gsp-rm-vm.md`](docs/05-operations/03-risc-v-gsp-rm-vm.md) - risc-v-gsp-rm-debugger GSP RISC-V VM runtime analysis (`# TOOL IN DEVELOPMENT - NOT READY YET!`) +- [`docs/05-operations/03-risc-v-gsp-rm-vm.md`](docs/05-operations/03-risc-v-gsp-rm-vm.md) - risc-v-gsp-rm-debugger GSP RISC-V VM runtime analysis (status: docs/27 tool audit, docs/25 value validation) --- 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 `addr<TAB>hits<TAB>symbol`, 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 <script.py>` (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-<run> dumps/greeneye-<run> +Comparison: `./risc-v-gsp-rm-debugger.sh compare dumps/real-<run> dumps/greeneye-<run> --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 <rehosted elf> --duration N --snapshot <regions>` + * `./risc-v-gsp-rm-debugger.sh record --kernel <rehosted elf> --duration N --snapshot <regions>` or the scripted harness (`run`), * the real-backend reference traces for the same workload. 5. **Compare** — `./risc-v-gsp-rm-debugger.sh compare dumps/<old> dumps/<new> --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 <fwimage>` reaches a stable address and +**Exit criteria:** `./risc-v-gsp-rm-debugger.sh probe <fwimage>` 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": <int>, "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/<a> dumps/<b> --symbols` is the primary agent +`./risc-v-gsp-rm-debugger.sh compare dumps/<a> dumps/<b> --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 `<session>/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/<target>.json merged symbol DB per target sessions/<target>-probe/ recorded probe session sessions/<target>-scenario/ recorded scripted session - compare/<a>--<b>.md greeneye compare report per target pair + compare/<a>--<b>.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`. <out>/ 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<br/>entries + meta (bias, sha256)"] MAP --> LOOK["DeviceMap.lookup<br/>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 <elf>` | 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 <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 | @@ -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/<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` | 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 <proj_dir> <project> -process <program> -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) diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index 975b3dc..b7aab25 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -194,7 +194,7 @@ instead. ### 3.9 Firmware runtime analysis — risc-v-gsp-rm-debugger (experimental) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: [docs/27](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); value demos: [docs/25](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)). For firmware-side questions (what does the GSP/uproc server do at runtime, what does it read/write, how do its state machines evolve), the experimental diff --git a/docs/05-operations/03-risc-v-gsp-rm-vm.md b/docs/05-operations/03-risc-v-gsp-rm-vm.md index 773006d..cde0736 100644 --- a/docs/05-operations/03-risc-v-gsp-rm-vm.md +++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md @@ -1,12 +1,13 @@ # GSP in a RISC-V VM — risc-v-gsp-rm-debugger (experimental) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: [docs/27](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); value demos: [docs/25](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)). > This is experimental developer tooling. It is not part of the shipped > emulation, never runs in a guest, and its interfaces, file formats and > documented workflows may change without notice. Do not depend on it in -> production paths or cite it as a supported feature. When it reaches a -> minimum stable level, the flags will be removed from this document and from -> the developer-tools list. +> production paths or cite it as a supported feature. The in-development +> notices were removed on 2026-10-02 after the tool audit, the 194-test green +> suite and the end-to-end value demonstrations; docs 28/29 remain unadmitted +> pilots. ## 1. What it is @@ -22,9 +23,9 @@ its runtime behaviour inspectable with Frida-like primitives: (`Session.run_until`), * **code injection**: build a position-independent RV64 service with the `sdk/`, load it into the running firmware and register it so the firmware - dispatches to it (`greeneye inject`), + dispatches to it (`./risc-v-gsp-rm-debugger.sh inject`), * declarative probe specs, a plugin API, a Ghidra symbol/hit bridge and a - **Ghidra control bridge** (`greeneye ghidra` + `GreenEyeControl.java`) for + **Ghidra control bridge** (`./risc-v-gsp-rm-debugger.sh ghidra` + `GreenEyeControl.java`) for "execute until here" from the decompiler. Its stated purpose is **simulating and inspecting the GSP firmware's runtime @@ -41,7 +42,7 @@ accuracy, portability playbooks, roadmap) is under ## 2. What it is not * **Not a GSP boot environment.** QEMU `virt` has no falcon windows, WPR2, - CSB/TRANSCOM, PMU, timers or FB DMA. `greeneye probe` shows exactly where + CSB/TRANSCOM, PMU, timers or FB DMA. `./risc-v-gsp-rm-debugger.sh probe` shows exactly where the real image first diverges (for the TU104 570.144 image: a load-access fault at firmware vaddr `0x4009014` reading `0x2000000000000A00`); it does not boot it. A device model is a roadmap item, not a claim. @@ -62,7 +63,7 @@ accuracy, portability playbooks, roadmap) is under The intended measurement loop is: capture the real backend's RPC behaviour, run the same stimulus in risc-v-gsp-rm-debugger, and compare the recorded sessions -(`greeneye compare`) with the accuracy metrics defined in the tool's +(`./risc-v-gsp-rm-debugger.sh compare`) with the accuracy metrics defined in the tool's `docs/06-ACCURACY.md`. Portability runs (new GSP, new device, GB10-class architecture) are described in `docs/07-PORTABILITY-PLAYBOOKS.md`. @@ -98,14 +99,20 @@ roadmap. The long-term program (adversarial navigation, adjacent microcontrollers, custom simulator, Verilog soft-core, agentic platform) is documented in `debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`. -## 6. When the development flag can be removed +## 6. Development notices removed (2026-10-02) -The marker comes off this document and the developer-tools list when: +The in-development notices were removed from this document and from the +developer-tools list on 2026-10-02, after: -1. the v0.1 acceptance list in `debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md` - passes on a clean checkout; -2. the usage recipes in `docs/02-USAGE.md` are verified end-to-end; -3. a second person or agent can run the quickstart unaided; -4. the session format and CLI are declared stable. +1. the v0.1 surface passed the tool audit on a clean checkout + (`debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md`); +2. the full suite ran green — 194 tests + (`python3 -m unittest discover -s tests -t .`); +3. the usage recipes and the s01–s10 end-to-end value demonstrations were + verified (`debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md`); +4. the session format and CLI are the audited v0.1 surfaces. -Until then, treat everything here as in development. +Open items stay open and are not stability claims: docs/28 porting automation +and docs/29 trial packaging remain unadmitted pilots, the device model (R1) +and custom simulator M2+ (R2) remain roadmap, and RM 610 stays behind the +human gate. diff --git a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md index f12230a..c1ecffe 100644 --- a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md +++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md @@ -1,6 +1,6 @@ # risc-v-gsp-rm-debugger User Guide (experimental) -> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> Status: implemented, documented and tested (audit: [docs/27](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); value demos: [docs/25](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)). > risc-v-gsp-rm-debugger is the development environment for running GSP/uproc firmware > off-hardware, observing it, injecting into it and comparing runs as evidence. > It is never shipped, never a driver dependency and never present in a guest; @@ -122,7 +122,7 @@ security claims. Every run records a `greeneye-session/1` directory: ```text -dumps/<stamp>-<name>/ +dumps/<stamp>-<uuid>-<name>/ session.json format, name, counts, snapshot inventory, meta events.jsonl append-only event stream (hooks, watches, memory, notes) snapshots/*.bin.z zlib-compressed region captures with sha256 @@ -181,7 +181,7 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. | `plugins/rmharness_plugin.py` | REPL commands for the host RM oracle | | `rmharness/harness.sh` + `rmtool`/`rmtop`/`rmq` | read-only host oracle captures appended into a session | | `ghidra/ExportForGreenEye.java`, `MarkGreenEyeHits.java`, `GreenEyeControl.java` | symbol export, hit annotation and decompiler-driven execution | -| `sdk/` + `greeneye inject` | position-independent service ABI v1 | +| `sdk/` + `./risc-v-gsp-rm-debugger.sh inject` | position-independent service ABI v1 | ## 5. Choosing the right tool @@ -342,17 +342,18 @@ python3 -m greeneye.device_map show dumps/<ver>-device-map.json | `NameError: __file__` in `run` scripts | script invoked outside `risc-v-gsp-rm-debugger.sh run` | run through `./risc-v-gsp-rm-debugger.sh run`, keep scripts inside the tool tree | | Empty TCG trace blob | plugin window missed or target never resumed | `make -C qemu`; widen `start=`/`end=`, set `exec=on`, resume the target | | MCP writes refused / no tools | server read-only by default; stdout polluted | pass `--allow-write`/`--allow-inject` deliberately; keep stdout protocol-only | -| `greeneye error:` on a valid path | wrong relative path or `--db` file | `./risc-v-gsp-rm-debugger.sh info` shows resolved paths; bad symbol DBs fail with a clear error | +| `risc-v-gsp-rm-debugger error:` on a valid path | wrong relative path or `--db` file | `./risc-v-gsp-rm-debugger.sh info` shows resolved paths; bad symbol DBs fail with a clear error | | Harness findings not reproducible | seed/budget changed | pin `--seed` and budgets; compare `findings.jsonl` byte-for-byte | | Everything "unreachable" | wrong surface/timeouts | run `--surface demo` on the built demo first; raise `--settle`/`--timeout` | | `Unknown symbol` in the optional OpenRM build | module-tag drift | re-pin build glue; see the [RUNBOOK](../RUNBOOK.md) S2 | -Marker status: every tool document carries the -**# TOOL IN DEVELOPMENT - NOT READY YET!** banner. The marker is removed only -when the acceptance list in -[docs/00-OVERVIEW](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md) passes on a -clean checkout, the usage recipes verify end-to-end, a second person can run -the quickstart unaided, and the session format and CLI are declared stable. +Marker status: the in-development notices were removed on 2026-10-02 after the +tool audit ([docs/27](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md)), the +194-test green suite, and the end-to-end s01–s10 value demonstrations +([docs/25](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)). Open +items stay listed honestly: docs 28/29 are unadmitted pilots and the device +model/custom simulator M2+ remain roadmap. The session format and CLI are the +audited v0.1 surfaces; treat changes to them as reviewed events. ## 9. Safety diff --git a/docs/06-portability/03-device-validation-and-porting-sequence.md b/docs/06-portability/03-device-validation-and-porting-sequence.md index 6c5bc59..e4e7be5 100644 --- a/docs/06-portability/03-device-validation-and-porting-sequence.md +++ b/docs/06-portability/03-device-validation-and-porting-sequence.md @@ -119,7 +119,7 @@ Per driver/firmware version `N`: the per-version bundle carries `version-diff/`, `portability-matrix/` and `mutation-smoke/` results plus the M1–M6 skeleton. 4. **Device profile** — for a new device run - `python3 harness/port_new_device.py --run --device <name> --firmware <N-image> --reference <anchor-image>` + `python3 harness/port_new_device.py --run --device <name> --firmware <N-image> --reference <anchor-image> --out dumps/port-<name>` (docs/28 §3; unadmitted pilot, evaluation in future-eng-ops F3); fill the profile from §4 evidence and reconcile the engine inventory against the host oracle. @@ -129,7 +129,7 @@ Per driver/firmware version `N`: * capture host module trace (`gsp-resman-vfio:`), guest dmesg, `nvidia-smi -q`, `lspci -vvv`, and the control/ioctl sequence; * compare the physical captures with the simulator sessions - (`greeneye compare`, M1–M6) and resolve every delta as profile, logic or + (`./risc-v-gsp-rm-debugger.sh compare`, M1–M6) and resolve every delta as profile, logic or fidelity gap (docs/07 P4). 6. **No new guest regression** — run the existing guest/CUDA ladder rungs and confirm no rung regressed before the next version. diff --git a/docs/07-developers/02-development-and-analysis-environment.md b/docs/07-developers/02-development-and-analysis-environment.md index 4bff443..f19a4d8 100644 --- a/docs/07-developers/02-development-and-analysis-environment.md +++ b/docs/07-developers/02-development-and-analysis-environment.md @@ -21,8 +21,10 @@ In scope: the developer-facing analysis environment. Out of scope: end-user installation (see [`02-getting-started/01-install-and-first-run.md`](../02-getting-started/01-install-and-first-run.md)), the emulation architecture itself (see [`03-architecture/01-system-overview.md`](../03-architecture/01-system-overview.md)) -and product roadmaps. The risc-v-gsp-rm-debugger toolchain is **in development and not -ready yet** — status, limits and flag-removal criteria are in +and product roadmaps. The risc-v-gsp-rm-debugger toolchain is +**implemented, documented and tested** — the in-development notices were +removed on 2026-10-02 after the tool audit and end-to-end value demos; status, +limits and open items are in [`05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md) and the tool's own [`docs/00-OVERVIEW.md`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md). @@ -182,7 +184,7 @@ risc-v-gsp-rm-debugger adds a runtime layer on top in ioctl layer (`tools/rmtool/src/rm_api.c`, `query.c`); `tools/rmq` is the pre-existing device-info oracle. They allocate only an RM client/device/ subdevice handle and never create engine, channel or memory objects; write -paths are refused in code. Risc-V GSP-RM debugger's `rmharness/` wrappers locate, build and +paths are refused in code. RISC-V GSP-RM debugger's `rmharness/` wrappers locate, build and capture them into sessions. ```bash @@ -312,7 +314,7 @@ Detailed procedures are not duplicated here. | Axis | Static triage | Dynamic confirmation | Full procedure | |---|---|---|---| | New CUDA userspace (`libcuda` bump) | `cudatool.py info/delta`, `fdematch`, `diff_corpus.py`, name-map apply | guest smoke (`cuda_drv_test.c`), `cuda-ab`, symbol spot-checks | [`userspace/cuda/docs/07`](../../userspace/cuda/docs/07-version-upgrade-playbook.md); risc-v-gsp-rm-debugger [`22`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §2 | -| New GSP/RM firmware version | decompile + diff RPC dispatcher/controls; Ghidra symbol inventory | `greeneye probe` first-touch, scripted/re-hosted `record`, `compare`, `version_diff.py` | [`05-operations/02` §4.1](../05-operations/02-debugging-and-maintenance-workflows.md) (upgrade runbook); risc-v-gsp-rm-debugger [`07 P1`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`21`](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), [`22`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §3 | +| New GSP/RM firmware version | decompile + diff RPC dispatcher/controls; Ghidra symbol inventory | `./risc-v-gsp-rm-debugger.sh probe` first-touch, scripted/re-hosted `record`, `compare`, `version_diff.py` | [`05-operations/02` §4.1](../05-operations/02-debugging-and-maintenance-workflows.md) (upgrade runbook); risc-v-gsp-rm-debugger [`07 P1`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`21`](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), [`22`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md) §3 | | New device / architecture | device profile data, ISA/image shape, PMU/SOE deltas | portability matrix, probe first-touch on the new image | [`06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md) and [`03-device-validation-and-porting-sequence.md`](../06-portability/03-device-validation-and-porting-sequence.md); risc-v-gsp-rm-debugger [`07 P2/P3`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`18`](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md) | | A/B accuracy ritual (real vs emulated) | M1–M6 metric definition | hardware/VFIO reference capture vs risc-v-gsp-rm-debugger session | [`05-operations/01`](../05-operations/01-performance-correctness-security.md); risc-v-gsp-rm-debugger [`06`](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md), [`07 P4`](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`25`](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) | | RM 610 family | — | gate first; nothing opened before approval | risc-v-gsp-rm-debugger [`23`](../../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md) (hard gate), [`21` §3](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) | diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index b99613e..50f4f93 100644 --- a/docs/07-developers/onboarding-and-standards.md +++ b/docs/07-developers/onboarding-and-standards.md @@ -158,7 +158,7 @@ The following rules each come from a real bug and are enforced in review: | `tools/firmware_analyzer.py` + Ghidra scripts | firmware analysis pipeline | | module debug parameters | guest-memory scanning/poking, VRAM inspection; physical-backend parameters and debugfs state/control files (see [`../eng-ops.md`](../eng-ops.md) Part II) | | QEMU gdbstub workflow | guest virtual-memory inspection/writing | -| `debug/risc-v-gsp-rm-vm/` (risc-v-gsp-rm-debugger) | **# TOOL IN DEVELOPMENT - NOT READY YET!** — RISC-V GSP/uproc VM runtime inspection, session recording and `gsp-rm-vfio` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) | +| `debug/risc-v-gsp-rm-vm/` (risc-v-gsp-rm-debugger) | implemented, documented and tested ([audit](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) — RISC-V GSP/uproc VM runtime inspection, session recording and `gsp-rm-vfio` accuracy measurement (see [`../05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md)) | | `wiki/` documents | protocol and firmware deep dives | ## 5. Landing a change diff --git a/docs/README.md b/docs/README.md index f0849fb..0873387 100644 --- a/docs/README.md +++ b/docs/README.md @@ -174,8 +174,8 @@ Read in order if you are new. Jump directly if you know what you need. | 17 | [Practical challenges and adversarial interoperability](04-implementation/02-practical-challenges-and-adversarial-interop.md) | developers, stakeholders | 20 min | | 18 | [Performance, correctness, security](05-operations/01-performance-correctness-security.md) | developers, auditors | 25 min | | 19 | [Debugging and maintenance workflows](05-operations/02-debugging-and-maintenance-workflows.md) | developers, maintainers | 25 min | -| 20 | [GSP in a RISC-V VM (risc-v-gsp-rm-debugger, experimental)](05-operations/03-risc-v-gsp-rm-vm.md) — **# TOOL IN DEVELOPMENT - NOT READY YET!** | developers, analysts | 15 min | -| 21 | [risc-v-gsp-rm-debugger user guide (experimental)](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) — **# TOOL IN DEVELOPMENT - NOT READY YET!** | developers, analysts | 15 min | +| 20 | [GSP in a RISC-V VM (risc-v-gsp-rm-debugger, experimental)](05-operations/03-risc-v-gsp-rm-vm.md) — implemented, documented and tested ([audit](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) | developers, analysts | 15 min | +| 21 | [risc-v-gsp-rm-debugger user guide (experimental)](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) — implemented, documented and tested ([audit](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) | developers, analysts | 15 min | | 22 | [Defensive Operations Runbook](RUNBOOK.md) | maintainers, operators | 20 min | | 23 | [Engineering operations](eng-ops.md) — tool admission and workflows (Part I) plus live physical-backend operations (Part II) | maintainers, developers | 20 min | | 24 | [Hardware and software matrix](06-portability/hardware-software-matrix.md) | developers, integrators | 20 min | @@ -227,7 +227,7 @@ and risc-v-gsp-rm-debugger user guide; additive only. --> * firmware runtime analysis (experimental): running GSP/uproc firmware in a RISC-V QEMU VM with hooks, watchpoints, memory dumps and `gsp-rm-vfio` - accuracy measurement — **# TOOL IN DEVELOPMENT - NOT READY YET!** → + accuracy measurement — implemented, documented and tested ([audit](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); [value demos](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)) → [`05-operations/03-risc-v-gsp-rm-vm.md`](05-operations/03-risc-v-gsp-rm-vm.md) (tooling in [`../debug/risc-v-gsp-rm-vm/`](../debug/risc-v-gsp-rm-vm/README.md)) * performance: the microbenchmark list and the A/B methodology → diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index 4b11dfa..c0dd3c8 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -14,9 +14,10 @@ > · [Developer onboarding and standards](07-developers/onboarding-and-standards.md) > · [Engineering operations](eng-ops.md) > -> **# TOOL IN DEVELOPMENT - NOT READY YET!** The risc-v-gsp-rm-debugger tooling cited here -> is experimental; its interfaces and file formats may change. Nothing in this -> runbook authorises a product change, a hardware write or work on RM 610. +> Status: implemented, documented and tested (audit: [docs/27](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md); value demos: [docs/25](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md)). +> The risc-v-gsp-rm-debugger tooling cited here is experimental; its +> interfaces and file formats may change. Nothing in this runbook authorises a +> product change, a hardware write or work on RM 610. ## 0. How to use this runbook @@ -51,7 +52,7 @@ win. | P3 | **Evidence over anecdote.** Every conclusion needs at least an A/B pair and an explicit fidelity level (L0–L3). | A single run, a static reading or a simulator-only delta cannot land a product change. | | P4 | **Physical confirmation for behaviour changes.** A simulator observation is evidence about the firmware, not about silicon. | Reproduction on a supervised physical/vfio-mdev cycle is required before a change that alters emulation behaviour. | | P5 | **The simulator is a study environment, never a security boundary.** | No confidentiality, side-channel or security claims; never use injection to defeat a hardware security boundary. | -| P6 | **Development-only tooling.** risc-v-gsp-rm-debugger is never shipped, never a dependency of the emulation, never in a guest. | Keep the in-development banner on tool docs until the acceptance list passes. | +| P6 | **Development-only tooling.** risc-v-gsp-rm-debugger is never shipped, never a dependency of the emulation, never in a guest. | Keep the tool docs' status line and open-item list current (the in-development notices were removed 2026-10-02; audit docs/27). | | P7 | **No unattended physical-GPU cycles.** Physical work is supervised, with fail-safe release and explicit reboot approval. | Stop and ask; never bind/unbind drivers or claim the GPU as an experiment. | | P8 | **RM 610 is a hard human gate.** Until a named human approves in writing, no acquisition, analysis, emulation edit, physical work or support claim for 610. | The gate is enforced in code by `version_diff`/`ci_release`; do not work around it. | | P9 | **Fail closed, record honestly.** Unverified host info, unpaired firmware, unexplained deltas and absent references stay open. | "No unexplained deltas" is a claim that must be earned, not a default. | @@ -65,7 +66,7 @@ affected doc or PR. |---|---|---|---| | **Anchor maintainer** | guest driver ↔ emulated firmware anchor; version surface | keeps the anchor current; approves anchor bumps; keeps `config/versions/*.yaml` labelled as design targets until read by code | any change to the anchor | | **Firmware triage maintainer** | versioned firmware directories; symbol DBs; probe/version-diff runs | acquires and hashes new images; builds symbol DBs with provenance; runs the P1 loop; owns the pairing decision | pairing verdict; "new logic" vs "behaviour moved" | -| **risc-v-gsp-rm-debugger tooling maintainer** | `debug/risc-v-gsp-rm-vm/`; test suite; session format | keeps `make test` green; guards format/API stability; keeps the marker and doc map honest; maintains golden sessions | tool status claims; removal of the in-development marker | +| **risc-v-gsp-rm-debugger tooling maintainer** | `debug/risc-v-gsp-rm-vm/`; test suite; session format | keeps `make test` green; guards format/API stability; keeps the status line and doc map honest; maintains golden sessions | tool status claims; admitting or retiring gated items | | **CI/release maintainer** | `harness/version_diff.py`, `harness/ci_release.py`, `risc-v-gsp-rm-debugger.yml`, goldens | runs dry-run before real runs; hashes evidence bundles; diffs seeded corpora; keeps CI paths and budgets bounded | release triage sign-off; RM 610 gate enforcement | | **Physical-cycle supervisor** | supervised physical/vfio-mdev cycles | enforces fail-safe release, D0/D3cold handling and reboot approvals; captures reference traces | all physical execution; reboot requests | | **Evidence archivist** | session and bundle retention | keeps SHA-256 inventories; enforces provenance (no private paths, no unsanitised host data); applies retention/prune policy | publication of evidence | @@ -93,7 +94,7 @@ Golden artifacts are append-only history: never edit a stored golden session ### 3.2 Session hygiene -* Sessions are directories (`dumps/<stamp>-<name>/`) with `session.json`, +* Sessions are directories (`dumps/<stamp>-<uuid>-<name>/`) with `session.json`, `events.jsonl`, `snapshots/`, `blobs/` and `summary.md`. Keep them together; a copied `events.jsonl` without its `session.json` is not evidence. * Name sessions for the question asked, not the host or the operator. @@ -125,10 +126,12 @@ Golden artifacts are append-only history: never edit a stored golden session ### 3.4 Documentation and marker discipline -* The **# TOOL IN DEVELOPMENT - NOT READY YET!** banner stays on tool docs - until the acceptance list in - `debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md` passes; removal is a reviewed - change, not an edit. +* Tool docs carry a status line instead of a development banner: the + in-development notices were removed on 2026-10-02 after the tool audit + (`debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md`), the 194-test green suite + and the end-to-end value demos + (`debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md`); adding or removing + such a notice is a reviewed change, not an edit. * Every behaviour change updates the doc that describes it (docs are part of the definition of done); planned work is labelled `planned (docs/xx)`. * Status tables must match the code on the current commit (commands, flags, @@ -692,7 +695,7 @@ and never let the last step touch anything we do not own. ## 10. Related documentation -Risc-V GSP-RM debugger suite (experimental, in development): +RISC-V GSP-RM debugger suite (experimental; implemented, documented and tested): * [risc-v-gsp-rm-debugger user guide](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) — what it is, quickstart, tool chooser and troubleshooting; diff --git a/docs/eng-ops.md b/docs/eng-ops.md index 4dd450e..218b8cd 100644 --- a/docs/eng-ops.md +++ b/docs/eng-ops.md @@ -16,7 +16,7 @@ binds both: evidence or it did not happen ([`onboarding-and-standards.md`](07-de | Admission, extension, redesign, trialing and retirement of tools | Architecture ([`03-architecture/01-system-overview.md`](03-architecture/01-system-overview.md)); tool manuals: CUDA ([`../userspace/cuda/READ-ME-FIRST.md`](../userspace/cuda/READ-ME-FIRST.md)), risc-v-gsp-rm-debugger ([`26-ARCHITECTURE.md`](../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md), [user guide](../debug/risc-v-gsp-rm-vm/docs/02-USAGE.md), [scripting](../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md)), rmharness ([`README`](../debug/risc-v-gsp-rm-vm/rmharness/README.md)) | | Which tool applies in which loop; automation and packaging | Accuracy M1–M6 ([`06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md)); performance method ([`05-operations/01`](05-operations/01-performance-correctness-security.md) §3); version discipline ([`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md) §4) | | Evidence bundles, version-span gates, frontier admission | Per-tool docs and the periodic [`27-TOOL-AUDIT.md`](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md) | -| Live physical-backend engineering operations: supervised-cycle mechanics, parameter gates, debugfs controls and the hazard register (**Part II** below) | Physical-backend architecture ([`03-architecture/08`](03-architecture/08-physical-gpu-integration.md), [`03-architecture/11`](03-architecture/11-physical-backend-guest-wiring.md)); defensive/incident scenarios ([`RUNBOOK.md`](RUNBOOK.md)); current frontier ([`STATE-CURRENT.md`](STATE-CURRENT.md)) | +| Live physical-backend engineering operations: supervised-cycle mechanics, parameter gates, debugfs controls and the hazard register (**Part II** below) | Physical-backend architecture ([`03-architecture/08`](03-architecture/08-physical-gpu-integration.md), [`03-architecture/11`](03-architecture/11-physical-backend-guest-wiring.md)); defensive/incident scenarios ([`RUNBOOK.md`](RUNBOOK.md)); current frontier ([`STATE-CURRENT.md`](../STATE-CURRENT.md)) | **Explicitly out of scope.** (1) Security claims: the simulator and its device maps are study environments, never a confidentiality or isolation boundary @@ -175,7 +175,7 @@ the audit is the periodic reconciliation. | Admitted family | Loop | Value evidence (current) | Review / retire trigger | |---|---|---|---| | Ghidra corpora + scripts (`tools/ghidra`, `userspace/cuda/tools`) | RE, portability | docs 05/07; `diff_corpus`, name map | corpus diff no longer changes port class | -| risc-v-gsp-rm-debugger core + session format | dynamic-RE | `docs/25` s01–s10; 155-test suite | format unused by any loop | +| risc-v-gsp-rm-debugger core + session format | dynamic-RE | `docs/25` s01–s10; 194-test suite | format unused by any loop | | Harness (`version_diff`, matrix, mutation, discovery, reach, `ci_release`) | portability, adversarial | docs 18/19/21; deterministic replay tests | a report is never attached to a change | | Injection SDK + demo uproc | dynamic-RE | docs 11/12; s06 | prototypes stop using it | | Ghidra bridges (in/out) | RE | docs 05/13 | static/dynamic join replaced | @@ -227,7 +227,7 @@ flowchart LR IMP --> IDX["names.tsv, decompiled_index.tsv, callgraph.tsv"] IDX --> DIFF["corpus diff / fdematch / RPC dispatch diff"] DIFF --> HYP["Hypothesis: functions, tables, layouts"] - HYP --> SYM["greeneye symbols export (bias recorded)"] + HYP --> SYM["./risc-v-gsp-rm-debugger.sh symbols export (bias recorded)"] SYM --> DYN["dynamic loop"] DYN -->|"hits, watch PCs, fault PCs"| HYP ``` @@ -502,7 +502,7 @@ that cannot state a benefit is rejected as overhead. | Date | Revision | Purpose / scope | Benefit | Evidence | |---|---|---|---|---| | 2026-10-02 | v1 | Establish the admission rule, value axes, decision framework, workflow maps, automation, packaging, frontier gates and review discipline | Tooling decisions become auditable, measurable and reversible; no tool without an evaluation | This document plus linked tool docs and the [`docs/25`](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) baselines | -| 2026-10-02 | v2 (Part II) | Add the live physical-backend operations: hard rules and scope, build/load order and the full `gsp_phys_*` parameter matrix, the routine supervised cycle with its clean-release checklist, the debugfs inventory and `gsp-phys-state` reference, the physical-backend scenario catalogue and hazard register, the OODA loop and the work-context/porting map | Physical-backend execution becomes auditable and fail-safe: one checklist, a named signal per failure, and no retry of a wedged path | Kernel sources cited per parameter and debugfs file; the current frontier in this document and [`STATE-CURRENT.md`](STATE-CURRENT.md) | +| 2026-10-02 | v2 (Part II) | Add the live physical-backend operations: hard rules and scope, build/load order and the full `gsp_phys_*` parameter matrix, the routine supervised cycle with its clean-release checklist, the debugfs inventory and `gsp-phys-state` reference, the physical-backend scenario catalogue and hazard register, the OODA loop and the work-context/porting map | Physical-backend execution becomes auditable and fail-safe: one checklist, a named signal per failure, and no retry of a wedged path | Kernel sources cited per parameter and debugfs file; the current frontier in this document and [`STATE-CURRENT.md`](../STATE-CURRENT.md) | ```bash python3 scripts/check-docs-links.py # repo root @@ -523,7 +523,7 @@ cd debug/risc-v-gsp-rm-vm && make demo sdk && make test # tool claims > Part I (§§1–9) governs tooling admission, value measurement and retirement. > Defensive/incident scenarios are owned by [`RUNBOOK.md`](RUNBOOK.md) and are > cross-linked, not duplicated, here; the current frontier is -> [`STATE-CURRENT.md`](STATE-CURRENT.md); the known unknowns are +> [`STATE-CURRENT.md`](../STATE-CURRENT.md); the known unknowns are > [`04-implementation/01`](04-implementation/01-known-knowns-and-unknowns.md). > Everything in this part is supervised, bounded and fail-safe-first; nothing > here authorises unattended hardware work. @@ -809,7 +809,7 @@ bump, device/ISA/ROM change, protected state, matrix/CI) are owned by | Portability (firmware, hardware, driver version, userspace version) | [`06-portability/*`](06-portability/hardware-software-matrix.md) and [`RUNBOOK.md`](RUNBOOK.md) S1–S10. | | Performance and correctness validation | [`05-operations/01`](05-operations/01-performance-correctness-security.md) (evaluation ladder, metrics, A/B method). | | Architecture of the backend and the guest wiring | [`03-architecture/08`](03-architecture/08-physical-gpu-integration.md), [`03-architecture/11`](03-architecture/11-physical-backend-guest-wiring.md). | -| Current frontier and dated status | [`STATE-CURRENT.md`](STATE-CURRENT.md). | +| Current frontier and dated status | [`STATE-CURRENT.md`](../STATE-CURRENT.md). | ### 14.2 Triage flow for a CUDA/userspace symptom @@ -840,7 +840,7 @@ region up. The device is therefore parked in the **designed locked fail-safe** (module unloaded, GPU unbound, D0 locks held, WPR2 up) awaiting a supervised reboot; the promote path stays gated behind `gsp_phys_rmcall_gr_promote=0` until a bisected variant is proven. Live detail -and evidence pointers: [`STATE-CURRENT.md`](STATE-CURRENT.md). +and evidence pointers: [`STATE-CURRENT.md`](../STATE-CURRENT.md). <!-- change (2026-10-02): correct the porting/packaging tool section from planned interfaces that no longer match the landed scaffolds (docs 28/29) to diff --git a/docs/future-eng-ops.md b/docs/future-eng-ops.md index 00bffba..13a0b73 100644 --- a/docs/future-eng-ops.md +++ b/docs/future-eng-ops.md @@ -74,7 +74,7 @@ F11, F13). Each item carries exactly one evaluation criterion. | Field | Detail | |---|---| -| **Status** | `partially used`. `cudatool.py info/delta/fdematch`, `diff_corpus.py`, `annotate_corpus.py` and `symbols export` are in production use for the 570.144 anchor, but the docs/22 §2 runbook is ten manual steps. A concurrent `harness/port_driver_versions.py` scaffold is landing as an unadmitted pilot (dry-run default; [`docs/28`](../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md) §2); no chained multi-version run is admitted or exercised yet and there is no 540-era regression corpus in-tree. | +| **Status** | `partially used`. `cudatool.py info/delta/fdematch`, `diff_corpus.py`, `annotate_corpus.py` and `symbols export` are in production use for the 570.144 anchor, but the docs/22 §2 runbook is ten manual steps. A concurrent `harness/port_driver_versions.py` scaffold is landing as an unadmitted pilot (dry-run default; [`docs/28`](../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md) §2); no chained multi-version run is admitted or exercised yet and there is no 540-era regression corpus in-tree. Evaluate `harness/port_driver_versions.py` as an extension of `ci_release.py` rather than a third orchestrator; the criterion for keeping it separate is that the sweep must meet the F2 threshold without a release bundle as a precondition, otherwise fold it into `ci_release.py`. | | **Need** | The anchor is 570.144; deployed guests and the anticipated 580/610 families each repeat the same runbook, and wrapper re-resolution (~1% of wrapper names transfer by address) is a known trap ([`22-PORTING-CUDA-AND-DEVICES.md`](../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md)). Each repeat costs days of human time and risks silently moving wrapper names. | | **Scope** | Does chain the existing CUDA tools into one per-version report (exports, FDE transfer matrix, corpus delta, name map, symbol DB, smoke results) and diff reports across versions; does not decompile unknown binaries automatically, does not change the firmware anchor, does not run a guest smoke without a supervised guest. | | **Evaluation** | Metric: wall-clock and human minutes per version triage to a complete evidence pack. Baseline: the recorded 570.144 → 570.211 manual runbook. Threshold: one rerun (or 540-era reference) triaged in ≤50% of the baseline human minutes with wrapper re-resolution warnings preserved. Kill: if two consecutive versions need manual steps the chain cannot absorb, drop the chain and keep per-step tools. | @@ -96,7 +96,7 @@ F11, F13). Each item carries exactly one evaluation criterion. | Field | Detail | |---|---| -| **Status** | `partially used`. The PIC service SDK, `greeneye inject`, `elf.write_flat_kernel` and newly tested `write_relocated_elf` exist, and version diff already byte-patches an image ad hoc (docs/25 s07). A concurrent `harness/package_sim.py` scaffold is landing as an unadmitted pilot (trial directory plus `--pack-image`; [`docs/29`](../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)); no packer or trial bundle is admitted, hash-verified in CI, or used by a reviewer workflow yet. | +| **Status** | `partially used`. The PIC service SDK, `./risc-v-gsp-rm-debugger.sh inject`, `elf.write_flat_kernel` and newly tested `write_relocated_elf` exist, and version diff already byte-patches an image ad hoc (docs/25 s07). A concurrent `harness/package_sim.py` scaffold is landing as an unadmitted pilot (trial directory plus `--pack-image`; [`docs/29`](../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)); no packer or trial bundle is admitted, hash-verified in CI, or used by a reviewer workflow yet. | | **Need** | Injection experiments today are demo-slot recipes; RM-core injection (H1.3) and reviewer replay need a reproducible artifact, the docs/23 C8 evidence bundle needs one-command reproduction, and hand-built byte patches do not carry an ABI/version contract. | | **Scope** | Does build a deterministic image-pack (input hash, relocation map, injected segments, patched dispatch entries, blob ABI version) and a trial bundle (tool revision, profile, stimulus, expected session); does not sign images, does not bypass firmware checks, does not make an image runnable on hardware, does not ship. | | **Evaluation** | Metric: manual steps to reproduce a reviewer's injected-service run from the artifact. Baseline: the ad-hoc patch + inject recipe. Threshold: one command yields a bundle whose rerun reproduces a byte-identical session on a clean host. Kill: if a rerun depends on host-specific state or is non-deterministic, retire the pack format and keep sessions as the artifact. | |
