diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md b/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md new file mode 100644 index 0000000..18d93bd --- /dev/null +++ b/debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md @@ -0,0 +1,259 @@ +# 23 — RM 610 port readiness and approval gate + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00-OVERVIEW for status. +> This document defines the gate, not a claim: readiness is **not** met today +> (2026-10-02). It exists so no one starts the port early. + +**The RM 610 port begins only after explicit human approval.** That is a hard +gate, not a scheduling preference: until a named human approves it in writing, +nothing in this repository fetches, downloads, extracts or analyses a 610 GSP +firmware image, and no code or document treats 610 as an anchor or a supported +target. The gate is repeated in the sign-off checklist (§6) and is the first +thing the approval message must acknowledge. + +## 1. Hard gate + +| Rule | Meaning | +|---|---| +| No acquisition | No 610 runfile, GSP `.fwimage`, driver package or firmware blob is fetched, extracted, copied or mirrored before approval. | +| No analysis | No decompilation, symbol export, probe, corpus diff or pairing comparison against a 610 image before approval. | +| No emulation edits | No version-keyed handler, signature entry or profile edit justified by "610" before approval; changes require current-version evidence. | +| No physical-GPU work | No unsupervised physical-GPU cycle, mdev claim or driver bind/unbind for 610; the project rule is no unattended physical-GPU cycles (GREEN-EYE-ROADMAP H7). | +| No support claims | 610 is not entered in the hardware/software matrix or the version matrix until it passes the docs/22 port checklists with evidence. | + +Precision notes: + +* The pinned `nvidia-open-gpu-kernel-modules` checkout used as build glue + (recorded in `SBOM.md`) is **not** a GSP firmware image and is **not** a 610 + port; it neither authorises acquisition nor counts as analysis. +* This document, docs/22 and the current-version test runs are the only + 610-adjacent work permitted today. Everything else waits for approval. +* Approval is scoped and revocable: it covers named inputs and named + activities, on a named date, by a named approver. + +### 1.1 What approval does and does not cover + +| Approval covers | Approval does not cover | +|---|---| +| Acquiring the named 610 inputs through the named channel | Any other 610 artifact or channel not listed in the approval message | +| Analysis, probing, diffing and evidence capture on the 610 inputs | Merging an emulation change without the docs/22 A/B evidence | +| Running the docs/22 port workflow and the pipeline dry-run | Physical-GPU execution without a separate supervised plan | +| Publishing 610 evidence into the port log | Entering 610 as "Supported" in the matrix before validation | +| Re-asking for a scope extension | Retroactively blessing work done before approval | + +An approval with an open-ended scope is invalid; ask again with the specific +inputs and activities. A denied or expired approval leaves the repo in the +state described in §5. + +## 2. Readiness criteria (all must be true) + +Every row must pass on the **current anchor** (570.144) before approval is even +requested. "All must be true" is literal: a single open item keeps the gate +closed. + +| # | Criterion | How it is verified | Evidence | Status today | +|---|---|---|---|---| +| C1 | All tools implemented and tested on the current driver/firmware | full test suites green (documents/demo/probe/inject/Ghidra/harness) | test logs attached to the request | partial (MCP/CI missing) | +| C2 | Tests green | `make test` and the harness/rmharness suites pass | transcript with date and commit | green at v0.1 (55 tests) | +| C3 | Demo, probe, inject, Ghidra work | `./greeneye.sh demo`, `probe`, `inject`, `ghidra` all demonstrated | session dirs + transcript | working per docs/00 | +| C4 | MCP monitoring works | MCP plugin implemented and exercised (roadmap R3, docs/08; docs/15) | tool list + a monitored run | **not implemented (planned R3)** | +| C5 | CI pipeline works | release/CI pipeline implemented and exercised (planned docs/21) | pipeline run with artifacts | **not implemented (planned docs/21)** | +| C6 | Docs complete and accurate | doc review checklist (§3.2) signed | review record | to complete | +| C7 | Discovery/version-diff/CI exercised on the current version | control discovery (planned docs/19) + `harness/portability_matrix.py` + `compare` + pipeline dry-run on 570.144 | report + session hashes | partial (matrix/compare exist; docs/19 planned) | +| C8 | Harness produces a full evidence bundle | docs/07 checklist + docs/14 §6 pack produced end to end for a current-version port rehearsal | bundle directory with SHA-256 inventory | to complete | +| C9 | Human has approved | signed message (§6) | approval ID recorded in the request thread | pending | + +C4 and C5 are the long poles. Do not silently downgrade them: if the human +chooses to waive a criterion, the waiver is written into the approval message +with its risk and the affected scope. + +## 3. What "ready" looks like concretely + +### 3.1 Exact commands that must pass + +Run from `open-iov/debug/risc-v-gsp-rm-vm/` (docs/02 §8 has the make targets): + +```bash +make demo +make test +python3 -m unittest tests.test_harness -v +python3 rmharness/tests/test_rmharness_plugin.py +./greeneye.sh info +./greeneye.sh demo +./greeneye.sh demo --backend native +./greeneye.sh probe +./greeneye.sh inject +./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json +./greeneye.sh analyze dumps/<run> --symbols symbols-<ver>.json +./greeneye.sh compare dumps/<a> dumps/<b> --symbols +``` + +Plus, on the current version: + +```bash +python3 harness/portability_matrix.py \ + --target firmware/uproc_demo/build/uproc_demo.elf \ + --target firmware/uproc_demo/build/uproc_demo.elf \ + --out dumps/matrix-selfcheck +python3 harness/mutation_harness.py --out dumps/mutation-selfcheck \ + --iterations 12 --seed 7 +python3 harness/mutation_harness.py --out dumps/mutation-replay \ + --iterations 12 --seed 7 +``` + +Required results: + +* every suite green, with installed QEMU; skips are explained, not ignored; +* `portability_matrix` self-comparison reports **zero deltas** (`all_zero`); +* mutation `findings.jsonl` is byte-identical between the two seeded runs; +* `greeneye compare` on two identical runs is empty; +* `analyze` renders a coherent session (hook/watch/breakpoint events, UART + banner liveness per docs/06 §7). + +### 3.2 Doc review checklist + +* [ ] 00–18 match the code on the current commit (commands, flags, status + tables, test counts); +* [ ] `docs/22` porting guide is accurate for the current tools; planned items + are labelled `planned (docs/xx)`; +* [ ] `docs/19-CONTROL-DISCOVERY.md` (planned) exists and has been run once on + the current version, or C7 is explicitly waived; +* [ ] `docs/21-CI-RELEASE-PIPELINE.md` (planned) exists and has run once on the + current version, or C5 is explicitly waived; +* [ ] `GREEN-EYE-ROADMAP.md` and `docs/08` status claims match reality; +* [ ] no local source paths, no invented command names, no unsupported + "supported/accurate" claims. + +### 3.3 Golden sessions and regression data in place + +* [ ] golden demo session(s) checked in or reproducible by a documented seed; +* [ ] matrix self-comparison zero-delta output archived; +* [ ] mutation replay corpus archived with its seed and budget; +* [ ] rmharness host-oracle captures for the current anchor archived + (`rmtool engine list --format=json`, `mem stats --format=json`); +* [ ] a full current-version evidence bundle (docs/07 checklist + docs/14 §6) + produced once, as the rehearsal for the 610 run. + +## 4. Dry-run plan for the day of approval (no execution today) + +Executed only after the approval in §6 exists. Steps 1–2 are acquisition and +must not happen beforehand. + +1. **Confirm the approval.** Record approval ID, approver, date, scope and any + waived criterion in the port log. +2. **Obtain the 610 inputs through the approved channel.** The 610 driver + runfile and matching GSP `.fwimage` (or the approved firmware source) are + fetched through the channel named in the approval. Record the runfile + version, firmware hash (MD5/SHA-256), version string and image family + immediately; extract the `.fwimage` per docs/05-operations §4.1 step 1. +3. **Lay down versioned directories.** `firmware/<SERIES>-GSP/610/`, + `userspace/cuda/610/` (copied skeleton), `config/versions/610.yaml` + (documentation until the load path reads it). Never overwrite a working + version; keep 570.144 untouched. +4. **Pair and probe.** Build the 610 symbol DB (`analyze_fwimage.py`, + `symbols export --bias 0`), probe the 610 image and the 570.144 reference + with the same bounded settings, and diff the first-touch maps. Pairing + mismatch stops the run here. +5. **Baseline vs candidate orchestration.** Run + `harness/portability_matrix.py` with the 610 and 570.144 targets and + identical scenario options; run the mutation harness once per version with + the same seed; archive both reports and every session. +6. **Pipeline dry-run, then real.** Run the release pipeline (planned + docs/21-CI-RELEASE-PIPELINE.md) in its dry-run mode first; inspect the + planned artifact list without publishing. Only after the dry-run is clean, + run the real pipeline on the 610 evidence bundle. +7. **Expected artifacts.** + * approval record and input hashes; + * 610 symbol DB + Ghidra export provenance; + * probe reports (610 and reference) and the first-touch diff; + * `portability-report.json`/`.md`, per-pair compare reports, sessions; + * mutation `findings.jsonl` + summary for both versions; + * M1–M6 table with reference-capture method and L2/L3 limits; + * doc updates per docs/22 §3.5/§4 and the matrix entry (if and only if the + support claim is earned). +8. **Decision points.** Stop and keep the current anchor if: pairing is + ambiguous; any unexplained probe delta remains; the engine/RPC inventory + diff is not fully explained; M1–M6 regress on the current workload; the + evidence bundle is incomplete. Forward only when every delta has a decided + response. +9. **Rollback / keep-old-version rules.** The 570.144 directories, + configuration and guest driver stay untouched; rollback = return to the old + anchor commit/tag and the old guest driver (docs/05-operations §4.1 step 6). + A forward attempt never destroys the working setup; do not delete the old + version tree and do not reuse 570.144-derived addresses for 610. + +## 5. What must NOT happen before approval + +| Prohibited action | Why it is prohibited | +|---|---| +| Download/fetch 610 blobs or runfiles | Version discipline and evidence integrity: an unapproved input hash cannot anchor a later claim; acquisition is the act the gate exists to control. | +| Probe or decompile a 610 image | Analysis before readiness contaminates the evidence chain and tempts ad-hoc emulation edits. | +| Edit emulation code "for 610" | No current-version evidence justifies it; version-keyed handlers must be driven by a measured inventory diff (docs/05-operations §4.1 step 4). | +| Touch the physical GPU for 610 | Project hard rule: no unattended physical-GPU cycles; physical validation is a supervised step after approval. | +| Try the 610 driver in a guest | The guest never contains Open-IOV code and the anchor is fixed; an unpaired driver failure looks like an emulation bug (docs/07 P2.2). | +| Record 610 in the support/version matrix | Support means tested and documented; an untested entry violates the matrix contract (hardware-software-matrix §1/§6). | +| Treat the pinned open-module tag as approval | Build glue is not a GSP image and not an authorised port input (SBOM.md). | + +Permitted before approval: reading this document and docs/22, running all +current-version tests, producing and archiving the current evidence bundle, +and preparing the approval request. + +## 6. Sign-off checklist and approval message + +### 6.1 Human sign-off (one page) + +* [ ] **The RM 610 port begins only after explicit human approval.** +* [ ] C1–C9 all true, or each waiver is listed with its scope and risk. +* [ ] Test transcript attached (date, commit, `make test` green). +* [ ] `portability_matrix` self-comparison zero deltas; mutation replay + byte-identical. +* [ ] Doc review checklist (§3.2) complete. +* [ ] Current-version evidence bundle complete with SHA-256 inventory. +* [ ] Golden sessions/regression data in place (§3.3). +* [ ] Approval message (§6.2) sent and answered with an approval ID. +* [ ] Named approver accepts the acquisition scope and the permitted channel. + +``` +Approver: ______________________ Role: ______________________ +Approval ID: ____________________ Date: ______________________ +Scope limits / waivers: ________________________________________ +Signature: ______________________ +``` + +### 6.2 Approval request message (exact format) + +Send exactly this shape; fill every `<...>` and leave "Waivers" as "none" if +empty: + +``` +RM 610 PORT APPROVAL REQUEST + +Anchor today: 570.144 (firmware <sha256>; guest driver <md5>) +Target: RM 610 (requested input: <runfile version / approved source>) +Requested scope: acquire the 610 driver + GSP firmware through <approved +channel>; lay down versioned dirs; analyse, probe, diff, and run the docs/22 +port workflow; no product change before A/B evidence. + +Readiness, docs/23 §2: + C1 tools tested .......... <pass / waived> + C2 tests green ........... <pass / waived> + C3 demo/probe/inject/Ghidra <pass / waived> + C4 MCP monitoring ........ <pass / waived> + C5 CI pipeline ........... <pass / waived> + C6 docs complete ......... <pass / waived> + C7 discovery/diff/CI ..... <pass / waived> + C8 evidence bundle ....... <pass / waived> + C9 human approval ........ requested by this message + +Waivers: <none / list with reason> +Evidence bundle: <path> +Commit: <git rev>; transcripts: <paths> +Signed: <name/role>, <date> + +Decision (human): APPROVED / DENIED +Approval ID: <id>; Date: <date>; Scope limits: <text> +``` + +After approval, the 610 port proceeds only through the docs/22 workflow and +the docs/05-operations §4.1 version discipline. Until that message exists, +this repository is a 610 no-fly zone. |