From 05797fd8cf884bb680540dfc188f36836a215c9f Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Fri, 2 Oct 2026 11:44:31 -0400 Subject: rename (cosmetic): green-eye -> risc-v-gsp-rm-debugger in user-facing names, docs, CLI, launcher and CI workflow; internal greeneye package/module identifiers unchanged (includes in-flight greeneye module edits present in the tree) --- .../02-debugging-and-maintenance-workflows.md | 20 +- docs/05-operations/03-risc-v-gsp-rm-vm.md | 24 +- docs/05-operations/04-green-eye-user-guide.md | 439 --------------------- .../04-risc-v-gsp-rm-debugger-user-guide.md | 439 +++++++++++++++++++++ .../03-device-validation-and-porting-sequence.md | 4 +- docs/06-portability/hardware-software-matrix.md | 14 +- .../02-development-and-analysis-environment.md | 58 +-- docs/07-developers/onboarding-and-standards.md | 2 +- docs/README.md | 16 +- docs/RUNBOOK.md | 60 +-- docs/eng-ops.md | 36 +- docs/future-eng-ops.md | 22 +- 12 files changed, 567 insertions(+), 567 deletions(-) delete mode 100644 docs/05-operations/04-green-eye-user-guide.md create mode 100644 docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md (limited to 'docs') 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) - +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 --symbols symbols-.json --record` | first-divergence report; first-touch map | -| Symbols | `./greeneye.sh symbols export --index --bias 0 -o symbols-.json` | runtime-address symbol DB with provenance | +| Probe | `./risc-v-gsp-rm-debugger.sh probe --symbols symbols-.json --record` | first-divergence report; first-touch map | +| Symbols | `./risc-v-gsp-rm-debugger.sh symbols export --index --bias 0 -o symbols-.json` | runtime-address symbol DB with provenance | | Version diff | `python3 harness/version_diff.py --old --new --out dumps/vdiff-` | shape/symbol/corpus/probe/behavior diff plus the M1–M6 skeleton | | Portability matrix | `python3 harness/portability_matrix.py --target --target --out dumps/matrix-` | per-target sessions and per-pair `compare` reports | -| Decide | `./greeneye.sh compare dumps/ dumps/ --symbols` | symbol-attributed deltas; a product change only after physical confirmation | +| Decide | `./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --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/ -./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/ +./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-green-eye-user-guide.md deleted file mode 100644 index a9bf1dc..0000000 --- a/docs/05-operations/04-green-eye-user-guide.md +++ /dev/null @@ -1,439 +0,0 @@ -# green-eye User Guide (experimental) - -> **# TOOL IN DEVELOPMENT - NOT READY YET!** -> green-eye 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 -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 - -green-eye 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. - -| It is | It is not | -|---|---| -| A firmware runtime microscope (execution + memory: L0/L1) | A timing, interrupt or device model (L2/L3 absent) | -| A scriptable `Session` API with two backends (QEMU-RSP and native) | A GDB wrapper; there is no GDB dependency | -| A recorded-evidence system with a versioned session format | A product component, a guest agent or a shipped dependency | -| 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 -diagnostics answer *what did the driver request*; a supervised physical cycle -answers *what does silicon do*. green-eye makes the middle question repeatable -and safe. - -## 2. Ten-minute quickstart - -Requirements: Linux, Python 3.10+ (stdlib only), `qemu-system-riscv64` -(Ubuntu `qemu-system-misc`), `clang` and `lld`. No GPU, no driver and no -kernel module are touched. - -```bash -cd open-iov/debug/risc-v-gsp-rm-vm - -./greeneye.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/ - -./greeneye.sh probe # real GSP image: report the first divergence -./greeneye.sh inject # load and invoke a position-independent service -``` - -What "good" looks like: - -1. `info` reports QEMU and the demo paths; -2. `demo` prints hook/branch lines and a session directory under `dumps/`; -3. `analyze` renders hook/watch/breakpoint events and a coherent summary; -4. `probe` reports a bounded first divergence (for the TU104 570.144 image, a - load-access fault at firmware vaddr `0x4009014` reading - `0x2000000000000A00`) — that is expected data, not a boot; -5. `inject` returns matching values on the direct and firmware-dispatched - paths. - -Next steps: [choose a tool](#5-choosing-the-right-tool) for your task and read -[Common recipes](#7-common-recipes). - -## 3. Mental model - -### 3.1 Two backends, one session API - -```text -CLI / REPL / Python ─┐ -MCP (stdio) ────────┼─► GreenEyeAPI ─► Session ─┬─► QEMU-RSP backend (qemu-system-riscv64) -Ghidra bridge ──────┤ hooks, watchpoints, └─► native backend (sim/machine.py) -harness/ + rmharness┘ memory, symbols, recorder ──► session directory -``` - -* **QEMU-RSP** is the default: full RV64 execution, gdbstub transport without - GDB, TCG trace plugin optional. -* **native** (`--backend native`) is the in-process interpreter: deterministic - virtual time (instruction counts), fast startup, an exec/access trace, and - lenient MMIO for first-touch exploration. -* Both satisfy the same `Session` primitives (registers/memory, breakpoints, - watchpoints, step/continue, snapshots), so scripts, probes, plugins, - recordings and comparisons survive a backend change. - -### 3.2 The primitives - -| Primitive | Use it for | -|---|---| -| `breakpoint` / `hook` | did this function run? with what arguments and return value? | -| `watch` (`w`/`r`/`a`) | when did this field change, from which store PC? | -| `run` / `run_until` | bounded observation; stop at a chosen address | -| `call` | Frida-like remote call to unit-test a function in isolation | -| `step` / `note` | single-step with dispatch; annotate the event stream | -| `Memory.read/write/hexdump/search/snapshot/diff` | inspect and diff memory regions | -| `SymbolDB` | resolve file/program/runtime addresses across sources | -| `Recorder` | write the durable session (events, snapshots, blobs) | -| injection SDK | load, register and invoke your own PIC RV64 service | - -Instructions between stops are invisible unless a trace is on: the TCG plugin -(`-plugin qemu/greeneye-trace.so`) on QEMU, or `--trace` on the native backend. - -### 3.3 Fidelity levels (what a result can mean) - -| Level | Property | green-eye today | -|---|---|---| -| **L0** | instruction semantics | high (QEMU TCG, same ISA family) | -| **L1** | memory behaviour | high for RAM-resident code, conditional on mapping | -| **L2** | time/concurrency | **not modelled** (do not claim) | -| **L3** | device environment (falcon, WPR2, CSB, PMU, timers, DMA, IRQ) | **absent** (device model is roadmap) | - -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 -security claims. - -### 3.4 A session is the unit of work - -Every run records a `greeneye-session/1` directory: - -```text -dumps/-/ - session.json format, name, counts, snapshot inventory, meta - events.jsonl append-only event stream (hooks, watches, memory, notes) - snapshots/*.bin.z zlib-compressed region captures with sha256 - blobs/* QEMU logs, trace.jsonl, host-oracle stdout - summary.md rendered analysis -``` - -Partial sessions stay readable; the format evolves additively. A copied -`events.jsonl` without its `session.json`, snapshots and metadata is not -evidence. - -## 4. Tool inventory - -Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. - -### 4.1 CLI (`./greeneye.sh`) - -| Command | One-line purpose | -|---|---| -| `info` | environment/tooling check (QEMU, paths, capabilities) | -| `demo` | canned boot + hooks + watchpoints + recording on the bundled uproc | -| `run ` | run a Python instrumentation session against the demo/ELF | -| `attach` / `launch` | interactive REPL; keep a target alive and print its gdbstub port | -| `record` | boot and record with watches/snapshots (and `--trace` on native) | -| `probe ` | bounded run of a raw image; first-divergence report | -| `analyze ` | session to symbol-annotated Markdown report | -| `compare ` | symbolic A/B delta of two recorded sessions | -| `symbols export\|resolve` | build/inspect a runtime-address symbol DB | -| `inject` | load, register and invoke an SDK service (direct + mailbox) | -| `ghidra` | serve the live session to GhidraScripts over localhost | -| `plugins` | list discoverable plugins | - -### 4.2 Harnesses (`harness/`) - -| Tool | One-line purpose | -|---|---| -| `portability_matrix.py` | probe + fixed scenario + compare across targets, with an M1–M6 skeleton | -| `mutation_harness.py` | seeded one-input mutations with outcome classes and per-attempt sessions | -| `control_discovery.py` | sweep a call surface to find known/unknown/injected handler IDs | -| `reach.py` | is one symbol reachable, what triggers it, with what arguments and effects | -| `version_diff.py` | old vs new image: shape, symbols, corpus hints, probe, behavior | -| `ci_release.py` | version_diff → matrix → mutation smoke, hashed into one bundle | -| `port_driver_versions.py`, `port_new_device.py`, `package_sim.py` | porting/packaging scaffolds (dry-run default; pilot status and evaluation in [docs/28](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md), [docs/29](../../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)) | -| `value_demos/run_all.py` | ten fixed scenarios s01–s10 with measured time-to-value | -| `common.py` | shared helpers (flat relocation, sessions, bounded log reads) | - -### 4.3 Native simulator, plugins, host oracle, bridges - -| Tool | One-line purpose | -|---|---| -| `sim/` (`--backend native`, `--trace`) | deterministic RV64IMAC interpreter with exec/access trace and lenient MMIO | -| `python3 -m greeneye.device_map harvest\|show\|merge\|demo` | first-touch MMIO map: authoring, inspection, merge | -| `qemu/greeneye_trace.c` (`make -C qemu`) | full TCG exec/access JSONL trace with `start=`/`end=` filters | -| `plugins/example_plugin.py` | plugin authoring reference | -| `plugins/mcp_server.py` | MCP server for agents (stdio or loopback; read-only by default) | -| `plugins/rmharness_plugin.py` | REPL commands for the host RM oracle | -| `rmharness/harness.sh` + `rmtool`/`rmtop`/`rmq` | read-only host oracle captures appended into a session | -| `ghidra/ExportForGreenEye.java`, `MarkGreenEyeHits.java`, `GreenEyeControl.java` | symbol export, hit annotation and decompiler-driven execution | -| `sdk/` + `greeneye inject` | position-independent service ABI v1 | - -## 5. Choosing the right tool - -| Task | Tool | Notes | -|---|---|---| -| "Does this run?" / first divergence of a raw image | `./greeneye.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 | -| "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 | -| "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 | -| "Let an agent monitor a run" | `plugins/mcp_server.py` | read/observe by default; writes gated | - -Decision rule: static reading is a hypothesis; a recorded session is evidence; -at least an A/B pair is a conclusion. - -## 6. Sessions as evidence - -1. **Record with a fixed stimulus.** The same script, seed, budgets and image - hash make runs comparable; a self-comparison must be empty. -2. **Annotate as you go.** `s.note(...)` inside the session explains what was - asked and what was mutated; a chat log is not evidence. -3. **Attach the provenance.** Firmware SHA-256, version string, pairing notes, - symbol DB source/hash/bias, and the exact command or script. -4. **Keep the directory together.** `session.json` + `events.jsonl` + - `snapshots/` + blobs are one artifact; publish a SHA-256 list when moving - it. -5. **State the fidelity.** L0/L1 exercised; L2/L3 not claimed; reference - capture named (hardware, vfio-mdev, host oracle or none). -6. **Report deltas honestly.** `compare` marks non-semantic fields (time, host - paths, backend identity) as such; every remaining delta is explained or - listed as open. An empty unexplained-delta list is a claim that must be - earned. -7. **Bundle for triage.** A release bundle is - `bundle-manifest.json` + `release-report.json` + version-diff + portability - matrix + mutation smoke; see - [docs/21](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) §4.3. - -The M1–M6 metric contract (inventory, reply, ordering, state, error-path and -memory-side-effect agreement) is defined in -[docs/06-ACCURACY](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §5 and is -authoritative for every claim. - -## 7. Common recipes - -### 7.1 First record and analyze - -```bash -cd debug/risc-v-gsp-rm-vm -make demo -./greeneye.sh demo # prints the session directory -./greeneye.sh analyze dumps/ # symbol-annotated report -``` - -### 7.2 Probe a new firmware image - -```bash -./greeneye.sh symbols export --index --bias 0 -o symbols-.json -./greeneye.sh probe .fwimage.bin> --symbols symbols-.json --record -python3 harness/version_diff.py --old --new --out dumps/vdiff- \ - --old-symbols symbols-.json --new-symbols symbols-.json -``` - -### 7.3 Discover controls and prove reachability - -```bash -python3 harness/control_discovery.py --out dumps/discovery --max-id 32 \ - --patterns zero --seed 5 -python3 harness/reach.py --target rpc_ping --method call --args 0x41 \ - --out dumps/reach-ping -``` - -### 7.4 Mutate an input surface (simulator only) - -```bash -python3 harness/mutation_harness.py --out dumps/mutation-7 \ - --iterations 64 --seed 7 --timeout 0.25 --settle 0.2 -``` - -### 7.5 Portability pipeline across targets - -```bash -python3 harness/portability_matrix.py \ - --target --target \ - --out dumps/matrix-candidate --probe-instructions 200 --scenario-duration 0.2 -``` - -### 7.6 Inject and debug a service - -```bash -make -C sdk -make -C sdk relocs -./greeneye.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. -Both are recorded. - -### 7.7 Drive execution from Ghidra - -```bash -# terminal 1 -./greeneye.sh ghidra --kernel --bridge-port 7000 -# terminal 2 (Ghidra headless) -$GHIDRA/support/analyzeHeadless -process -noanalysis \ - -scriptPath open-iov/debug/risc-v-gsp-rm-vm/ghidra \ - -postScript GreenEyeControl.java 7000 0x
-``` - -### 7.8 Host oracle capture (read-only) - -```bash -./rmharness/harness.sh --session dumps/real- --name before \ - -- rmtool engine list --format=json -./rmharness/harness.sh --session dumps/real- -- rmtop --once -``` - -### 7.9 Release rehearsal - -```bash -python3 harness/ci_release.py --old --new --out dumps/release- \ - --old-label --new-label --dry-run -``` - -`--dry-run` prints the plan and creates nothing; the RM 610 gate refuses 610 -labels (exit 3) until a human approves in writing. - -### 7.10 Let an agent monitor - -```bash -python3 plugins/mcp_server.py --stdio --backend native --record -# read/observe by default; --allow-write and --allow-inject are explicit opt-ins -``` - -### 7.11 First-touch device map - -```bash -./greeneye.sh probe --record -python3 -m greeneye.device_map harvest dumps/ --out dumps/-device-map.json -python3 -m greeneye.device_map show dumps/-device-map.json -``` - -## 8. Troubleshooting - -| Symptom | Likely cause | Fix | -|---|---|---| -| `qemu-system-riscv64 not found` | QEMU absent or not on `PATH` | install `qemu-system-misc` or point `GREENEYE_QEMU` at the binary | -| QEMU starts but the script cannot attach | wrong port / target exited | use the port `launch`/`demo` printed; re-run `launch` and `attach --port ` | -| `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 | -| 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 | -| Harness findings not reproducible | seed/budget changed | pin `--seed` and budgets; compare `findings.jsonl` byte-for-byte | -| Everything "unreachable" | wrong surface/timeouts | run `--surface demo` on the built demo first; raise `--settle`/`--timeout` | -| `Unknown symbol` in the optional OpenRM build | module-tag drift | re-pin build glue; see the [RUNBOOK](../RUNBOOK.md) S2 | - -Marker status: every tool document carries the -**# TOOL IN DEVELOPMENT - NOT READY YET!** banner. The marker is removed only -when the acceptance list in -[docs/00-OVERVIEW](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md) passes on a -clean checkout, the usage recipes verify end-to-end, a second person can run -the quickstart unaided, and the session format and CLI are declared stable. - -## 9. Safety - -* **Simulator only.** The tools launch their own QEMU or native machine - against the bundled demo or an explicitly allowed re-hosted ELF. They never - attach to hardware, a guest, a kernel module, an mdev or an existing - gdbstub. -* **No guest, no hardware, no product.** Nothing runs in a guest; injected - services are prototypes, not shipped code; product changes go through - `open-iov-vfio` with physical confirmation. -* **Read by default; writes gated.** MCP `write_mem`/`call_function` need - `--allow-write`, injection needs `--allow-inject`, and every write is - recorded in the session. -* **Bounded everywhere.** Runs have durations/stop caps; reads and snapshots - have size caps; harness subprocesses have timeouts; a wedged target is left - stopped and restarted clean rather than poked. -* **Local only.** Ghidra and MCP transports are localhost/stdio; the bridge is - unauthenticated by design, so never expose it on a network interface. -* **No confidentiality claims.** The simulator is a study environment, never a - security or confidentiality boundary; never use injection to defeat a - hardware security boundary. -* **Fuzzing is gated.** Mutation runs only against the simulator or re-hosted - code, behind explicit harnesses, with recorded evidence. -* **RM 610 is a hard human gate.** No acquisition, analysis, emulation edit, - physical work or support claim before written approval; the gate is enforced - by the CLIs. - -## 10. Documentation map - -Tool documentation (`debug/risc-v-gsp-rm-vm/docs/`): [00 overview](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md), -[01 design](../../debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md), -[02 usage](../../debug/risc-v-gsp-rm-vm/docs/02-USAGE.md), -[03 scripting](../../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md), -[04 plugins](../../debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md), -[05 Ghidra bridge](../../debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md), -[06 accuracy](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md), -[07 portability playbooks](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), -[08 roadmap](../../debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md), -[09 firmware notes](../../debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md), -[10 related work](../../debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md), -[11 RM service guide](../../debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md), -[12 injection SDK](../../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md), -[13 Ghidra control](../../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md), -[14 adversarial interop](../../debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md), -[15 agentic GSP IDE](../../debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md), -[16 custom simulator](../../debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md), -[17 RM harness](../../debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md), -[18 harness automation](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md), -[19 control discovery](../../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md), -[20 MCP server](../../debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md), -[21 CI/release pipeline](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), -[22 porting CUDA and devices](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md), -[23 RM 610 readiness](../../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md), -[24 device map](../../debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md), -[25 value validation](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md), -[26 architecture](../../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md), -[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). - -Project documentation: - -* [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) — incident scenarios - S1–S10, evidence bundles, escalation tree; -* [GSP in a RISC-V VM](03-risc-v-gsp-rm-vm.md) — project-level purpose, status - and limits; -* [Debugging and maintenance workflows](02-debugging-and-maintenance-workflows.md) - — captures, failure taxonomy and the upgrade runbook; -* [Hardware and software matrix](../06-portability/hardware-software-matrix.md) - — support ladder and the portability pipeline; -* [Adversarial interoperability](../04-implementation/02-practical-challenges-and-adversarial-interop.md) - — the no-patch rule; -* [Engineering operations](../eng-ops.md) — tool admission, workflows and - retirement (the cross-cutting engineering-operations document); -* CUDA playbook: - [`userspace/cuda/docs/07-version-upgrade-playbook.md`](../../userspace/cuda/docs/07-version-upgrade-playbook.md) - and [`userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md); -* [Documentation front door](../README.md) — the full reading order. - - diff --git a/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md new file mode 100644 index 0000000..f12230a --- /dev/null +++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md @@ -0,0 +1,439 @@ +# risc-v-gsp-rm-debugger User Guide (experimental) + +> **# TOOL IN DEVELOPMENT - NOT READY YET!** +> 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 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 risc-v-gsp-rm-debugger is + +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. + +| It is | It is not | +|---|---| +| A firmware runtime microscope (execution + memory: L0/L1) | A timing, interrupt or device model (L2/L3 absent) | +| A scriptable `Session` API with two backends (QEMU-RSP and native) | A GDB wrapper; there is no GDB dependency | +| A recorded-evidence system with a versioned session format | A product component, a guest agent or a shipped dependency | +| 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*; 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*. risc-v-gsp-rm-debugger makes the middle question repeatable +and safe. + +## 2. Ten-minute quickstart + +Requirements: Linux, Python 3.10+ (stdlib only), `qemu-system-riscv64` +(Ubuntu `qemu-system-misc`), `clang` and `lld`. No GPU, no driver and no +kernel module are touched. + +```bash +cd open-iov/debug/risc-v-gsp-rm-vm + +./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 + +./risc-v-gsp-rm-debugger.sh demo # canned run: boot, hooks, watchpoints, session +./risc-v-gsp-rm-debugger.sh analyze dumps/ + +./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: + +1. `info` reports QEMU and the demo paths; +2. `demo` prints hook/branch lines and a session directory under `dumps/`; +3. `analyze` renders hook/watch/breakpoint events and a coherent summary; +4. `probe` reports a bounded first divergence (for the TU104 570.144 image, a + load-access fault at firmware vaddr `0x4009014` reading + `0x2000000000000A00`) — that is expected data, not a boot; +5. `inject` returns matching values on the direct and firmware-dispatched + paths. + +Next steps: [choose a tool](#5-choosing-the-right-tool) for your task and read +[Common recipes](#7-common-recipes). + +## 3. Mental model + +### 3.1 Two backends, one session API + +```text +CLI / REPL / Python ─┐ +MCP (stdio) ────────┼─► GreenEyeAPI ─► Session ─┬─► QEMU-RSP backend (qemu-system-riscv64) +Ghidra bridge ──────┤ hooks, watchpoints, └─► native backend (sim/machine.py) +harness/ + rmharness┘ memory, symbols, recorder ──► session directory +``` + +* **QEMU-RSP** is the default: full RV64 execution, gdbstub transport without + GDB, TCG trace plugin optional. +* **native** (`--backend native`) is the in-process interpreter: deterministic + virtual time (instruction counts), fast startup, an exec/access trace, and + lenient MMIO for first-touch exploration. +* Both satisfy the same `Session` primitives (registers/memory, breakpoints, + watchpoints, step/continue, snapshots), so scripts, probes, plugins, + recordings and comparisons survive a backend change. + +### 3.2 The primitives + +| Primitive | Use it for | +|---|---| +| `breakpoint` / `hook` | did this function run? with what arguments and return value? | +| `watch` (`w`/`r`/`a`) | when did this field change, from which store PC? | +| `run` / `run_until` | bounded observation; stop at a chosen address | +| `call` | Frida-like remote call to unit-test a function in isolation | +| `step` / `note` | single-step with dispatch; annotate the event stream | +| `Memory.read/write/hexdump/search/snapshot/diff` | inspect and diff memory regions | +| `SymbolDB` | resolve file/program/runtime addresses across sources | +| `Recorder` | write the durable session (events, snapshots, blobs) | +| injection SDK | load, register and invoke your own PIC RV64 service | + +Instructions between stops are invisible unless a trace is on: the TCG plugin +(`-plugin qemu/greeneye-trace.so`) on QEMU, or `--trace` on the native backend. + +### 3.3 Fidelity levels (what a result can mean) + +| 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 | +| **L2** | time/concurrency | **not modelled** (do not claim) | +| **L3** | device environment (falcon, WPR2, CSB, PMU, timers, DMA, IRQ) | **absent** (device model is roadmap) | + +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 risc-v-gsp-rm-debugger session for timing, interrupt or +security claims. + +### 3.4 A session is the unit of work + +Every run records a `greeneye-session/1` directory: + +```text +dumps/-/ + session.json format, name, counts, snapshot inventory, meta + events.jsonl append-only event stream (hooks, watches, memory, notes) + snapshots/*.bin.z zlib-compressed region captures with sha256 + blobs/* QEMU logs, trace.jsonl, host-oracle stdout + summary.md rendered analysis +``` + +Partial sessions stay readable; the format evolves additively. A copied +`events.jsonl` without its `session.json`, snapshots and metadata is not +evidence. + +## 4. Tool inventory + +Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. + +### 4.1 CLI (`./risc-v-gsp-rm-debugger.sh`) + +| Command | One-line purpose | +|---|---| +| `info` | environment/tooling check (QEMU, paths, capabilities) | +| `demo` | canned boot + hooks + watchpoints + recording on the bundled uproc | +| `run ` | run a Python instrumentation session against the demo/ELF | +| `attach` / `launch` | interactive REPL; keep a target alive and print its gdbstub port | +| `record` | boot and record with watches/snapshots (and `--trace` on native) | +| `probe ` | bounded run of a raw image; first-divergence report | +| `analyze ` | session to symbol-annotated Markdown report | +| `compare ` | symbolic A/B delta of two recorded sessions | +| `symbols export\|resolve` | build/inspect a runtime-address symbol DB | +| `inject` | load, register and invoke an SDK service (direct + mailbox) | +| `ghidra` | serve the live session to GhidraScripts over localhost | +| `plugins` | list discoverable plugins | + +### 4.2 Harnesses (`harness/`) + +| Tool | One-line purpose | +|---|---| +| `portability_matrix.py` | probe + fixed scenario + compare across targets, with an M1–M6 skeleton | +| `mutation_harness.py` | seeded one-input mutations with outcome classes and per-attempt sessions | +| `control_discovery.py` | sweep a call surface to find known/unknown/injected handler IDs | +| `reach.py` | is one symbol reachable, what triggers it, with what arguments and effects | +| `version_diff.py` | old vs new image: shape, symbols, corpus hints, probe, behavior | +| `ci_release.py` | version_diff → matrix → mutation smoke, hashed into one bundle | +| `port_driver_versions.py`, `port_new_device.py`, `package_sim.py` | porting/packaging scaffolds (dry-run default; pilot status and evaluation in [docs/28](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md), [docs/29](../../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md)) | +| `value_demos/run_all.py` | ten fixed scenarios s01–s10 with measured time-to-value | +| `common.py` | shared helpers (flat relocation, sessions, bounded log reads) | + +### 4.3 Native simulator, plugins, host oracle, bridges + +| Tool | One-line purpose | +|---|---| +| `sim/` (`--backend native`, `--trace`) | deterministic RV64IMAC interpreter with exec/access trace and lenient MMIO | +| `python3 -m greeneye.device_map harvest\|show\|merge\|demo` | first-touch MMIO map: authoring, inspection, merge | +| `qemu/greeneye_trace.c` (`make -C qemu`) | full TCG exec/access JSONL trace with `start=`/`end=` filters | +| `plugins/example_plugin.py` | plugin authoring reference | +| `plugins/mcp_server.py` | MCP server for agents (stdio or loopback; read-only by default) | +| `plugins/rmharness_plugin.py` | REPL commands for the host RM oracle | +| `rmharness/harness.sh` + `rmtool`/`rmtop`/`rmq` | read-only host oracle captures appended into a session | +| `ghidra/ExportForGreenEye.java`, `MarkGreenEyeHits.java`, `GreenEyeControl.java` | symbol export, hit annotation and decompiler-driven execution | +| `sdk/` + `greeneye inject` | position-independent service ABI v1 | + +## 5. Choosing the right tool + +| Task | Tool | Notes | +|---|---|---| +| "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`, `./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/` + `./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 | +| "Let an agent monitor a run" | `plugins/mcp_server.py` | read/observe by default; writes gated | + +Decision rule: static reading is a hypothesis; a recorded session is evidence; +at least an A/B pair is a conclusion. + +## 6. Sessions as evidence + +1. **Record with a fixed stimulus.** The same script, seed, budgets and image + hash make runs comparable; a self-comparison must be empty. +2. **Annotate as you go.** `s.note(...)` inside the session explains what was + asked and what was mutated; a chat log is not evidence. +3. **Attach the provenance.** Firmware SHA-256, version string, pairing notes, + symbol DB source/hash/bias, and the exact command or script. +4. **Keep the directory together.** `session.json` + `events.jsonl` + + `snapshots/` + blobs are one artifact; publish a SHA-256 list when moving + it. +5. **State the fidelity.** L0/L1 exercised; L2/L3 not claimed; reference + capture named (hardware, vfio-mdev, host oracle or none). +6. **Report deltas honestly.** `compare` marks non-semantic fields (time, host + paths, backend identity) as such; every remaining delta is explained or + listed as open. An empty unexplained-delta list is a claim that must be + earned. +7. **Bundle for triage.** A release bundle is + `bundle-manifest.json` + `release-report.json` + version-diff + portability + matrix + mutation smoke; see + [docs/21](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md) §4.3. + +The M1–M6 metric contract (inventory, reply, ordering, state, error-path and +memory-side-effect agreement) is defined in +[docs/06-ACCURACY](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md) §5 and is +authoritative for every claim. + +## 7. Common recipes + +### 7.1 First record and analyze + +```bash +cd debug/risc-v-gsp-rm-vm +make demo +./risc-v-gsp-rm-debugger.sh demo # prints the session directory +./risc-v-gsp-rm-debugger.sh analyze dumps/ # symbol-annotated report +``` + +### 7.2 Probe a new firmware image + +```bash +./risc-v-gsp-rm-debugger.sh symbols export --index --bias 0 -o symbols-.json +./risc-v-gsp-rm-debugger.sh probe .fwimage.bin> --symbols symbols-.json --record +python3 harness/version_diff.py --old --new --out dumps/vdiff- \ + --old-symbols symbols-.json --new-symbols symbols-.json +``` + +### 7.3 Discover controls and prove reachability + +```bash +python3 harness/control_discovery.py --out dumps/discovery --max-id 32 \ + --patterns zero --seed 5 +python3 harness/reach.py --target rpc_ping --method call --args 0x41 \ + --out dumps/reach-ping +``` + +### 7.4 Mutate an input surface (simulator only) + +```bash +python3 harness/mutation_harness.py --out dumps/mutation-7 \ + --iterations 64 --seed 7 --timeout 0.25 --settle 0.2 +``` + +### 7.5 Portability pipeline across targets + +```bash +python3 harness/portability_matrix.py \ + --target --target \ + --out dumps/matrix-candidate --probe-instructions 200 --scenario-duration 0.2 +``` + +### 7.6 Inject and debug a service + +```bash +make -C sdk +make -C sdk relocs +./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. +Both are recorded. + +### 7.7 Drive execution from Ghidra + +```bash +# terminal 1 +./risc-v-gsp-rm-debugger.sh ghidra --kernel --bridge-port 7000 +# terminal 2 (Ghidra headless) +$GHIDRA/support/analyzeHeadless -process -noanalysis \ + -scriptPath open-iov/debug/risc-v-gsp-rm-vm/ghidra \ + -postScript GreenEyeControl.java 7000 0x
+``` + +### 7.8 Host oracle capture (read-only) + +```bash +./rmharness/harness.sh --session dumps/real- --name before \ + -- rmtool engine list --format=json +./rmharness/harness.sh --session dumps/real- -- rmtop --once +``` + +### 7.9 Release rehearsal + +```bash +python3 harness/ci_release.py --old --new --out dumps/release- \ + --old-label --new-label --dry-run +``` + +`--dry-run` prints the plan and creates nothing; the RM 610 gate refuses 610 +labels (exit 3) until a human approves in writing. + +### 7.10 Let an agent monitor + +```bash +python3 plugins/mcp_server.py --stdio --backend native --record +# read/observe by default; --allow-write and --allow-inject are explicit opt-ins +``` + +### 7.11 First-touch device map + +```bash +./risc-v-gsp-rm-debugger.sh probe --record +python3 -m greeneye.device_map harvest dumps/ --out dumps/-device-map.json +python3 -m greeneye.device_map show dumps/-device-map.json +``` + +## 8. Troubleshooting + +| Symptom | Likely cause | Fix | +|---|---|---| +| `qemu-system-riscv64 not found` | QEMU absent or not on `PATH` | install `qemu-system-misc` or point `GREENEYE_QEMU` at the binary | +| QEMU starts but the script cannot attach | wrong port / target exited | use the port `launch`/`demo` printed; re-run `launch` and `attach --port ` | +| `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 `risc-v-gsp-rm-debugger.sh run` | run through `./risc-v-gsp-rm-debugger.sh run`, keep scripts inside the tool tree | +| Empty TCG trace blob | plugin window missed or target never resumed | `make -C qemu`; widen `start=`/`end=`, set `exec=on`, resume the target | +| MCP writes refused / no tools | server read-only by default; stdout polluted | pass `--allow-write`/`--allow-inject` deliberately; keep stdout protocol-only | +| `greeneye error:` on a valid path | wrong relative path or `--db` file | `./risc-v-gsp-rm-debugger.sh info` shows resolved paths; bad symbol DBs fail with a clear error | +| Harness findings not reproducible | seed/budget changed | pin `--seed` and budgets; compare `findings.jsonl` byte-for-byte | +| Everything "unreachable" | wrong surface/timeouts | run `--surface demo` on the built demo first; raise `--settle`/`--timeout` | +| `Unknown symbol` in the optional OpenRM build | module-tag drift | re-pin build glue; see the [RUNBOOK](../RUNBOOK.md) S2 | + +Marker status: every tool document carries the +**# TOOL IN DEVELOPMENT - NOT READY YET!** banner. The marker is removed only +when the acceptance list in +[docs/00-OVERVIEW](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md) passes on a +clean checkout, the usage recipes verify end-to-end, a second person can run +the quickstart unaided, and the session format and CLI are declared stable. + +## 9. Safety + +* **Simulator only.** The tools launch their own QEMU or native machine + against the bundled demo or an explicitly allowed re-hosted ELF. They never + attach to hardware, a guest, a kernel module, an mdev or an existing + gdbstub. +* **No guest, no hardware, no product.** Nothing runs in a guest; injected + services are prototypes, not shipped code; product changes go through + `open-iov-vfio` with physical confirmation. +* **Read by default; writes gated.** MCP `write_mem`/`call_function` need + `--allow-write`, injection needs `--allow-inject`, and every write is + recorded in the session. +* **Bounded everywhere.** Runs have durations/stop caps; reads and snapshots + have size caps; harness subprocesses have timeouts; a wedged target is left + stopped and restarted clean rather than poked. +* **Local only.** Ghidra and MCP transports are localhost/stdio; the bridge is + unauthenticated by design, so never expose it on a network interface. +* **No confidentiality claims.** The simulator is a study environment, never a + security or confidentiality boundary; never use injection to defeat a + hardware security boundary. +* **Fuzzing is gated.** Mutation runs only against the simulator or re-hosted + code, behind explicit harnesses, with recorded evidence. +* **RM 610 is a hard human gate.** No acquisition, analysis, emulation edit, + physical work or support claim before written approval; the gate is enforced + by the CLIs. + +## 10. Documentation map + +Tool documentation (`debug/risc-v-gsp-rm-vm/docs/`): [00 overview](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md), +[01 design](../../debug/risc-v-gsp-rm-vm/docs/01-DESIGN.md), +[02 usage](../../debug/risc-v-gsp-rm-vm/docs/02-USAGE.md), +[03 scripting](../../debug/risc-v-gsp-rm-vm/docs/03-SCRIPTING.md), +[04 plugins](../../debug/risc-v-gsp-rm-vm/docs/04-PLUGINS.md), +[05 Ghidra bridge](../../debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md), +[06 accuracy](../../debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md), +[07 portability playbooks](../../debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md), +[08 roadmap](../../debug/risc-v-gsp-rm-vm/docs/08-ROADMAP.md), +[09 firmware notes](../../debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md), +[10 related work](../../debug/risc-v-gsp-rm-vm/docs/10-RELATED-WORK.md), +[11 RM service guide](../../debug/risc-v-gsp-rm-vm/docs/11-GSP-RM-SERVICE-DEVELOPER-GUIDE.md), +[12 injection SDK](../../debug/risc-v-gsp-rm-vm/docs/12-INJECTION-SDK.md), +[13 Ghidra control](../../debug/risc-v-gsp-rm-vm/docs/13-GHIDRA-CONTROL.md), +[14 adversarial interop](../../debug/risc-v-gsp-rm-vm/docs/14-ADVERSARIAL-INTEROP-GUIDE.md), +[15 agentic GSP IDE](../../debug/risc-v-gsp-rm-vm/docs/15-AGENTIC-GSP-IDE.md), +[16 custom simulator](../../debug/risc-v-gsp-rm-vm/docs/16-CUSTOM-SIMULATOR.md), +[17 RM harness](../../debug/risc-v-gsp-rm-vm/docs/17-RM-HARNESS.md), +[18 harness automation](../../debug/risc-v-gsp-rm-vm/docs/18-HARNESS-AUTOMATION.md), +[19 control discovery](../../debug/risc-v-gsp-rm-vm/docs/19-CONTROL-DISCOVERY.md), +[20 MCP server](../../debug/risc-v-gsp-rm-vm/docs/20-MCP-SERVER.md), +[21 CI/release pipeline](../../debug/risc-v-gsp-rm-vm/docs/21-CI-RELEASE-PIPELINE.md), +[22 porting CUDA and devices](../../debug/risc-v-gsp-rm-vm/docs/22-PORTING-CUDA-AND-DEVICES.md), +[23 RM 610 readiness](../../debug/risc-v-gsp-rm-vm/docs/23-RM610-READINESS.md), +[24 device map](../../debug/risc-v-gsp-rm-vm/docs/24-DEVICE-MAP.md), +[25 value validation](../../debug/risc-v-gsp-rm-vm/docs/25-VALUE-VALIDATION.md), +[26 architecture](../../debug/risc-v-gsp-rm-vm/docs/26-ARCHITECTURE.md), +[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/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). + +Project documentation: + +* [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) — incident scenarios + S1–S10, evidence bundles, escalation tree; +* [GSP in a RISC-V VM](03-risc-v-gsp-rm-vm.md) — project-level purpose, status + and limits; +* [Debugging and maintenance workflows](02-debugging-and-maintenance-workflows.md) + — captures, failure taxonomy and the upgrade runbook; +* [Hardware and software matrix](../06-portability/hardware-software-matrix.md) + — support ladder and the portability pipeline; +* [Adversarial interoperability](../04-implementation/02-practical-challenges-and-adversarial-interop.md) + — the no-patch rule; +* [Engineering operations](../eng-ops.md) — tool admission, workflows and + retirement (the cross-cutting engineering-operations document); +* CUDA playbook: + [`userspace/cuda/docs/07-version-upgrade-playbook.md`](../../userspace/cuda/docs/07-version-upgrade-playbook.md) + and [`userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md); +* [Documentation front door](../README.md) — the full reading order. + + 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).** - Before the profile change lands, run the firmware-side pipeline from `debug/risc-v-gsp-rm-vm/` and attach its output: -`./greeneye.sh probe --symbols --record` for the first-touch map; -`./greeneye.sh symbols export ...` for a provenance-carrying symbol DB; +`./risc-v-gsp-rm-debugger.sh probe --symbols --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 --target --out dumps/matrix-` 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.** 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>
GSP firmware Ghidra projects"] GHCUDA["userspace/cuda Ghidra corpus
+ 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,
call, run_until, record"] GEB["Backends: QEMU-RSP + native RV64IMAC"] GEH["harness/, injection SDK,
Ghidra bridges, device maps"] RMH["rmharness host captures"] end subgraph AUTO["Automation"] - CI[".github/workflows/ci.yml
.github/workflows/greeneye.yml"] + CI[".github/workflows/ci.yml
.github/workflows/risc-v-gsp-rm-debugger.yml"] MCP["plugins/mcp_server.py
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//` | | 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/ +./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/ ``` 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,
symbol inventory diff"] A2 --> A3["hypothesis: dispatch tables,
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
sessions"] B2 --> B3["evidence: hits, watch PCs,
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 | - @@ -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). 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) +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 --bias 0 -o symbols-.json +./risc-v-gsp-rm-debugger.sh symbols export --index --bias 0 -o symbols-.json # 2) bounded probe of each image (records a session) -./greeneye.sh probe .fwimage.bin> --symbols symbols-.json --record +./risc-v-gsp-rm-debugger.sh probe .fwimage.bin> --symbols symbols-.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-- # 4) behaviour compare and canonical report -./greeneye.sh compare dumps/ dumps/ --symbols -./greeneye.sh analyze dumps/ --symbols symbols-.json +./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols +./risc-v-gsp-rm-debugger.sh analyze dumps/ --symbols symbols-.json ``` ### S2 — New kernel driver / open-kernel-modules release @@ -301,7 +301,7 @@ python3 harness/control_discovery.py --out dumps/discovery- --seed python3 harness/reach.py --target --method auto --out dumps/reach- # symbol-attributed A/B -./greeneye.sh compare dumps/ dumps/ --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols ``` ### S4 — New CUDA userspace / toolkit interacting unexpectedly with the GSP @@ -319,7 +319,7 @@ python3 harness/reach.py --target --method auto --out dumps/reach-/run/libcuda.so. /run/libcuda.so. tools/cudatool.py wrappers /run/libcuda.so. cd ../../debug/risc-v-gsp-rm-vm -./greeneye.sh symbols export \ +./risc-v-gsp-rm-debugger.sh symbols export \ --names ../../userspace/cuda//annotations/names.tsv \ --index ../../userspace/cuda//run/analysis/decompiled/decompiled_index.tsv \ --bias 0x100000 -o symbols-.json -./greeneye.sh symbols resolve --db symbols-.json 0x +./risc-v-gsp-rm-debugger.sh symbols resolve --db symbols-.json 0x 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 && readelf -h && readelf -l cd debug/risc-v-gsp-rm-vm -./greeneye.sh info -./greeneye.sh probe --symbols symbols-.json --record +./risc-v-gsp-rm-debugger.sh info +./risc-v-gsp-rm-debugger.sh probe --symbols symbols-.json --record python3 harness/portability_matrix.py \ --target --target \ --out dumps/matrix- @@ -412,7 +412,7 @@ python3 harness/portability_matrix.py \ ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh probe --instructions --record +./risc-v-gsp-rm-debugger.sh probe --instructions --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/ dumps/ --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --symbols ``` ### S8 — Encrypted/protected memory or protected instructions (measurement plan; non-claims) @@ -528,11 +528,11 @@ python3 -m greeneye.device_map show dumps/-device-map.json ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh probe --record +./risc-v-gsp-rm-debugger.sh probe --record python3 -m greeneye.device_map harvest dumps/ --out dumps/-device-map.json python3 -m greeneye.device_map merge dumps/-device-map.json dumps/-device-map.json \ --out dumps/merged-device-map.json -./greeneye.sh compare dumps/ dumps/ --symbols +./risc-v-gsp-rm-debugger.sh compare dumps/ dumps/ --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 --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// 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/ ELF or .fwimage, hash-pinned 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.