diff options
Diffstat (limited to 'docs/RUNBOOK.md')
| -rw-r--r-- | docs/RUNBOOK.md | 25 |
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; |