diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/05-operations/02-debugging-and-maintenance-workflows.md | 20 | ||||
| -rw-r--r-- | docs/05-operations/03-risc-v-gsp-rm-vm.md | 24 | ||||
| -rw-r--r-- | docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md (renamed from docs/05-operations/04-green-eye-user-guide.md) | 58 | ||||
| -rw-r--r-- | docs/06-portability/03-device-validation-and-porting-sequence.md | 4 | ||||
| -rw-r--r-- | docs/06-portability/hardware-software-matrix.md | 14 | ||||
| -rw-r--r-- | docs/07-developers/02-development-and-analysis-environment.md | 58 | ||||
| -rw-r--r-- | docs/07-developers/onboarding-and-standards.md | 2 | ||||
| -rw-r--r-- | docs/README.md | 16 | ||||
| -rw-r--r-- | docs/RUNBOOK.md | 60 | ||||
| -rw-r--r-- | docs/eng-ops.md | 36 | ||||
| -rw-r--r-- | docs/future-eng-ops.md | 22 |
11 files changed, 157 insertions, 157 deletions
diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index cfc452d..975b3dc 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -192,13 +192,13 @@ Watch the serial log afterwards for backtraces. A truly hard-wedged vCPU (spinning on a faulting MMIO instruction) may print nothing — use the gdbstub instead. -### 3.9 Firmware runtime analysis — green-eye (experimental) +### 3.9 Firmware runtime analysis — risc-v-gsp-rm-debugger (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** 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 -green-eye tooling runs uproc/GSP firmware in a `qemu-system-riscv64` VM with +risc-v-gsp-rm-debugger tooling runs uproc/GSP firmware in a `qemu-system-riscv64` VM with hooks, watchpoints, memory dumps and session recording, without a physical GPU, WPR2 risk or a reboot. See [`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md) for purpose, status and @@ -322,13 +322,13 @@ version × each hardware family, run the step-5 bring-up sequence. When adding a version, extend the matrix rather than replacing the old column — regressions across versions are the cheapest bugs to catch. -### 4.1.1 Green-eye-assisted upgrade/porting workflow (experimental) +### 4.1.1 Risc-V GSP-RM debugger-assisted upgrade/porting workflow (experimental) -<!-- change (2026-10-02): add the green-eye probe -> symbols -> version diff -> +<!-- change (2026-10-02): add the risc-v-gsp-rm-debugger probe -> symbols -> version diff -> portability matrix -> decide pipeline to the upgrade runbook, with pointers to -the new RUNBOOK and green-eye user guide; additive only. --> +the new RUNBOOK and risc-v-gsp-rm-debugger user guide; additive only. --> -For firmware-side questions the experimental green-eye tooling (see +For firmware-side questions the experimental risc-v-gsp-rm-debugger tooling (see [`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md)) turns steps 3–5 above into a repeatable pipeline that produces attachable evidence before any emulation change. It never replaces the physical backend when silicon truth is required, @@ -336,11 +336,11 @@ and it never touches a guest, a kernel module or the installed driver. | Rung | Command (from `debug/risc-v-gsp-rm-vm/`) | Output | |---|---|---| -| Probe | `./greeneye.sh probe <new.fwimage> --symbols symbols-<ver>.json --record` | first-divergence report; first-touch map | -| Symbols | `./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json` | runtime-address symbol DB with provenance | +| Probe | `./risc-v-gsp-rm-debugger.sh probe <new.fwimage> --symbols symbols-<ver>.json --record` | first-divergence report; first-touch map | +| Symbols | `./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json` | runtime-address symbol DB with provenance | | Version diff | `python3 harness/version_diff.py --old <old> --new <new> --out dumps/vdiff-<ver>` | shape/symbol/corpus/probe/behavior diff plus the M1–M6 skeleton | | Portability matrix | `python3 harness/portability_matrix.py --target <old> --target <new> --out dumps/matrix-<ver>` | per-target sessions and per-pair `compare` reports | -| Decide | `./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols` | symbol-attributed deltas; a product change only after physical confirmation | +| Decide | `./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols` | symbol-attributed deltas; a product change only after physical confirmation | Decision discipline: verify the pairing first; behaviour that moved without a code change is usually a state/ordering fix; changed code on a live path is @@ -348,7 +348,7 @@ prioritised; a symbol never hit in either run is a coverage gap, not dead code. The full incident procedures (symptoms, evidence, response order, rollback) are in the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S1 and its OODA ordering; the quickstart and tool chooser are in the -[green-eye user guide](04-green-eye-user-guide.md). +[risc-v-gsp-rm-debugger user guide](04-risc-v-gsp-rm-debugger-user-guide.md). ### 4.2 New guest driver version 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 c21124b..773006d 100644 --- a/docs/05-operations/03-risc-v-gsp-rm-vm.md +++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md @@ -1,4 +1,4 @@ -# GSP in a RISC-V VM — green-eye (experimental) +# GSP in a RISC-V VM — risc-v-gsp-rm-debugger (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** > This is experimental developer tooling. It is not part of the shipped @@ -10,7 +10,7 @@ ## 1. What it is -**green-eye** runs GSP/uproc firmware in a `qemu-system-riscv64` VM and makes +**risc-v-gsp-rm-debugger** runs GSP/uproc firmware in a `qemu-system-riscv64` VM and makes its runtime behaviour inspectable with Frida-like primitives: * breakpoints and enter/leave hooks (RV64 ABI aware), @@ -48,7 +48,7 @@ accuracy, portability playbooks, roadmap) is under * **Not a timing model.** Do not infer latency or concurrency behaviour from it; its in-scope conclusions are execution flow and memory side effects. * **Not a replacement for Ghidra or the guest diagnostics.** Ghidra answers - *what is the code*; green-eye answers *what did it do*. The guest driver + *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. The guest driver remains the oracle for guest-side behaviour. ## 3. Where it fits @@ -58,10 +58,10 @@ accuracy, portability playbooks, roadmap) is under | Static | Ghidra corpus (`userspace/cuda`, `tools/ghidra`) | what is the code? | | Guest driver | `tools/guest-diag/`, ptrace tracer | what did the driver request? | | Physical backend | supervised physical cycles, module logs | what did real silicon/the real GSP-RM do? | -| **Firmware runtime (this)** | **green-eye** | **what does the firmware server do, repeatably and safely?** | +| **Firmware runtime (this)** | **risc-v-gsp-rm-debugger** | **what does the firmware server do, repeatably and safely?** | The intended measurement loop is: capture the real backend's RPC behaviour, -run the same stimulus in green-eye, and compare the recorded sessions +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 `docs/06-ACCURACY.md`. Portability runs (new GSP, new device, GB10-class architecture) are described in `docs/07-PORTABILITY-PLAYBOOKS.md`. @@ -72,13 +72,13 @@ From the repository root: ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh info # environment check (QEMU, toolchain) +./risc-v-gsp-rm-debugger.sh info # environment check (QEMU, toolchain) make demo sdk # build the demo uproc and the injection SDK -./greeneye.sh demo # canned instrumentation pass; records a session -./greeneye.sh analyze dumps/<session> -./greeneye.sh probe # real GSP image: report the first divergence -./greeneye.sh inject # load and invoke an injected service -./greeneye.sh ghidra # serve the session to GhidraScripts +./risc-v-gsp-rm-debugger.sh demo # canned instrumentation pass; records a session +./risc-v-gsp-rm-debugger.sh analyze dumps/<session> +./risc-v-gsp-rm-debugger.sh probe # real GSP image: report the first divergence +./risc-v-gsp-rm-debugger.sh inject # load and invoke an injected service +./risc-v-gsp-rm-debugger.sh ghidra # serve the session to GhidraScripts ``` Requirements: `qemu-system-riscv64` (Ubuntu `qemu-system-misc`), Python 3.10+ @@ -96,7 +96,7 @@ real-firmware first-fault probe, and the TCG full-memory trace plugin. Not implemented: device model (R1), custom simulator (R2), MCP plugin (R3) — all 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/GREEN-EYE-ROADMAP.md`. +documented in `debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`. ## 6. When the development flag can be removed diff --git a/docs/05-operations/04-green-eye-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md index a9bf1dc..f12230a 100644 --- a/docs/05-operations/04-green-eye-user-guide.md +++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md @@ -1,21 +1,21 @@ -# green-eye User Guide (experimental) +# risc-v-gsp-rm-debugger User Guide (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** -> green-eye is the development environment for running GSP/uproc firmware +> 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; > interfaces and file formats may change without notice. For incident response > procedures see the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md). -This guide is the single front door for a new user: what green-eye is, how to +This guide is the single front door for a new user: what risc-v-gsp-rm-debugger is, how to get a first recorded run in ten minutes, which tool to use for which task, how to treat sessions as evidence, and what to do when something is wrong. The authoritative details live in the tool's own documentation set ([documentation map](#10-documentation-map)). -## 1. What green-eye is +## 1. What risc-v-gsp-rm-debugger is -green-eye runs GSP/uproc firmware in a controllable machine, instruments it +risc-v-gsp-rm-debugger runs GSP/uproc firmware in a controllable machine, instruments it with Frida-like primitives, records a durable session, changes the machine's inputs (including injected code), and compares runs so that emulation changes in `open-iov-vfio` land with evidence instead of anecdotes. @@ -28,9 +28,9 @@ in `open-iov-vfio` land with evidence instead of anecdotes. | A static/dynamic join for Ghidra | A decompiler or a CUDA-corpus replacement | | An automation layer (harnesses, MCP, CI) | A fuzzing service against hardware; simulator/re-hosted code only | -Ghidra answers *what is the code*; green-eye answers *what did it do*. Guest +Ghidra answers *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. Guest diagnostics answer *what did the driver request*; a supervised physical cycle -answers *what does silicon do*. green-eye makes the middle question repeatable +answers *what does silicon do*. risc-v-gsp-rm-debugger makes the middle question repeatable and safe. ## 2. Ten-minute quickstart @@ -42,14 +42,14 @@ kernel module are touched. ```bash cd open-iov/debug/risc-v-gsp-rm-vm -./greeneye.sh info # environment check: QEMU, toolchain, paths +./risc-v-gsp-rm-debugger.sh info # environment check: QEMU, toolchain, paths make demo && make sdk # build the bundled RV64 uproc demo and injection SDK -./greeneye.sh demo # canned run: boot, hooks, watchpoints, session -./greeneye.sh analyze dumps/<printed-session-dir> +./risc-v-gsp-rm-debugger.sh demo # canned run: boot, hooks, watchpoints, session +./risc-v-gsp-rm-debugger.sh analyze dumps/<printed-session-dir> -./greeneye.sh probe # real GSP image: report the first divergence -./greeneye.sh inject # load and invoke a position-independent service +./risc-v-gsp-rm-debugger.sh probe # real GSP image: report the first divergence +./risc-v-gsp-rm-debugger.sh inject # load and invoke a position-independent service ``` What "good" looks like: @@ -105,7 +105,7 @@ Instructions between stops are invisible unless a trace is on: the TCG plugin ### 3.3 Fidelity levels (what a result can mean) -| Level | Property | green-eye today | +| Level | Property | risc-v-gsp-rm-debugger today | |---|---|---| | **L0** | instruction semantics | high (QEMU TCG, same ISA family) | | **L1** | memory behaviour | high for RAM-resident code, conditional on mapping | @@ -114,7 +114,7 @@ Instructions between stops are invisible unless a trace is on: the TCG plugin A simulator observation is evidence about the firmware, not about silicon; anything that would change the product is reproduced on a physical/vfio-mdev -reference first. Never quote a green-eye session for timing, interrupt or +reference first. Never quote a risc-v-gsp-rm-debugger session for timing, interrupt or security claims. ### 3.4 A session is the unit of work @@ -138,7 +138,7 @@ evidence. Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. -### 4.1 CLI (`./greeneye.sh`) +### 4.1 CLI (`./risc-v-gsp-rm-debugger.sh`) | Command | One-line purpose | |---|---| @@ -187,15 +187,15 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. | Task | Tool | Notes | |---|---|---| -| "Does this run?" / first divergence of a raw image | `./greeneye.sh probe` | no device model: expected early fault is data | +| "Does this run?" / first divergence of a raw image | `./risc-v-gsp-rm-debugger.sh probe` | no device model: expected early fault is data | | "What does this firmware do on this stimulus?" | `record` / `run` + `analyze` | fixed stimulus, bounded budgets, hooks/watchpoints | | "Which command IDs exist / what is undiscovered?" | `harness/control_discovery.py` | fresh session per probe; deterministic seed | | "Is this function reachable, and how?" | `harness/reach.py` | `auto|stimulus|trigger|run|call`; emits a replayable probe spec | -| "What changed between two firmware versions?" | `harness/version_diff.py`, `./greeneye.sh compare` | static inventory + dynamic profile | +| "What changed between two firmware versions?" | `harness/version_diff.py`, `./risc-v-gsp-rm-debugger.sh compare` | static inventory + dynamic profile | | "Does the new firmware move behaviour or code?" | `harness/version_diff.py` + docs/14 decision table | code vs behaviour classification | | "Prove an error path / fail-closed rule" | `harness/mutation_harness.py` | simulator only; seeded and replayable | -| "Prototype an RM service before product code" | `sdk/` + `./greeneye.sh inject` | PIC blob; direct and mailbox paths | -| "Join Ghidra static addresses to runtime hits" | `./greeneye.sh ghidra` + Java bridges | localhost only; no auth | +| "Prototype an RM service before product code" | `sdk/` + `./risc-v-gsp-rm-debugger.sh inject` | PIC blob; direct and mailbox paths | +| "Join Ghidra static addresses to runtime hits" | `./risc-v-gsp-rm-debugger.sh ghidra` + Java bridges | localhost only; no auth | | "What does a control reply look like on real RM?" | `rmharness/harness.sh … rmtool` | read-only host oracle; safe beside a CUDA job | | "Explore MMIO the firmware touches first" | `probe` → `python3 -m greeneye.device_map` | versioned JSON; feeds the device model | | "Triage a release end to end" | `harness/ci_release.py` | always `--dry-run` first | @@ -238,15 +238,15 @@ authoritative for every claim. ```bash cd debug/risc-v-gsp-rm-vm make demo -./greeneye.sh demo # prints the session directory -./greeneye.sh analyze dumps/<session> # symbol-annotated report +./risc-v-gsp-rm-debugger.sh demo # prints the session directory +./risc-v-gsp-rm-debugger.sh analyze dumps/<session> # symbol-annotated report ``` ### 7.2 Probe a new firmware image ```bash -./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json -./greeneye.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<ver>.json --record +./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json +./risc-v-gsp-rm-debugger.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<ver>.json --record python3 harness/version_diff.py --old <old> --new <new> --out dumps/vdiff-<ver> \ --old-symbols symbols-<old>.json --new-symbols symbols-<new>.json ``` @@ -280,7 +280,7 @@ python3 harness/portability_matrix.py \ ```bash make -C sdk make -C sdk relocs -./greeneye.sh inject --service sdk/build/injected_demo.elf --cmd 1 --arg0 0x41 --arg1 0x42 +./risc-v-gsp-rm-debugger.sh inject --service sdk/build/injected_demo.elf --cmd 1 --arg0 0x41 --arg1 0x42 ``` The direct call is the unit test; the mailbox call is the integration test. @@ -290,7 +290,7 @@ Both are recorded. ```bash # terminal 1 -./greeneye.sh ghidra --kernel <elf> --bridge-port 7000 +./risc-v-gsp-rm-debugger.sh ghidra --kernel <elf> --bridge-port 7000 # terminal 2 (Ghidra headless) $GHIDRA/support/analyzeHeadless <proj> <name> -process <program> -noanalysis \ -scriptPath open-iov/debug/risc-v-gsp-rm-vm/ghidra \ @@ -325,7 +325,7 @@ python3 plugins/mcp_server.py --stdio --backend native --record ### 7.11 First-touch device map ```bash -./greeneye.sh probe <fwimage> --record +./risc-v-gsp-rm-debugger.sh probe <fwimage> --record python3 -m greeneye.device_map harvest dumps/<probe-session> --out dumps/<ver>-device-map.json python3 -m greeneye.device_map show dumps/<ver>-device-map.json ``` @@ -339,10 +339,10 @@ python3 -m greeneye.device_map show dumps/<ver>-device-map.json | `Address already in use` on a bridge/trace port | stale bridge or another session | choose another `--bridge-port`; check `pgrep -fa greeneye` and `pgrep -fa qemu-system-riscv64` | | QEMU survives Ctrl-C of a script | `launch` keeps the target alive by design | close the session or stop the reported PID; do not kill an unrelated QEMU | | Session analyzer shows no hits/events | recording off, or the stimulus never ran | use the CLI (records by default); check hooks/watchpoints with a known symbol (`rpc_sum`) | -| `NameError: __file__` in `run` scripts | script invoked outside `greeneye.sh run` | run through `./greeneye.sh run`, keep scripts inside the tool tree | +| `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 | `./greeneye.sh info` shows resolved paths; bad symbol DBs fail with a clear error | +| `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 | | 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 | @@ -412,7 +412,7 @@ Tool documentation (`debug/risc-v-gsp-rm-vm/docs/`): [00 overview](../../debug/r [27 tool audit](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md), [28 porting automation](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md), [29 packaging and trialing](../../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md), and the -[long-term roadmap](../../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md). +[long-term roadmap](../../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). Project documentation: 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 3c5d1aa..6c5bc59 100644 --- a/docs/06-portability/03-device-validation-and-porting-sequence.md +++ b/docs/06-portability/03-device-validation-and-porting-sequence.md @@ -149,7 +149,7 @@ sequenceDiagram participant H as Ops host participant D as Device under test participant G as Guest VM (stock driver) - participant S as green-eye harness + participant S as risc-v-gsp-rm-debugger harness participant E as Evidence store O->>H: approve one supervised cycle (reboot/bind approval) @@ -217,7 +217,7 @@ as a gap, never "fixed" in the product from simulator evidence alone * Current ops entry point and host procedures: [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md), the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md), and the - [green-eye user guide](../05-operations/04-green-eye-user-guide.md) + [risc-v-gsp-rm-debugger user guide](../05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) * Porting automation (sweep + device scaffold, bundles, M1–M6): [`../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md`](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md) * Playbooks and porting guide: diff --git a/docs/06-portability/hardware-software-matrix.md b/docs/06-portability/hardware-software-matrix.md index 8fca9e9..857d752 100644 --- a/docs/06-portability/hardware-software-matrix.md +++ b/docs/06-portability/hardware-software-matrix.md @@ -70,21 +70,21 @@ so new transports are a small, isolated implementation. 3. Record the differences; prefer configuration over code. 4. Publish the profile, the evidence, and any workarounds. -**Green-eye portability pipeline (experimental).** +**Risc-V GSP-RM debugger portability pipeline (experimental).** -<!-- change (2026-10-02): add the green-eye portability pipeline to the new-GPU +<!-- change (2026-10-02): add the risc-v-gsp-rm-debugger portability pipeline to the new-GPU procedure and point at the RUNBOOK/user guide; additive only. --> Before the profile change lands, run the firmware-side pipeline from `debug/risc-v-gsp-rm-vm/` and attach its output: -`./greeneye.sh probe <image> --symbols <db> --record` for the first-touch map; -`./greeneye.sh symbols export ...` for a provenance-carrying symbol DB; +`./risc-v-gsp-rm-debugger.sh probe <image> --symbols <db> --record` for the first-touch map; +`./risc-v-gsp-rm-debugger.sh symbols export ...` for a provenance-carrying symbol DB; `python3 harness/portability_matrix.py --target <reference> --target <candidate> --out dumps/matrix-<candidate>` for per-pair sessions and `compare` reports; then classify profile-versus-logic deltas with the decision table in `debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md` §4.1. The command-level walkthrough is in the -[green-eye user guide](../05-operations/04-green-eye-user-guide.md); the +[risc-v-gsp-rm-debugger user guide](../05-operations/04-risc-v-gsp-rm-debugger-user-guide.md); the incident procedure, evidence expectations and rollback rules are in the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S5. @@ -144,7 +144,7 @@ the profile files, not the profile schema. **Evidence expectations for adding support.** <!-- change (2026-10-02): state the evidence required before a combination is -entered in the matrix, and link the RUNBOOK bundle checklist and green-eye +entered in the matrix, and link the RUNBOOK bundle checklist and risc-v-gsp-rm-debugger portability pipeline; additive only. --> A combination is entered in the matrix only with: the profile fields recorded; @@ -158,7 +158,7 @@ combination stays **Target** or **Experimental**. The full bundle checklist and fault tree are in the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) §6–§7; the pipeline commands are in the -[green-eye user guide](../05-operations/04-green-eye-user-guide.md). +[risc-v-gsp-rm-debugger user guide](../05-operations/04-risc-v-gsp-rm-debugger-user-guide.md). ### 6.1 Userspace driver facts diff --git a/docs/07-developers/02-development-and-analysis-environment.md b/docs/07-developers/02-development-and-analysis-environment.md index 114345b..4bff443 100644 --- a/docs/07-developers/02-development-and-analysis-environment.md +++ b/docs/07-developers/02-development-and-analysis-environment.md @@ -1,8 +1,8 @@ -# Development and analysis environment: Ghidra, green-eye and the Open-IOV toolchain +# Development and analysis environment: Ghidra, risc-v-gsp-rm-debugger and the Open-IOV toolchain > The single front door to the environment an Open-IOV developer works in: > the host stack, the guest diagnostics, the CUDA userspace and GSP firmware -> Ghidra corpora, the host RM tooling, green-eye, CI and MCP. Each component +> Ghidra corpora, the host RM tooling, risc-v-gsp-rm-debugger, CI and MCP. Each component > links to the document that specifies it; this page is the map, not a > duplicate of the manuals. @@ -21,7 +21,7 @@ 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 green-eye toolchain is **in development and not +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 [`05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md) and the tool's own @@ -45,14 +45,14 @@ flowchart TB GHFW["tools/ghidra + firmware/57X-GSP/<ver><br/>GSP firmware Ghidra projects"] GHCUDA["userspace/cuda Ghidra corpus<br/>+ analysis tools"] end - subgraph DYN["Dynamic firmware analysis - green-eye"] + subgraph DYN["Dynamic firmware analysis - risc-v-gsp-rm-debugger"] GE["Session: hooks, watchpoints, memory,<br/>call, run_until, record"] GEB["Backends: QEMU-RSP + native RV64IMAC"] GEH["harness/, injection SDK,<br/>Ghidra bridges, device maps"] RMH["rmharness host captures"] end subgraph AUTO["Automation"] - CI[".github/workflows/ci.yml<br/>.github/workflows/greeneye.yml"] + CI[".github/workflows/ci.yml<br/>.github/workflows/risc-v-gsp-rm-debugger.yml"] MCP["plugins/mcp_server.py<br/>agent tool surface"] end end @@ -76,7 +76,7 @@ flowchart TB | CUDA static corpus | what is `libcuda` doing, and what changed? | `userspace/cuda/READ-ME-FIRST.md` | | GSP firmware static | what does the firmware image contain? | `tools/ghidra/`, `firmware/57X-GSP/<ver>/` | | Host RM oracle | what does real RM report on this GPU? | `tools/rmtool`, `tools/rmtop`, `rmharness/` | -| Dynamic firmware | what did the firmware server actually do? | `debug/risc-v-gsp-rm-vm/greeneye.sh` | +| Dynamic firmware | what did the firmware server actually do? | `debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh` | | CI / agent | did the broad suite pass; can an agent drive it? | `.github/workflows/`, `plugins/mcp_server.py` | ## 3. Host stack: KVM, QEMU, VFIO and the module @@ -147,7 +147,7 @@ low. Current tooling translates; re-derive old conclusions |---|---| | `tools/cudatool.py` | exports/FDEs/wrappers, `info`, `nearest`, `crash`, `delta`, `fdematch` | | `tools/callwalk.py` | callers/callees/chains over `callgraph.tsv` | -| `tools/diff_corpus.py` | corpus diff across driver versions (match discipline reused by green-eye version diffs) | +| `tools/diff_corpus.py` | corpus diff across driver versions (match discipline reused by risc-v-gsp-rm-debugger version diffs) | | `tools/name_candidates.py`, `subsystem_digest.py` | name candidates and per-subsystem call-tree digests | | `tools/ghidra_*.sh`, `tools/ghidra/` | headless analysis, decompile-at, index/name-map export, merge | | `tools/annotate_corpus.py` | apply the name map to the corpus | @@ -173,7 +173,7 @@ firmware analysis pipeline is driven from `tools/ghidra/`: The upgrade procedure — acquire, version, decompile, diff the RPC dispatcher, update the version surface, validate, roll back safely — is [`05-operations/02` §4.1](../05-operations/02-debugging-and-maintenance-workflows.md); -green-eye adds a runtime layer on top in +risc-v-gsp-rm-debugger adds a runtime layer on top in [`debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md`](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md). ## 7. Host RM oracle: rmtool, rmtop, rmq and rmharness @@ -182,7 +182,7 @@ green-eye 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. Green-eye'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 @@ -197,7 +197,7 @@ Details: `tools/rmtool/` sources, [`rmharness/README.md`](../../debug/risc-v-gsp the tool doc [`17-RM-HARNESS.md`](../../debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md), and the metric use (M1/M6) in `docs/06-ACCURACY.md`. -## 8. green-eye and its subsystems +## 8. risc-v-gsp-rm-debugger and its subsystems `debug/risc-v-gsp-rm-vm/` is the dynamic firmware environment. Its subsystem map: `greeneye/` (Session, memory, symbols, structs, probes, record, analyze, @@ -210,9 +210,9 @@ plugins, Ghidra bridges, injection, device map, native backend), `sim/` ```bash cd debug/risc-v-gsp-rm-vm make demo sdk -./greeneye.sh info && ./greeneye.sh demo -./greeneye.sh probe # real fwimage: first divergence, honestly bounded -./greeneye.sh analyze dumps/<session> +./risc-v-gsp-rm-debugger.sh info && ./risc-v-gsp-rm-debugger.sh demo +./risc-v-gsp-rm-debugger.sh probe # real fwimage: first divergence, honestly bounded +./risc-v-gsp-rm-debugger.sh analyze dumps/<session> ``` The full architecture and API surfaces are @@ -220,13 +220,13 @@ The full architecture and API surfaces are purpose/status is [`05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md); the long-term program is -[`GREEN-EYE-ROADMAP.md`](../../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md). +[`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). ## 9. CI and MCP * **Project CI**: `.github/workflows/ci.yml` builds the kernel module, userspace and host tests on the main tree. -* **Tool CI**: `.github/workflows/greeneye.yml` installs +* **Tool CI**: `.github/workflows/risc-v-gsp-rm-debugger.yml` installs `qemu-system-misc clang lld-18`, builds `sdk`/`demo`, and runs the tool unit tests (`python3 -m unittest discover -s tests -t .`) on pushes/PRs touching `debug/risc-v-gsp-rm-vm/**` or `tools/rm*/**`. No secrets, hardware or guest. @@ -257,11 +257,11 @@ the long-term program is | `rmtop` | ncurses dashboard; `--once` for capture | human overview / session capture | `tools/rmtop/` | [`17`](../../debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md) | | `rmq` | device-info tables (unmodified) | TU104 static data queries | `tools/rmq/` | [`17`](../../debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md) | | `rmharness` | capture host oracle runs into sessions | pairing real RM data with a sim session | `debug/risc-v-gsp-rm-vm/rmharness/` | [`rmharness/README`](../../debug/risc-v-gsp-rm-vm/rmharness/README.md) | -| green-eye CLI | session lifecycle, probe, record, analyze, compare, inject, Ghidra | all dynamic firmware questions | `debug/risc-v-gsp-rm-vm/greeneye.sh` | [`00`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md), [`02`](../../debug/risc-v-gsp-rm-vm/docs/02-USAGE.md) | -| green-eye Python API | scripted instrumentation and injection | repeatable/CI-able experiments | `greeneye/`, `examples/` | [`03`](../../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md) | -| green-eye Ghidra bridge | run-until/breakpoints from the decompiler | static↔dynamic address joins | `ghidra/`, `greeneye/gdbridge.py` | [`05`](../../debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md), [`13`](../../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md) | +| risc-v-gsp-rm-debugger CLI | session lifecycle, probe, record, analyze, compare, inject, Ghidra | all dynamic firmware questions | `debug/risc-v-gsp-rm-vm/risc-v-gsp-rm-debugger.sh` | [`00`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md), [`02`](../../debug/risc-v-gsp-rm-vm/docs/02-USAGE.md) | +| risc-v-gsp-rm-debugger Python API | scripted instrumentation and injection | repeatable/CI-able experiments | `greeneye/`, `examples/` | [`03`](../../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md) | +| risc-v-gsp-rm-debugger Ghidra bridge | run-until/breakpoints from the decompiler | static↔dynamic address joins | `ghidra/`, `greeneye/gdbridge.py` | [`05`](../../debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md), [`13`](../../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md) | | injection SDK | PIC RV64 service blobs + ABI | prototyping a service or engine | `sdk/`, `greeneye/inject.py` | [`12`](../../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md) | -| green-eye harness | matrix, mutation, discovery, reach, version diff, release bundle, demos | porting, regression, evidence packs | `debug/risc-v-gsp-rm-vm/harness/` | [`18`](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md), [`19`](../../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md), [`21`](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) | +| risc-v-gsp-rm-debugger harness | matrix, mutation, discovery, reach, version diff, release bundle, demos | porting, regression, evidence packs | `debug/risc-v-gsp-rm-vm/harness/` | [`18`](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md), [`19`](../../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md), [`21`](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) | | native simulator + trace | deterministic RV64IMAC + exec/access trace | speed/determinism experiments | `sim/`, `greeneye/sim_backend.py` | [`16`](../../debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md) | | device map | first-touch MMIO data + lenient mode | device-model bring-up | `greeneye/device_map.py` | [`24`](../../debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md) | | TCG trace plugin | full instruction/memory JSONL trace | coverage map when hooks are not enough | `qemu/greeneye_trace.c` | [`qemu/README.md`](../../debug/risc-v-gsp-rm-vm/qemu/README.md) | @@ -279,7 +279,7 @@ flowchart LR A1["CUDA corpus + GSP firmware projects"] --> A2["name transfer, corpus diff,<br/>symbol inventory diff"] A2 --> A3["hypothesis: dispatch tables,<br/>call paths, data layouts"] end - subgraph DYN["Dynamic loop (green-eye)"] + subgraph DYN["Dynamic loop (risc-v-gsp-rm-debugger)"] B1["Session + injection on the firmware"] --> B2["observe, record, compare<br/>sessions"] B2 --> B3["evidence: hits, watch PCs,<br/>written pages, reply values"] end @@ -293,13 +293,13 @@ flowchart LR * **Static loop**: import the binary/version into Ghidra, transfer the name map (`cudatool.py delta`/`fdematch` for CUDA; `diff_gsp_firmware.py` and the RPC map for firmware), diff the corpus, and read the changed functions. -* **Dynamic loop**: boot the firmware in green-eye, instrument it, record a +* **Dynamic loop**: boot the firmware in risc-v-gsp-rm-debugger, instrument it, record a session, compare against a reference, and attach the session as evidence. * **Interlock**: a Ghidra symbol/address is resolved into the runtime through a symbol DB with the right bias; a runtime hit or fault PC is exported back (`export_hits`) and annotated into the project (`MarkGreenEyeHits.java`); `corpus_location()` maps a hit to its decompiled - body when the index carried `bucket:line`. See the green-eye + body when the index carried `bucket:line`. See the risc-v-gsp-rm-debugger [`05`](../../debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md), [`13`](../../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md) and [`26` §7](../../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md). @@ -311,11 +311,11 @@ 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); green-eye [`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); green-eye [`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); green-eye [`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 green-eye session | [`05-operations/01`](../05-operations/01-performance-correctness-security.md); green-eye [`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 | green-eye [`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) | +| 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 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) | The fast pipeline for a GSP version is: `harness/version_diff.py` → `harness/portability_matrix.py` → `harness/mutation_harness.py`, wrapped by @@ -349,7 +349,7 @@ dynamic session disposes, and physical confirmation gates any product change. → this document → the subsystem doc for what you will touch. * **CUDA bring-up**: [`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md) → `docs/01`, `docs/03`, `docs/05` → `docs/22` for porting. -* **Firmware/green-eye**: [`05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md) +* **Firmware/risc-v-gsp-rm-debugger**: [`05-operations/03-risc-v-gsp-rm-vm.md`](../05-operations/03-risc-v-gsp-rm-vm.md) → tool [`00`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md), [`26`](../../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md), then [`03`](../../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md), @@ -358,7 +358,7 @@ dynamic session disposes, and physical confirmation gates any product change. * **Host stack / VM**: [`03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md) and [`05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md). * **Portability**: [`06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md) - plus green-eye `docs/07` and `docs/22`. + plus risc-v-gsp-rm-debugger `docs/07` and `docs/22`. Every path in this document was verified at the time of writing; when a tool moves, update this table first — it is the front door. diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index 78100c4..b99613e 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/` (green-eye) | **# 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) | **# 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)) | | `wiki/` documents | protocol and firmware deep dives | ## 5. Landing a change diff --git a/docs/README.md b/docs/README.md index 77f4069..f0849fb 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 (green-eye, experimental)](05-operations/03-risc-v-gsp-rm-vm.md) — **# TOOL IN DEVELOPMENT - NOT READY YET!** | developers, analysts | 15 min | -| 21 | [green-eye user guide (experimental)](05-operations/04-green-eye-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) — **# 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 | | 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 | @@ -183,7 +183,7 @@ Read in order if you are new. Jump directly if you know what you need. | 26 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min | | 27 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference | -<!-- change (2026-10-02): insert the green-eye user guide and the Open-IOV +<!-- change (2026-10-02): insert the risc-v-gsp-rm-debugger user guide and the Open-IOV Defensive Operations Runbook into the reading list; renumber rows 21-24 to 23-26; additive only. --> @@ -199,10 +199,10 @@ execution, multi-VM, 3D, performance come first). > [`tools/`](tools/README.md) (for example `rmtool.md` and `rmtop.md`) are > being expanded; until they are complete, start with the > [Defensive Operations Runbook](RUNBOOK.md) and the -> [green-eye user guide](05-operations/04-green-eye-user-guide.md). +> [risc-v-gsp-rm-debugger user guide](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md). <!-- change (2026-10-02): state that the per-tool documentation section is -under development and point readers at the RUNBOOK and the green-eye user +under development and point readers at the RUNBOOK and the risc-v-gsp-rm-debugger user guide; additive only. --> Deep-dive material lives in [`../wiki/`](../wiki/README.md) (firmware @@ -218,12 +218,12 @@ The pre-reboot flat documents have been merged into this tree and removed [`05-operations/02-debugging-and-maintenance-workflows.md`](05-operations/02-debugging-and-maintenance-workflows.md) * defensive operations: incident scenarios, the OODA ordering, evidence bundles and the escalation tree → - [`RUNBOOK.md`](RUNBOOK.md); the green-eye quickstart, tool chooser and + [`RUNBOOK.md`](RUNBOOK.md); the risc-v-gsp-rm-debugger quickstart, tool chooser and troubleshooting → - [`05-operations/04-green-eye-user-guide.md`](05-operations/04-green-eye-user-guide.md) + [`05-operations/04-risc-v-gsp-rm-debugger-user-guide.md`](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) <!-- change (2026-10-02): point the post-merge document map at the new RUNBOOK -and green-eye user guide; additive only. --> +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` diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index 79c1735..4b11dfa 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -6,7 +6,7 @@ > coordinating with us; any of them can break the emulation while the others > stand still. This runbook is the ordered response. > -> **Related:** [green-eye user guide](05-operations/04-green-eye-user-guide.md) +> **Related:** [risc-v-gsp-rm-debugger user guide](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) > · [GSP in a RISC-V VM (experimental)](05-operations/03-risc-v-gsp-rm-vm.md) > · [Debugging and maintenance workflows](05-operations/02-debugging-and-maintenance-workflows.md) > · [Hardware and software matrix](06-portability/hardware-software-matrix.md) @@ -14,7 +14,7 @@ > · [Developer onboarding and standards](07-developers/onboarding-and-standards.md) > · [Engineering operations](eng-ops.md) > -> **# TOOL IN DEVELOPMENT - NOT READY YET!** The green-eye tooling cited here +> **# 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. @@ -51,7 +51,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.** green-eye 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 in-development banner on tool docs until the acceptance list passes. | | 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,8 +65,8 @@ 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" | -| **green-eye 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 | -| **CI/release maintainer** | `harness/version_diff.py`, `harness/ci_release.py`, `greeneye.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 | +| **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 | +| **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 | | **Docs steward** | this tree | enforces change notes, link checks and doc-map updates; retires stale claims | docs are part of "done" | @@ -82,7 +82,7 @@ with a summary alone. | Item | Cadence | Procedure | Pass condition | |---|---|---|---| -| Demo golden session | every tool change and weekly | `./greeneye.sh demo` and compare against the archived session/expected events | UART banner and control-block liveness present; hook/watch/breakpoint sequence coherent | +| Demo golden session | every tool change and weekly | `./risc-v-gsp-rm-debugger.sh demo` and compare against the archived session/expected events | UART banner and control-block liveness present; hook/watch/breakpoint sequence coherent | | Portability self-comparison | per PR touching `harness/`, `greeneye/`, `sim/` | `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` | `all_zero` deltas in `portability-report.json` | | Mutation replay | per PR touching mutation/harness code | run `mutation_harness.py` twice with the same seed and budgets | `findings.jsonl` byte-identical | | Version-diff self-check | per release-triage change | `version_diff.py` old == new | zero symbol/probe/behavior deltas | @@ -115,7 +115,7 @@ Golden artifacts are append-only history: never edit a stored golden session | Dependency | Check | Action | |---|---|---| -| QEMU | `./greeneye.sh info`; run `make test` | install/renew `qemu-system-riscv64` (Ubuntu `qemu-system-misc`); set `GREENEYE_QEMU` if the binary is elsewhere | +| QEMU | `./risc-v-gsp-rm-debugger.sh info`; run `make test` | install/renew `qemu-system-riscv64` (Ubuntu `qemu-system-misc`); set `GREENEYE_QEMU` if the binary is elsewhere | | QEMU plugin API | `make -C qemu` after a QEMU upgrade | rebuild `qemu/greeneye-trace.so` against the vendored `qemu-plugin.h`; re-run a trace smoke | | Python | `python3 --version` (3.10+; stdlib only) | no pip packages required; keep plugins/harnesses stdlib-only | | clang/lld | `make demo`, `make sdk` | reinstall toolchain if the demo or SDK stops building | @@ -210,10 +210,10 @@ Scenarios are incidents to run, not roadmap claims. cd debug/risc-v-gsp-rm-vm # 1) symbol DBs, one per version -./greeneye.sh symbols export --index <export-VER.tsv> --bias 0 -o symbols-<VER>.json +./risc-v-gsp-rm-debugger.sh symbols export --index <export-VER.tsv> --bias 0 -o symbols-<VER>.json # 2) bounded probe of each image (records a session) -./greeneye.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<VER>.json --record +./risc-v-gsp-rm-debugger.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<VER>.json --record # 3) full old-vs-new triage (shape, symbols, corpus, probe, behavior, M1-M6) python3 harness/version_diff.py \ @@ -223,8 +223,8 @@ python3 harness/version_diff.py \ --out dumps/vdiff-<OLD>-<NEW> # 4) behaviour compare and canonical report -./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols -./greeneye.sh analyze dumps/<new-run> --symbols symbols-<NEW>.json +./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols +./risc-v-gsp-rm-debugger.sh analyze dumps/<new-run> --symbols symbols-<NEW>.json ``` ### S2 — New kernel driver / open-kernel-modules release @@ -301,7 +301,7 @@ python3 harness/control_discovery.py --out dumps/discovery-<VER> --seed <seed> python3 harness/reach.py --target <symbol> --method auto --out dumps/reach-<symbol> # symbol-attributed A/B -./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols ``` ### S4 — New CUDA userspace / toolkit interacting unexpectedly with the GSP @@ -319,7 +319,7 @@ python3 harness/reach.py --target <symbol> --method auto --out dumps/reach-<symb 1. Cheap triage first (minutes): `info` + `delta`; classify the port. 2. Measure name transfer before copying anything (`fdematch`). -3. Build the green-eye symbol DB for the new version so runtime addresses +3. Build the risc-v-gsp-rm-debugger symbol DB for the new version so runtime addresses resolve; spot-check transferred addresses. 4. Confirm dynamically: `cdt` with the ioctl tracer, then `ab.sh all`, against the **same** emulated firmware profile (anchor discipline). @@ -337,11 +337,11 @@ tools/cudatool.py fdematch <old>/run/libcuda.so.<old> <new>/run/libcuda.so.<new> tools/cudatool.py wrappers <new>/run/libcuda.so.<new> cd ../../debug/risc-v-gsp-rm-vm -./greeneye.sh symbols export \ +./risc-v-gsp-rm-debugger.sh symbols export \ --names ../../userspace/cuda/<new>/annotations/names.tsv \ --index ../../userspace/cuda/<new>/run/analysis/decompiled/decompiled_index.tsv \ --bias 0x100000 -o symbols-<new>.json -./greeneye.sh symbols resolve --db symbols-<new>.json 0x<transferred-addr> +./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-<new>.json 0x<transferred-addr> cd ../.. tools/cuda-ab/ab.sh all # host oracle + guest run + compare @@ -352,7 +352,7 @@ tools/cuda-ab/ab.sh all # host oracle + guest run + compare | Attribute | Detail | |---|---| | **Symptoms** | Probe first-touch addresses differ from the reference device; a firmware family/partition-manifest mismatch; ISA string differs (RV64GC vs RV64IMAC); aarch64 host reports `qemu-system-riscv64 not found`; PMU/SOE provisioning assumptions break. | -| **Detection** | `file`/`readelf` image shape; pairing check (family, FMC partition manifest, version string); probe first-touch diff; host tooling check (`./greeneye.sh info`); `rmtool` host-oracle inventory. | +| **Detection** | `file`/`readelf` image shape; pairing check (family, FMC partition manifest, version string); probe first-touch diff; host tooling check (`./risc-v-gsp-rm-debugger.sh info`); `rmtool` host-oracle inventory. | | **Evidence** | Device profile fields (PCI IDs, BARs, FB geometry, engine inventory, interrupt topology, ROM quirks); pairing notes; reference vs candidate first-touch maps; portability matrix report; physical validation record before any support claim. | | **Decision criteria** | Changed first-touch on profile registers → profile data, not logic. New firmware family/partition model → new family inputs, not a re-badged image. RV64GC or new CSRs → ISA/decoder work (S6). No physical validation → status stays Target/Experimental, never Supported. | | **Rollback** | Keep the reference device/firmware directories untouched; revert the candidate profile; a support claim is only removed with a matrix change note. | @@ -376,8 +376,8 @@ tools/cuda-ab/ab.sh all # host oracle + guest run + compare ```bash file <device-fwimage> && readelf -h <device-elf> && readelf -l <device-elf> cd debug/risc-v-gsp-rm-vm -./greeneye.sh info -./greeneye.sh probe <device-fwimage> --symbols symbols-<device>.json --record +./risc-v-gsp-rm-debugger.sh info +./risc-v-gsp-rm-debugger.sh probe <device-fwimage> --symbols symbols-<device>.json --record python3 harness/portability_matrix.py \ --target <reference-fwimage> --target <device-fwimage> \ --out dumps/matrix-<device> @@ -412,7 +412,7 @@ python3 harness/portability_matrix.py \ ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh probe <fwimage> --instructions <budget> --record +./risc-v-gsp-rm-debugger.sh probe <fwimage> --instructions <budget> --record python3 examples/scripts/sim_diff.py # requires QEMU; prints PARITY: OK on agreement make test ``` @@ -451,7 +451,7 @@ tools/rmtool/rmtool engine list cd debug/risc-v-gsp-rm-vm # snapshot the identity/static-config region before and after # (schema decode from the bundled/demo schema; real regions are version-keyed) -./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols ``` ### S8 — Encrypted/protected memory or protected instructions (measurement plan; non-claims) @@ -528,11 +528,11 @@ python3 -m greeneye.device_map show dumps/<ver>-device-map.json ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh probe <fwimage> --record +./risc-v-gsp-rm-debugger.sh probe <fwimage> --record python3 -m greeneye.device_map harvest dumps/<probe-session> --out dumps/<ver>-device-map.json python3 -m greeneye.device_map merge dumps/<ref>-device-map.json dumps/<ver>-device-map.json \ --out dumps/merged-device-map.json -./greeneye.sh compare dumps/<last-good-run> dumps/<stall-run> --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/<last-good-run> dumps/<stall-run> --symbols ``` ### S10 — Multi-version matrix operations and CI (RM 610 requires explicit human approval) @@ -635,7 +635,7 @@ Failure / new input observed | YES -> simulator evidence is a hypothesis only (P3/P4/P5); record the | fidelity gap; product change requires physical reproduction | -+- Does it reproduce under a fixed stimulus in green-eye? ++- Does it reproduce under a fixed stimulus in risc-v-gsp-rm-debugger? | NO -> widen the stimulus / capture the real trace before theorising; | absence of a hit is not proof of dead code | YES -> classify with the S1 decision table (code changed vs behaviour moved) @@ -668,20 +668,20 @@ Stop conditions (do not proceed, do not "temporarily" work around): | The input has not been hashed/versioned/paired | Every later claim is contaminated | S1 steps 1–3 | | RM 610 has no written approval | Hard gate | request approval with the readiness checklist | | The physical GPU is held by another job | Shared-oracle safety and fail-safe discipline | host-side read-only oracle (`rmtool gpu list`, `harness.sh`) | -| You need type recovery or decompilation | green-eye is dynamic ground truth, not a decompiler | Ghidra corpus and symbol tooling | -| You need guest-driver behaviour | green-eye observes firmware, not the guest | `tools/guest-diag/`, ioctl tracer | +| You need type recovery or decompilation | risc-v-gsp-rm-debugger is dynamic ground truth, not a decompiler | Ghidra corpus and symbol tooling | +| You need guest-driver behaviour | risc-v-gsp-rm-debugger observes firmware, not the guest | `tools/guest-diag/`, ioctl tracer | | A one-line question can be answered by `analyze` on an existing session | Do not produce new runs for no reason | reuse recorded sessions and `compare` | ## 9. One-page quick-reference decision tree | Symptom (first sign) | First command | Decision | Scenario | |---|---|---|---| -| New image/version appears | `./greeneye.sh symbols export ...` + `probe --record` | hash+pair first, then version diff | S1 | +| New image/version appears | `./risc-v-gsp-rm-debugger.sh symbols export ...` + `probe --record` | hash+pair first, then version diff | S1 | | OpenRM build breaks, `Unknown symbol` | `./scripts/build_nvidia_openrm.sh`; `dmesg` | glue-only vs interface change | S2 | | Control/ioctl inventory shifts | `python3 harness/control_discovery.py` | moved vs new logic | S3 | | `libcuda` bump / context failure | `tools/cudatool.py delta` + `fdematch` | patch / feature / reshuffle | S4 | | New device/architecture | `file`/`readelf`, `probe` | profile vs logic; physical validation for support | S5 | -| Illegal/unknown instruction | `./greeneye.sh probe --instructions N` | ISA/decoder; fidelity gap if native-only | S6 | +| Illegal/unknown instruction | `./risc-v-gsp-rm-debugger.sh probe --instructions N` | ISA/decoder; fidelity gap if native-only | S6 | | Identity/ROM fields differ | guest `lspci -vvv`, snapshot diff | consumed field → profile; else record | S7 | | Protected/encrypted state blocks | device map + lenient `mmio_log` | record fidelity gap; no extraction; no claims | S8 | | Early stall on PMU/SEC2/ACR/SOE | `probe --record` + device map | stub the missing exchange; gate security semantics | S9 | @@ -692,15 +692,15 @@ and never let the last step touch anything we do not own. ## 10. Related documentation -Green-eye suite (experimental, in development): +Risc-V GSP-RM debugger suite (experimental, in development): -* [green-eye user guide](05-operations/04-green-eye-user-guide.md) — what it +* [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; * [GSP in a RISC-V VM](05-operations/03-risc-v-gsp-rm-vm.md) — project-level purpose, status and limits; * [`debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md`](../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md) — tool status and doc map; -* [`debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md) +* [`debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) — H1–H7 program; * [`debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) — fidelity levels and the M1–M6 contract; diff --git a/docs/eng-ops.md b/docs/eng-ops.md index 117bd0c..4dd450e 100644 --- a/docs/eng-ops.md +++ b/docs/eng-ops.md @@ -13,7 +13,7 @@ binds both: evidence or it did not happen ([`onboarding-and-standards.md`](07-de | Governed here | Owned elsewhere (authoritative) | |---|---| -| 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)), green-eye ([`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)) | +| 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)) | @@ -21,7 +21,7 @@ binds both: evidence or it did not happen ([`onboarding-and-standards.md`](07-de **Explicitly out of scope.** (1) Security claims: the simulator and its device maps are study environments, never a confidentiality or isolation boundary ([`06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §6, -[`GREEN-EYE-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md) V4). +[`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) V4). (2) Timing claims: L2 is not modelled; order-of-events only ([`06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §2). (3) Shipping injected code: development-only, never a firmware patch, never in @@ -81,7 +81,7 @@ admissible. | 2 | Deeper / more correct analysis | watchpoints + TCG/native trace; capability inference ([`docs/14`](../debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md) §4.2) | attributed bytes/stores; M6 agreement; unexplained-delta count | RE | | 3 | Code-artifact porting time | `cudatool.py fdematch`, `diff_corpus.py`, `symbols export` | transfer rate per class; wall time old→new symbol DB; wrapper re-resolution errors | portability | | 4 | Bug-analysis time | `reach.py`, `run_until`/`call`, `ioctl_trace.c`; taxonomy in [`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md) §5 | crash/question → first evidence-backed answer (TTFA); supervised cycles avoided | adversarial | -| 5 | Development velocity on the simulated GSP | injection SDK; `greeneye.sh inject`; value demo s06 | seconds from service edit to direct+mailbox agreement; sessions per prototype | RE | +| 5 | Development velocity on the simulated GSP | injection SDK; `risc-v-gsp-rm-debugger.sh inject`; value demo s06 | seconds from service edit to direct+mailbox agreement; sessions per prototype | RE | | 6 | Correctness validation of virtualization | M1–M6 table, `compare`, golden sessions | M-table per change; rung ladder ([`05-operations/01`](05-operations/01-performance-correctness-security.md) §1) | correctness | | 7 | Performance analysis and improvement | A/B method, `tools/benchmark_infrastructure.sh`, simulator overhead ([`docs/25`](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) §6) | B/A % per metric; p50/p99 RPC; trace overhead; before/after same machine | performance | | 8 | Userspace/API compatibility friction | capability negotiation ([`../userspace/cuda/docs/04-virtualization-and-emulation.md`](../userspace/cuda/docs/04-virtualization-and-emulation.md) §1), symbol DB, ioctl diffs | controls with coherent replies vs observed; TTFA for a new capability bit; peer scenarios (RDMA guest, DPU/NIC/NVMe page sharing) counted only once a peer model exists | guest-compat | @@ -111,7 +111,7 @@ runs, cross-host comparisons, bare-metal-only data and simulator timing claims. **OODA reduction.** Every axis moves evidence through one of three loops. Each loop's compression is the project's program-level metric -([`GREEN-EYE-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md) success +([`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) success criteria), measured in [`docs/25`](../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md) §7: | Loop | Observe → Orient → Decide → Act | Compression metric | @@ -175,14 +175,14 @@ 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 | -| green-eye 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; 155-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 | | Device map (`greeneye-device-map/1`) | portability | docs 24; H2.1 first-touch | H2.2 model stops consuming maps | | `rmharness` + `rmtool`/`rmtop`/`rmq` | correctness, guest-compat | docs 17; M1/M6 reference captures | reference capture unused/unavailable | | MCP server + agent workflows | all loops | docs 15/20; release monitoring | write gating or audit trail removed | -| CI (`ci.yml`, `greeneye.yml`) | correctness | release-blocking tests | suite non-reproducible or skipped | +| CI (`ci.yml`, `risc-v-gsp-rm-debugger.yml`) | correctness | release-blocking tests | suite non-reproducible or skipped | ## 5. Workflow map: where each tool applies @@ -193,7 +193,7 @@ flowchart LR subgraph STATIC["Static"] GH["Ghidra CUDA corpus + GSP firmware"] end - subgraph DYN["Dynamic (green-eye, experimental)"] + subgraph DYN["Dynamic (risc-v-gsp-rm-debugger, experimental)"] GE["Session + QEMU/native backends"] HR["harness/*.py"] end @@ -203,7 +203,7 @@ flowchart LR RMH["rmtool/rmtop/rmq + rmharness"] end subgraph AUTO["Automation"] - CI["ci.yml / greeneye.yml"] + CI["ci.yml / risc-v-gsp-rm-debugger.yml"] MCP["MCP server + agents/cron"] end EVID["Evidence: sessions, reports, bundles"] @@ -302,19 +302,19 @@ flowchart LR | Loop | Entry points | Evidence | Gate | Detail | |---|---|---|---|---| -| Static RE | `tools/ghidra/*`, `userspace/cuda/tools/*`, `analyzeHeadless` | corpus TSVs, name map, symbol DB | addresses re-derived per build | [`userspace/cuda/docs/07`](../userspace/cuda/docs/07-version-upgrade-playbook.md), green-eye docs 05/13 | -| Dynamic RE | `greeneye.sh` probe/record/analyze/compare/inject/ghidra, Python `Session` | `greeneye-session/1` + `summary.md` | A/B pair; L2/L3 statement | [`26-ARCHITECTURE.md`](../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md) §11, [`11`](../debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md), [`12`](../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md), [`13`](../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md), [`14`](../debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md) §4.6, [`06`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §5 | +| Static RE | `tools/ghidra/*`, `userspace/cuda/tools/*`, `analyzeHeadless` | corpus TSVs, name map, symbol DB | addresses re-derived per build | [`userspace/cuda/docs/07`](../userspace/cuda/docs/07-version-upgrade-playbook.md), risc-v-gsp-rm-debugger docs 05/13 | +| Dynamic RE | `risc-v-gsp-rm-debugger.sh` probe/record/analyze/compare/inject/ghidra, Python `Session` | `greeneye-session/1` + `summary.md` | A/B pair; L2/L3 statement | [`26-ARCHITECTURE.md`](../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md) §11, [`11`](../debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md), [`12`](../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md), [`13`](../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md), [`14`](../debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md) §4.6, [`06`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §5 | | Porting | `version_diff.py`, `portability_matrix.py`, `mutation_harness.py`, `ci_release.py` | reports + `bundle-manifest.json` | every delta explained | [`07`](../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), [`22`](../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md), [`21`](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), runbook [`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md) §4.1 | | Performance | `benchmark_infrastructure.sh`, module counters, `vgpu_vm.py` | B/A table with environment | same-machine A/B; corpus green | [`05-operations/01`](05-operations/01-performance-correctness-security.md) §3 | | Correctness | `stack_manager.sh test`, `make tests`, `cuda_drv_test.c`, `cuda-ab` | rung + trace excerpts | no rung regression | [`05-operations/01`](05-operations/01-performance-correctness-security.md) §1–2 | -| CI | `.github/workflows/ci.yml`, `.github/workflows/greeneye.yml` | workflow logs | push/PR path triggers | [`21`](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) §5 | +| CI | `.github/workflows/ci.yml`, `.github/workflows/risc-v-gsp-rm-debugger.yml` | workflow logs | push/PR path triggers | [`21`](../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) §5 | | Guest-compat | `tools/guest-diag/*`, `cudatool.py`, `diff_corpus.py` | ioctl/control diff, corpus delta | stock guest only | [`READ-ME-FIRST.md`](../userspace/cuda/READ-ME-FIRST.md) | ## 6. Automation and agent invocation ```mermaid flowchart LR - PRE["Preflight: greeneye.sh info; RM610 gate"] --> DRY["ci_release.py --dry-run (plan only)"] + PRE["Preflight: risc-v-gsp-rm-debugger.sh info; RM610 gate"] --> DRY["ci_release.py --dry-run (plan only)"] DRY --> REAL["ci_release.py real run"] REAL --> VD["version_diff"] REAL --> PM["portability_matrix"] @@ -339,7 +339,7 @@ module or hardware. | `harness/control_discovery.py` | `python3 harness/control_discovery.py --surface demo --out dumps/disc --seed 7` | known IDs resolve; unknown/injected classes listed | RM surface exits cleanly until H1.3; misclassification or unreplayable probe | | `harness/reach.py` | `python3 harness/reach.py --target rpc_ping --method call --args 0x41 --out dumps/reach` | `reachable` with recorded route and args | timeout means "not under this stimulus", not unreachable | | `harness/ci_release.py` | dry-run first: `python3 harness/ci_release.py --old <old> --new <new> --out dumps/release --dry-run` | dry-run touches no target; real run writes the bundle | exit 1 step error, 2 tool error, 3 RM610 refusal; `skipped` is not `pass` | -| `greeneye.sh` | `./greeneye.sh info`/`probe`/`record`/`analyze`/`compare`/`inject` | session dir with `session.json` + `summary.md` | empty sessions or missed hooks; budgets required | +| `risc-v-gsp-rm-debugger.sh` | `./risc-v-gsp-rm-debugger.sh info`/`probe`/`record`/`analyze`/`compare`/`inject` | session dir with `session.json` + `summary.md` | empty sessions or missed hooks; budgets required | | `rmharness/harness.sh` | `./rmharness/harness.sh --session dumps/real -- rmtool engine list --format=json` | `rm_harness_run` event + stream blobs | read-only only; permission errors reported, never escalated | | `plugins/mcp_server.py` | `python3 plugins/mcp_server.py --stdio --record` | 24-tool JSON-RPC surface; read/observe default | stdout protocol-only; writes need `--allow-write`/`--allow-inject` | | `harness/value_demos/run_all.py` | `python3 harness/value_demos/run_all.py` | one `RESULT_JSON` per demo; suite ≤ 180 s | any demo `success: false`; re-run before quoting numbers | @@ -407,7 +407,7 @@ not a support claim. ```text dist/<pkg>/ README.md scenario, expected result, budgets, L2/L3 caveat - run.sh deterministic runner (greeneye.sh run + settle) + run.sh deterministic runner (risc-v-gsp-rm-debugger.sh run + settle) scenario.py fixed stimulus, fixed budgets, records a session firmware/<image> ELF or .fwimage, hash-pinned service/<service>.elf injected service (PIC, ABI v1), hash-pinned @@ -464,7 +464,7 @@ Everything here is **future** and off the critical path. Each capability enters the §2 process only when its near-term need is real and its gate is passed; details are tracked in the companion [`future-eng-ops.md`](future-eng-ops.md) (same directory) and -[`GREEN-EYE-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md) H5/H6. +[`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md) H5/H6. Deferred context: [`10-post-1.0/experimental-host-acceleration.md`](10-post-1.0/experimental-host-acceleration.md). | Frontier capability | Near-term need | Precondition / gate | Evaluation criterion (if funded) | @@ -507,7 +507,7 @@ that cannot state a benefit is rejected as overhead. ```bash python3 scripts/check-docs-links.py # repo root cd debug/risc-v-gsp-rm-vm && make demo sdk && make test # tool claims -./greeneye.sh info # environment +./risc-v-gsp-rm-debugger.sh info # environment ``` --- @@ -544,7 +544,7 @@ the rules win. | 5 | **Stop on hard signatures.** `board unresponsive`, `refusing claim`, `do not retry in this boot`, any panic/oops. | Do not write the device again in that boot; keep the locks; request reboot approval per rule 2. | | 6 | **Verify module identity before and after a cycle.** Record the built module's sha256 (and `srcversion`) before load and re-read it after unload. | A hash mismatch invalidates the cycle's evidence; stop and rebuild from the reviewed source. | | 7 | **A wedged device is left untouched for the reboot.** No `rmmod` retry loops, no bind/unbind experiments, no power-policy pokes. | The fail-safe (no rebind, D0 locks + runtime reference held, WPR2 up) is the designed resting state. | -| 8 | **Scope.** This part covers the claim/boot, rm-call ladder (host-side real submission), guest-memory forwarding, relay/fault-relay and release paths. Guest-facing emulation debugging is [`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md); firmware runtime study is [green-eye](05-operations/03-risc-v-gsp-rm-vm.md). | All other physical work belongs to the scenario owner named in §14. | +| 8 | **Scope.** This part covers the claim/boot, rm-call ladder (host-side real submission), guest-memory forwarding, relay/fault-relay and release paths. Guest-facing emulation debugging is [`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md); firmware runtime study is [risc-v-gsp-rm-debugger](05-operations/03-risc-v-gsp-rm-vm.md). | All other physical work belongs to the scenario owner named in §14. | ### 10.2 Build and load order, and the module-parameter matrix @@ -804,7 +804,7 @@ bump, device/ISA/ROM change, protected state, matrix/CI) are owned by | Debugging context | Owning document | |---|---| | Emulated-driver debugging (guest driver vs the emulated GSP-RM) | [`05-operations/02`](05-operations/02-debugging-and-maintenance-workflows.md) §1–3, §5 (observability, captures, gdbstub, failure taxonomy). | -| Firmware runtime (GSP/uproc in a RISC-V VM, hooks/watchpoints/sessions) | [`05-operations/03`](05-operations/03-risc-v-gsp-rm-vm.md) and the [green-eye user guide](05-operations/04-green-eye-user-guide.md) (experimental). | +| Firmware runtime (GSP/uproc in a RISC-V VM, hooks/watchpoints/sessions) | [`05-operations/03`](05-operations/03-risc-v-gsp-rm-vm.md) and the [risc-v-gsp-rm-debugger user guide](05-operations/04-risc-v-gsp-rm-debugger-user-guide.md) (experimental). | | Live physical backend (claim/boot, ladder, forwarding, relay, release) | **This Part II.** | | 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). | diff --git a/docs/future-eng-ops.md b/docs/future-eng-ops.md index 0aa961a..00bffba 100644 --- a/docs/future-eng-ops.md +++ b/docs/future-eng-ops.md @@ -1,7 +1,7 @@ -# Future engineering operations: green-eye capabilities not yet earning their keep +# Future engineering operations: risc-v-gsp-rm-debugger capabilities not yet earning their keep > Companion to [`eng-ops.md`](eng-ops.md). That document records what the -> project uses now; this one records green-eye capabilities that are built but +> project uses now; this one records risc-v-gsp-rm-debugger capabilities that are built but > unused, partially used, planned or research, each tied to an impending > project need, scoped explicitly, and carrying an evaluation that can fail — > plus a kill criterion if it never pays off. Nothing here is a product @@ -9,7 +9,7 @@ > the physical-confirmation rules of > [`06-ACCURACY.md`](../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md). -Status snapshot: 2026-10-02. Sources are the green-eye roadmap, tool docs +Status snapshot: 2026-10-02. Sources are the risc-v-gsp-rm-debugger roadmap, tool docs 16–27, the `harness/` entry points and the tool audit (doc 27). The tool tree is development-only: never shipped, never a dependency of `open-iov-vfio`, never present in a guest. RM 610 work is gated by human approval @@ -151,10 +151,10 @@ F11, F13). Each item carries exactly one evaluation criterion. | Field | Detail | |---|---| -| **Status** | `partially used`. `sim_bench.py`, the trace-overhead measurements (docs/16 §1.1a, docs/25 §6) and the product A/B methodology in [`01-performance-correctness-security.md`](05-operations/01-performance-correctness-security.md) §3 exist. There is no green-eye path that profiles a product run off-hardware or produces an automated before/after report. | +| **Status** | `partially used`. `sim_bench.py`, the trace-overhead measurements (docs/16 §1.1a, docs/25 §6) and the product A/B methodology in [`01-performance-correctness-security.md`](05-operations/01-performance-correctness-security.md) §3 exist. There is no risc-v-gsp-rm-debugger path that profiles a product run off-hardware or produces an automated before/after report. | | **Need** | Every emulation change is measured against docs/05 targets (e.g. init within 2× native) using physical cycles and a manual harness; pre-screening structural regressions off-hardware would reduce failed physical cycles. M7 timing is never claimed, so the useful signal is structural (instruction/event counts, session bytes, written pages), not wall clock. | | **Scope** | Does capture deterministic structural metrics per session and diff them before/after with an explicit fidelity label; does not make timing or wall-clock claims about silicon, does not replace the physical benchmark in docs/05. | -| **Evaluation** | Metric: fraction of perf-sensitive emulation changes that receive a green-eye before/after report before the physical benchmark. Baseline: 0. Threshold: five consecutive changes carry a report, and structural regressions ≥10% are flagged before the hardware run. Kill: if reports agree with the physical benchmark less than 50% of the time, retire them to debug annotations only. | +| **Evaluation** | Metric: fraction of perf-sensitive emulation changes that receive a risc-v-gsp-rm-debugger before/after report before the physical benchmark. Baseline: 0. Threshold: five consecutive changes carry a report, and structural regressions ≥10% are flagged before the hardware run. Kill: if reports agree with the physical benchmark less than 50% of the time, retire them to debug annotations only. | | **Gates** | H2.2 for real firmware; docs/06 M7 rule; docs/05 methodology is authoritative. | | **Effort / priority** | 2–3 engineering-weeks; **P3**. | @@ -219,9 +219,9 @@ F11, F13). Each item carries exactly one evaluation criterion. |---|---| | **Status** | `planned`. The repository has a tracked SBOM ([`SBOM.md`](../SBOM.md), CycloneDX) and the wiki GPU SBOM is superseded; there is no observation-derived inventory per firmware image that links services, symbols and dispatch tables to the SBOM and architecture docs. | | **Need** | Version bumps change firmware components and external tooling dependencies; provenance, license and vulnerability response need to know what an image contains and what changed. The architecture docs drift from the binary until a costly re-analysis rediscovers the delta. | -| **Scope** | Does derive an observation-backed component/capability inventory per image (hashes, symbols, services, dispatch tables, external dependencies) and link it to SBOM/architecture updates; does not assert legal conclusions, does not name local sources, does not auto-publish un-reviewed findings. | -| **Evaluation** | Metric: SBOM/architecture deltas per release that are observation-derived and reviewable. Baseline: manual entries. Threshold: one release where every added/removed firmware component row carries a hash plus evidence link from a green-eye session. Kill: if observation rows are rejected by SBOM review twice, drop to a provenance annex inside the session evidence. | -| **Gates** | H2.2 for real images; legal-and-licensing review ([`legal-and-licensing.md`](09-reference/legal-and-licensing.md)); local-provenance rules. | +| **Scope** | Does derive an observation-backed component/capability inventory per image (hashes, symbols, services, dispatch tables, external dependencies) and link it to SBOM/architecture updates; does not assert legal conclusions, does not name source locations, does not auto-publish un-reviewed findings. | +| **Evaluation** | Metric: SBOM/architecture deltas per release that are observation-derived and reviewable. Baseline: manual entries. Threshold: one release where every added/removed firmware component row carries a hash plus evidence link from a risc-v-gsp-rm-debugger session. Kill: if observation rows are rejected by SBOM review twice, drop to a provenance annex inside the session evidence. | +| **Gates** | H2.2 for real images; legal-and-licensing review ([`legal-and-licensing.md`](09-reference/legal-and-licensing.md)); provenance rules. | | **Effort / priority** | 2–3 engineering-weeks; **P3**. | ## 4. Pruning and retirement @@ -245,14 +245,14 @@ at the first review, delete it rather than documenting API symmetry. | Trigger | Who | What is re-checked | |---|---|---| -| H2.2 exit | green-eye maintainer + eng-ops owner | F5, F6, F7, F8, F14, F15 gates open; statuses move to `partially used`/`planned` execution | -| Each GSP/driver release | green-eye maintainer | F1/F2/F3 chain cost, F14 findings, F15 SBOM deltas; kill criteria evaluated | +| H2.2 exit | risc-v-gsp-rm-debugger maintainer + eng-ops owner | F5, F6, F7, F8, F14, F15 gates open; statuses move to `partially used`/`planned` execution | +| Each GSP/driver release | risc-v-gsp-rm-debugger maintainer | F1/F2/F3 chain cost, F14 findings, F15 SBOM deltas; kill criteria evaluated | | RM 610 approval request | project lead + maintainer | F1 evidence (C4/C5), bundles for C8; no 610 input before approval | | Quarterly | eng-ops owner | Re-run or explicitly defer every evaluation; prune/demote/keep decisions recorded in §4 | | New funded use case | project lead | Admit a new item with the same six fields; research items become `planned` only with funding | The doc is reviewed against the tool audit ([`27-TOOL-AUDIT.md`](../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md)) -and the roadmap ([`GREEN-EYE-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md)) +and the roadmap ([`RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`](../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md)) so the "what we use now / not yet" split stays true. <!-- change (2026-10-02): point F2–F4 at the landed docs 28/29 scaffolds so the |