summaryrefslogtreecommitdiffstats
path: root/docs/RUNBOOK.md
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
commit271bb3251267fec68f5c9cec63314b22cfaefe75 (patch)
tree7807872b74b49ba77a145c51c405f690425c6b43 /docs/RUNBOOK.md
parent05797fd8cf884bb680540dfc188f36836a215c9f (diff)
downloadopen-iov-271bb3251267fec68f5c9cec63314b22cfaefe75.tar.gz
open-iov-271bb3251267fec68f5c9cec63314b22cfaefe75.zip
debug: risc-v-gsp-rm-debugger final pass - remove in-development notices, complete rename, adversarial-review fixes
Remove the '# TOOL IN DEVELOPMENT - NOT READY YET!' notices from the tool docs/README/scripts and the project docs; record the removal (2026-10-02) against the tool audit (debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md), the 194-test suite and the value-validation demos (docs/25-VALUE-VALIDATION.md). Complete the cosmetic rename to risc-v-gsp-rm-debugger in user-facing prose and commands (launcher, roadmap, docs); internal greeneye package and code identifiers unchanged. Adversarial-review fixes: deterministic control-discovery sweep (flaky test root-caused), UUID session dirs + atomic JSON writes for concurrent runs, Ghidra bridge loopback enforcement and clean shutdown, fp register restore in Session.call, version_diff --dry-run, 30 s interrupt budget, dry-run non-destructiveness verified. Docs: flag-removal records, link fixes, command/flag corrections (fdematch arity, port_new_device --out, trace filename), F2 orchestration note in future-eng-ops; STATE-CURRENT status refreshed.
Diffstat (limited to 'docs/RUNBOOK.md')
-rw-r--r--docs/RUNBOOK.md25
1 files changed, 14 insertions, 11 deletions
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;