summaryrefslogtreecommitdiffstats
path: root/docs/05-operations
diff options
context:
space:
mode:
authorArthur Hanson Rasmusson <arthur@vgpu.io>2026-10-02 12:41:52 -0400
committerArthur Hanson Rasmusson <arthur@vgpu.io>2026-10-02 12:41:52 -0400
commit14cf2aa59c44a50f9a108b93d58c7cecab17d45f (patch)
tree92076b380791fe650cad54bbd1ca7f4e33c85c35 /docs/05-operations
parent1c99bfbeffff04529f6f669601fdf835a73778da (diff)
downloadopen-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.md2
-rw-r--r--docs/05-operations/03-risc-v-gsp-rm-vm.md39
-rw-r--r--docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md21
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