diff options
Diffstat (limited to 'docs/05-operations')
| -rw-r--r-- | docs/05-operations/02-debugging-and-maintenance-workflows.md | 20 | ||||
| -rw-r--r-- | docs/05-operations/03-risc-v-gsp-rm-vm.md | 24 | ||||
| -rw-r--r-- | docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md (renamed from docs/05-operations/04-green-eye-user-guide.md) | 58 |
3 files changed, 51 insertions, 51 deletions
diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md index cfc452d..975b3dc 100644 --- a/docs/05-operations/02-debugging-and-maintenance-workflows.md +++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md @@ -192,13 +192,13 @@ Watch the serial log afterwards for backtraces. A truly hard-wedged vCPU (spinning on a faulting MMIO instruction) may print nothing — use the gdbstub instead. -### 3.9 Firmware runtime analysis — green-eye (experimental) +### 3.9 Firmware runtime analysis — risc-v-gsp-rm-debugger (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** For firmware-side questions (what does the GSP/uproc server do at runtime, what does it read/write, how do its state machines evolve), the experimental -green-eye tooling runs uproc/GSP firmware in a `qemu-system-riscv64` VM with +risc-v-gsp-rm-debugger tooling runs uproc/GSP firmware in a `qemu-system-riscv64` VM with hooks, watchpoints, memory dumps and session recording, without a physical GPU, WPR2 risk or a reboot. See [`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md) for purpose, status and @@ -322,13 +322,13 @@ version × each hardware family, run the step-5 bring-up sequence. When adding a version, extend the matrix rather than replacing the old column — regressions across versions are the cheapest bugs to catch. -### 4.1.1 Green-eye-assisted upgrade/porting workflow (experimental) +### 4.1.1 Risc-V GSP-RM debugger-assisted upgrade/porting workflow (experimental) -<!-- change (2026-10-02): add the green-eye probe -> symbols -> version diff -> +<!-- change (2026-10-02): add the risc-v-gsp-rm-debugger probe -> symbols -> version diff -> portability matrix -> decide pipeline to the upgrade runbook, with pointers to -the new RUNBOOK and green-eye user guide; additive only. --> +the new RUNBOOK and risc-v-gsp-rm-debugger user guide; additive only. --> -For firmware-side questions the experimental green-eye tooling (see +For firmware-side questions the experimental risc-v-gsp-rm-debugger tooling (see [`03-risc-v-gsp-rm-vm.md`](03-risc-v-gsp-rm-vm.md)) turns steps 3–5 above into a repeatable pipeline that produces attachable evidence before any emulation change. It never replaces the physical backend when silicon truth is required, @@ -336,11 +336,11 @@ and it never touches a guest, a kernel module or the installed driver. | Rung | Command (from `debug/risc-v-gsp-rm-vm/`) | Output | |---|---|---| -| Probe | `./greeneye.sh probe <new.fwimage> --symbols symbols-<ver>.json --record` | first-divergence report; first-touch map | -| Symbols | `./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json` | runtime-address symbol DB with provenance | +| Probe | `./risc-v-gsp-rm-debugger.sh probe <new.fwimage> --symbols symbols-<ver>.json --record` | first-divergence report; first-touch map | +| Symbols | `./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json` | runtime-address symbol DB with provenance | | Version diff | `python3 harness/version_diff.py --old <old> --new <new> --out dumps/vdiff-<ver>` | shape/symbol/corpus/probe/behavior diff plus the M1–M6 skeleton | | Portability matrix | `python3 harness/portability_matrix.py --target <old> --target <new> --out dumps/matrix-<ver>` | per-target sessions and per-pair `compare` reports | -| Decide | `./greeneye.sh compare dumps/<old-run> dumps/<new-run> --symbols` | symbol-attributed deltas; a product change only after physical confirmation | +| Decide | `./risc-v-gsp-rm-debugger.sh compare dumps/<old-run> dumps/<new-run> --symbols` | symbol-attributed deltas; a product change only after physical confirmation | Decision discipline: verify the pairing first; behaviour that moved without a code change is usually a state/ordering fix; changed code on a live path is @@ -348,7 +348,7 @@ prioritised; a symbol never hit in either run is a coverage gap, not dead code. The full incident procedures (symptoms, evidence, response order, rollback) are in the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md) S1 and its OODA ordering; the quickstart and tool chooser are in the -[green-eye user guide](04-green-eye-user-guide.md). +[risc-v-gsp-rm-debugger user guide](04-risc-v-gsp-rm-debugger-user-guide.md). ### 4.2 New guest driver version diff --git a/docs/05-operations/03-risc-v-gsp-rm-vm.md b/docs/05-operations/03-risc-v-gsp-rm-vm.md index c21124b..773006d 100644 --- a/docs/05-operations/03-risc-v-gsp-rm-vm.md +++ b/docs/05-operations/03-risc-v-gsp-rm-vm.md @@ -1,4 +1,4 @@ -# GSP in a RISC-V VM — green-eye (experimental) +# GSP in a RISC-V VM — risc-v-gsp-rm-debugger (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** > This is experimental developer tooling. It is not part of the shipped @@ -10,7 +10,7 @@ ## 1. What it is -**green-eye** runs GSP/uproc firmware in a `qemu-system-riscv64` VM and makes +**risc-v-gsp-rm-debugger** runs GSP/uproc firmware in a `qemu-system-riscv64` VM and makes its runtime behaviour inspectable with Frida-like primitives: * breakpoints and enter/leave hooks (RV64 ABI aware), @@ -48,7 +48,7 @@ accuracy, portability playbooks, roadmap) is under * **Not a timing model.** Do not infer latency or concurrency behaviour from it; its in-scope conclusions are execution flow and memory side effects. * **Not a replacement for Ghidra or the guest diagnostics.** Ghidra answers - *what is the code*; green-eye answers *what did it do*. The guest driver + *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. The guest driver remains the oracle for guest-side behaviour. ## 3. Where it fits @@ -58,10 +58,10 @@ accuracy, portability playbooks, roadmap) is under | Static | Ghidra corpus (`userspace/cuda`, `tools/ghidra`) | what is the code? | | Guest driver | `tools/guest-diag/`, ptrace tracer | what did the driver request? | | Physical backend | supervised physical cycles, module logs | what did real silicon/the real GSP-RM do? | -| **Firmware runtime (this)** | **green-eye** | **what does the firmware server do, repeatably and safely?** | +| **Firmware runtime (this)** | **risc-v-gsp-rm-debugger** | **what does the firmware server do, repeatably and safely?** | The intended measurement loop is: capture the real backend's RPC behaviour, -run the same stimulus in green-eye, and compare the recorded sessions +run the same stimulus in risc-v-gsp-rm-debugger, and compare the recorded sessions (`greeneye compare`) with the accuracy metrics defined in the tool's `docs/06-ACCURACY.md`. Portability runs (new GSP, new device, GB10-class architecture) are described in `docs/07-PORTABILITY-PLAYBOOKS.md`. @@ -72,13 +72,13 @@ From the repository root: ```bash cd debug/risc-v-gsp-rm-vm -./greeneye.sh info # environment check (QEMU, toolchain) +./risc-v-gsp-rm-debugger.sh info # environment check (QEMU, toolchain) make demo sdk # build the demo uproc and the injection SDK -./greeneye.sh demo # canned instrumentation pass; records a session -./greeneye.sh analyze dumps/<session> -./greeneye.sh probe # real GSP image: report the first divergence -./greeneye.sh inject # load and invoke an injected service -./greeneye.sh ghidra # serve the session to GhidraScripts +./risc-v-gsp-rm-debugger.sh demo # canned instrumentation pass; records a session +./risc-v-gsp-rm-debugger.sh analyze dumps/<session> +./risc-v-gsp-rm-debugger.sh probe # real GSP image: report the first divergence +./risc-v-gsp-rm-debugger.sh inject # load and invoke an injected service +./risc-v-gsp-rm-debugger.sh ghidra # serve the session to GhidraScripts ``` Requirements: `qemu-system-riscv64` (Ubuntu `qemu-system-misc`), Python 3.10+ @@ -96,7 +96,7 @@ real-firmware first-fault probe, and the TCG full-memory trace plugin. Not implemented: device model (R1), custom simulator (R2), MCP plugin (R3) — all roadmap. The long-term program (adversarial navigation, adjacent microcontrollers, custom simulator, Verilog soft-core, agentic platform) is -documented in `debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md`. +documented in `debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md`. ## 6. When the development flag can be removed diff --git a/docs/05-operations/04-green-eye-user-guide.md b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md index a9bf1dc..f12230a 100644 --- a/docs/05-operations/04-green-eye-user-guide.md +++ b/docs/05-operations/04-risc-v-gsp-rm-debugger-user-guide.md @@ -1,21 +1,21 @@ -# green-eye User Guide (experimental) +# risc-v-gsp-rm-debugger User Guide (experimental) > **# TOOL IN DEVELOPMENT - NOT READY YET!** -> green-eye is the development environment for running GSP/uproc firmware +> risc-v-gsp-rm-debugger is the development environment for running GSP/uproc firmware > off-hardware, observing it, injecting into it and comparing runs as evidence. > It is never shipped, never a driver dependency and never present in a guest; > interfaces and file formats may change without notice. For incident response > procedures see the [Open-IOV Defensive Operations Runbook](../RUNBOOK.md). -This guide is the single front door for a new user: what green-eye is, how to +This guide is the single front door for a new user: what risc-v-gsp-rm-debugger is, how to get a first recorded run in ten minutes, which tool to use for which task, how to treat sessions as evidence, and what to do when something is wrong. The authoritative details live in the tool's own documentation set ([documentation map](#10-documentation-map)). -## 1. What green-eye is +## 1. What risc-v-gsp-rm-debugger is -green-eye runs GSP/uproc firmware in a controllable machine, instruments it +risc-v-gsp-rm-debugger runs GSP/uproc firmware in a controllable machine, instruments it with Frida-like primitives, records a durable session, changes the machine's inputs (including injected code), and compares runs so that emulation changes in `open-iov-vfio` land with evidence instead of anecdotes. @@ -28,9 +28,9 @@ in `open-iov-vfio` land with evidence instead of anecdotes. | A static/dynamic join for Ghidra | A decompiler or a CUDA-corpus replacement | | An automation layer (harnesses, MCP, CI) | A fuzzing service against hardware; simulator/re-hosted code only | -Ghidra answers *what is the code*; green-eye answers *what did it do*. Guest +Ghidra answers *what is the code*; risc-v-gsp-rm-debugger answers *what did it do*. Guest diagnostics answer *what did the driver request*; a supervised physical cycle -answers *what does silicon do*. green-eye makes the middle question repeatable +answers *what does silicon do*. risc-v-gsp-rm-debugger makes the middle question repeatable and safe. ## 2. Ten-minute quickstart @@ -42,14 +42,14 @@ kernel module are touched. ```bash cd open-iov/debug/risc-v-gsp-rm-vm -./greeneye.sh info # environment check: QEMU, toolchain, paths +./risc-v-gsp-rm-debugger.sh info # environment check: QEMU, toolchain, paths make demo && make sdk # build the bundled RV64 uproc demo and injection SDK -./greeneye.sh demo # canned run: boot, hooks, watchpoints, session -./greeneye.sh analyze dumps/<printed-session-dir> +./risc-v-gsp-rm-debugger.sh demo # canned run: boot, hooks, watchpoints, session +./risc-v-gsp-rm-debugger.sh analyze dumps/<printed-session-dir> -./greeneye.sh probe # real GSP image: report the first divergence -./greeneye.sh inject # load and invoke a position-independent service +./risc-v-gsp-rm-debugger.sh probe # real GSP image: report the first divergence +./risc-v-gsp-rm-debugger.sh inject # load and invoke a position-independent service ``` What "good" looks like: @@ -105,7 +105,7 @@ Instructions between stops are invisible unless a trace is on: the TCG plugin ### 3.3 Fidelity levels (what a result can mean) -| Level | Property | green-eye today | +| Level | Property | risc-v-gsp-rm-debugger today | |---|---|---| | **L0** | instruction semantics | high (QEMU TCG, same ISA family) | | **L1** | memory behaviour | high for RAM-resident code, conditional on mapping | @@ -114,7 +114,7 @@ Instructions between stops are invisible unless a trace is on: the TCG plugin A simulator observation is evidence about the firmware, not about silicon; anything that would change the product is reproduced on a physical/vfio-mdev -reference first. Never quote a green-eye session for timing, interrupt or +reference first. Never quote a risc-v-gsp-rm-debugger session for timing, interrupt or security claims. ### 3.4 A session is the unit of work @@ -138,7 +138,7 @@ evidence. Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. -### 4.1 CLI (`./greeneye.sh`) +### 4.1 CLI (`./risc-v-gsp-rm-debugger.sh`) | Command | One-line purpose | |---|---| @@ -187,15 +187,15 @@ Run everything from `open-iov/debug/risc-v-gsp-rm-vm/` unless stated. | Task | Tool | Notes | |---|---|---| -| "Does this run?" / first divergence of a raw image | `./greeneye.sh probe` | no device model: expected early fault is data | +| "Does this run?" / first divergence of a raw image | `./risc-v-gsp-rm-debugger.sh probe` | no device model: expected early fault is data | | "What does this firmware do on this stimulus?" | `record` / `run` + `analyze` | fixed stimulus, bounded budgets, hooks/watchpoints | | "Which command IDs exist / what is undiscovered?" | `harness/control_discovery.py` | fresh session per probe; deterministic seed | | "Is this function reachable, and how?" | `harness/reach.py` | `auto|stimulus|trigger|run|call`; emits a replayable probe spec | -| "What changed between two firmware versions?" | `harness/version_diff.py`, `./greeneye.sh compare` | static inventory + dynamic profile | +| "What changed between two firmware versions?" | `harness/version_diff.py`, `./risc-v-gsp-rm-debugger.sh compare` | static inventory + dynamic profile | | "Does the new firmware move behaviour or code?" | `harness/version_diff.py` + docs/14 decision table | code vs behaviour classification | | "Prove an error path / fail-closed rule" | `harness/mutation_harness.py` | simulator only; seeded and replayable | -| "Prototype an RM service before product code" | `sdk/` + `./greeneye.sh inject` | PIC blob; direct and mailbox paths | -| "Join Ghidra static addresses to runtime hits" | `./greeneye.sh ghidra` + Java bridges | localhost only; no auth | +| "Prototype an RM service before product code" | `sdk/` + `./risc-v-gsp-rm-debugger.sh inject` | PIC blob; direct and mailbox paths | +| "Join Ghidra static addresses to runtime hits" | `./risc-v-gsp-rm-debugger.sh ghidra` + Java bridges | localhost only; no auth | | "What does a control reply look like on real RM?" | `rmharness/harness.sh … rmtool` | read-only host oracle; safe beside a CUDA job | | "Explore MMIO the firmware touches first" | `probe` → `python3 -m greeneye.device_map` | versioned JSON; feeds the device model | | "Triage a release end to end" | `harness/ci_release.py` | always `--dry-run` first | @@ -238,15 +238,15 @@ authoritative for every claim. ```bash cd debug/risc-v-gsp-rm-vm make demo -./greeneye.sh demo # prints the session directory -./greeneye.sh analyze dumps/<session> # symbol-annotated report +./risc-v-gsp-rm-debugger.sh demo # prints the session directory +./risc-v-gsp-rm-debugger.sh analyze dumps/<session> # symbol-annotated report ``` ### 7.2 Probe a new firmware image ```bash -./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json -./greeneye.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<ver>.json --record +./risc-v-gsp-rm-debugger.sh symbols export --index <export.tsv> --bias 0 -o symbols-<ver>.json +./risc-v-gsp-rm-debugger.sh probe <gsp-<VER>.fwimage.bin> --symbols symbols-<ver>.json --record python3 harness/version_diff.py --old <old> --new <new> --out dumps/vdiff-<ver> \ --old-symbols symbols-<old>.json --new-symbols symbols-<new>.json ``` @@ -280,7 +280,7 @@ python3 harness/portability_matrix.py \ ```bash make -C sdk make -C sdk relocs -./greeneye.sh inject --service sdk/build/injected_demo.elf --cmd 1 --arg0 0x41 --arg1 0x42 +./risc-v-gsp-rm-debugger.sh inject --service sdk/build/injected_demo.elf --cmd 1 --arg0 0x41 --arg1 0x42 ``` The direct call is the unit test; the mailbox call is the integration test. @@ -290,7 +290,7 @@ Both are recorded. ```bash # terminal 1 -./greeneye.sh ghidra --kernel <elf> --bridge-port 7000 +./risc-v-gsp-rm-debugger.sh ghidra --kernel <elf> --bridge-port 7000 # terminal 2 (Ghidra headless) $GHIDRA/support/analyzeHeadless <proj> <name> -process <program> -noanalysis \ -scriptPath open-iov/debug/risc-v-gsp-rm-vm/ghidra \ @@ -325,7 +325,7 @@ python3 plugins/mcp_server.py --stdio --backend native --record ### 7.11 First-touch device map ```bash -./greeneye.sh probe <fwimage> --record +./risc-v-gsp-rm-debugger.sh probe <fwimage> --record python3 -m greeneye.device_map harvest dumps/<probe-session> --out dumps/<ver>-device-map.json python3 -m greeneye.device_map show dumps/<ver>-device-map.json ``` @@ -339,10 +339,10 @@ python3 -m greeneye.device_map show dumps/<ver>-device-map.json | `Address already in use` on a bridge/trace port | stale bridge or another session | choose another `--bridge-port`; check `pgrep -fa greeneye` and `pgrep -fa qemu-system-riscv64` | | QEMU survives Ctrl-C of a script | `launch` keeps the target alive by design | close the session or stop the reported PID; do not kill an unrelated QEMU | | Session analyzer shows no hits/events | recording off, or the stimulus never ran | use the CLI (records by default); check hooks/watchpoints with a known symbol (`rpc_sum`) | -| `NameError: __file__` in `run` scripts | script invoked outside `greeneye.sh run` | run through `./greeneye.sh run`, keep scripts inside the tool tree | +| `NameError: __file__` in `run` scripts | script invoked outside `risc-v-gsp-rm-debugger.sh run` | run through `./risc-v-gsp-rm-debugger.sh run`, keep scripts inside the tool tree | | Empty TCG trace blob | plugin window missed or target never resumed | `make -C qemu`; widen `start=`/`end=`, set `exec=on`, resume the target | | MCP writes refused / no tools | server read-only by default; stdout polluted | pass `--allow-write`/`--allow-inject` deliberately; keep stdout protocol-only | -| `greeneye error:` on a valid path | wrong relative path or `--db` file | `./greeneye.sh info` shows resolved paths; bad symbol DBs fail with a clear error | +| `greeneye error:` on a valid path | wrong relative path or `--db` file | `./risc-v-gsp-rm-debugger.sh info` shows resolved paths; bad symbol DBs fail with a clear error | | Harness findings not reproducible | seed/budget changed | pin `--seed` and budgets; compare `findings.jsonl` byte-for-byte | | Everything "unreachable" | wrong surface/timeouts | run `--surface demo` on the built demo first; raise `--settle`/`--timeout` | | `Unknown symbol` in the optional OpenRM build | module-tag drift | re-pin build glue; see the [RUNBOOK](../RUNBOOK.md) S2 | @@ -412,7 +412,7 @@ Tool documentation (`debug/risc-v-gsp-rm-vm/docs/`): [00 overview](../../debug/r [27 tool audit](../../debug/risc-v-gsp-rm-vm/docs/27-TOOL-AUDIT.md), [28 porting automation](../../debug/risc-v-gsp-rm-vm/docs/28-PORTING-AUTOMATION.md), [29 packaging and trialing](../../debug/risc-v-gsp-rm-vm/docs/29-PACKAGING-AND-TRIALING.md), and the -[long-term roadmap](../../debug/risc-v-gsp-rm-vm/GREEN-EYE-ROADMAP.md). +[long-term roadmap](../../debug/risc-v-gsp-rm-vm/RISC-V-GSP-RM-DEBUGGER-ROADMAP.md). Project documentation: |