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 | 14cf2aa59c44a50f9a108b93d58c7cecab17d45f (patch) | |
| tree | 92076b380791fe650cad54bbd1ca7f4e33c85c35 /docs/05-operations | |
| parent | 1c99bfbeffff04529f6f669601fdf835a73778da (diff) | |
| download | open-iov-14cf2aa59c44a50f9a108b93d58c7cecab17d45f.tar.gz open-iov-14cf2aa59c44a50f9a108b93d58c7cecab17d45f.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.
Diffstat (limited to 'docs/05-operations')
| -rw-r--r-- | docs/05-operations/02-debugging-and-maintenance-workflows.md | 2 | ||||
| -rw-r--r-- | docs/05-operations/03-risc-v-gsp-rm-vm.md | 39 | ||||
| -rw-r--r-- | docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md | 21 |
3 files changed, 35 insertions, 27 deletions
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 |
