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 | |
| 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')
| -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 | ||||
| -rw-r--r-- | docs/06-portability/03-device-validation-and-porting-sequence.md | 4 | ||||
| -rw-r--r-- | docs/07-developers/02-development-and-analysis-environment.md | 10 | ||||
| -rw-r--r-- | docs/07-developers/onboarding-and-standards.md | 2 | ||||
| -rw-r--r-- | docs/README.md | 6 | ||||
| -rw-r--r-- | docs/RUNBOOK.md | 25 | ||||
| -rw-r--r-- | docs/eng-ops.md | 14 | ||||
| -rw-r--r-- | docs/future-eng-ops.md | 4 |
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. | |
