summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-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
-rw-r--r--docs/06-portability/03-device-validation-and-porting-sequence.md4
-rw-r--r--docs/07-developers/02-development-and-analysis-environment.md10
-rw-r--r--docs/07-developers/onboarding-and-standards.md2
-rw-r--r--docs/README.md6
-rw-r--r--docs/RUNBOOK.md25
-rw-r--r--docs/eng-ops.md14
-rw-r--r--docs/future-eng-ops.md4
10 files changed, 70 insertions, 57 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
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. |