debug: add green-eye GSP/uproc RISC-V VM runtime analysis tooling

Adds open-iov/debug/risc-v-gsp-rm-vm: a GDB-free instrumentation stack that boots uproc/GSP firmware in qemu-system-riscv64 and provides Frida-like hooks, breakpoints, watchpoints, memory dumps, structure decoding, snapshot diffs, recorded sessions, declarative probes, a plugin API and a Ghidra symbol/hit bridge.

Verified: 25 tests green (including a live QEMU smoke test); the demo uproc boots with correct hook/leave/watch/schema/snapshot/fault evidence; the optional TCG trace plugin builds and recorded 15M trace lines in 3 s; the TU104 570.144 fwimage probe reports its first exception (load access fault at firmware vaddr 0x4009014 reading 0x2000000000000A00).

Documentation: lean tool docs under debug/risc-v-gsp-rm-vm/docs/00-10, a new docs/05-operations/03-risc-v-gsp-rm-vm.md debugging document, and '# TOOL IN DEVELOPMENT - NOT READY YET!' markers in docs/README.md, the onboarding tooling table and the debugging workflows doc.

Vendors qemu-plugin.h from QEMU v8.2.2 (GPL-2.0-or-later), with its license header intact, so the optional TCG plugin builds without a QEMU source tree.

1 files changed, 136 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md b/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md
new file mode 100644
index 0000000..1a1ae82
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/06-ACCURACY.md
@@ -0,0 +1,136 @@
+# 06 — Accuracy: what the green-eye test bed does and does not prove
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+> This document is deliberately conservative. Treat every claim without a
+> recorded A/B as unverified.
+
+## 1. Purpose
+
+green-eye exists to measure how accurately Open-IOV's GSP emulation
+(`gsp-rm-vfio` and the in-kernel emulation) reproduces the behaviour of the
+real GSP firmware, and to make the firmware itself analysable. That makes
+accuracy a first-class deliverable, not an assumption. This document defines
+the fidelity levels, the measurement contract, and the rules for honest
+conclusions.
+
+## 2. Fidelity levels
+
+| Level | Property | green-eye today |
+|---|---|---|
+| **L0 — instruction semantics** | RV64IMAC executes as on the device core | high (QEMU TCG, same ISA family) |
+| **L1 — memory behaviour** | reads/writes/ordering as firmware expects | high for RAM-resident code, *conditional* on mapping the same physical layout |
+| **L2 — time/concurrency** | cycle counts, DMA latency, interrupt timing | **not modelled** (do not claim) |
+| **L3 — device environment** | falcon windows, WPR2, CSB/TRANSCOM, PMU, timers, FB DMA, IRQ routing | **absent** (roadmap) |
+
+The practical reading: green-eye is an **execution and memory** microscope,
+not a timing or silicon model. Conclusions of the form "the firmware writes X
+before Y" are in scope; "the firmware takes N µs" is not.
+
+## 3. The real boot chain vs a bare QEMU VM
+
+The physical path the project already proved is:
+
+```
+FWSEC (falcon) -> WPR2 carve -> Booter Load (SEC2) -> RISC-V start
+   -> bootloader/appMain -> GSP-RM init -> RPC server
+```
+
+The GSP application's own entry supports this model: `_start` receives
+bootargs from the bootloader in `a0`–`a5` (bootargs PA/VA, ELF PA/size, load
+base PA, write-protected-region id), sets `stvec`, sets its stack, and calls
+`appMain` (see `uproc/gsp/src/kernel/start.S`). It expects falcon/CSB register
+windows, a TCM/MPU layout and a PMU-provided environment that `qemu virt`
+does not have.
+
+**Therefore:** loading the raw `.fwimage` into `qemu virt` cannot boot it.
+The `greeneye probe` command is designed for exactly this: it loads the
+segments, runs bounded, and reports the first divergence
+(`guest_errors,unimp,int` log + stopped PC + symbol). That report is a *memory
+and control-flow map* of what the firmware tries to touch first — useful data,
+but not a boot.
+
+**Measured first-touch (2026-10-02, TU104 570.144 image).** The firmware
+enters at relocated `0x84009000`, executes six instructions, and faults at
+firmware vaddr `0x4009014` on a 4-byte read of `0x2000000000000A00`
+(load access fault), after which it falls into an `mtvec=0` fetch loop. That
+address is the first entry for the R1 device model's register map.
+
+## 4. Re-hosting the uproc components (the higher-fidelity path)
+
+The GSP firmware contains the uproc components (`gsp`, `os/libos`,
+`nvriscv`, `sec2*`, `soe*`, `pmu_sw`, `conf_compute`, …). Re-hosting them
+means compiling a *subset* against a QEMU-virt platform shim:
+
+| Area | Can be faithful | Cannot be faithful |
+|---|---|---|
+| task/RPC logic, parsers, state machines | yes — this is ordinary code | — |
+| memory layout of app-owned structures | yes, if schemas/addresses are pinned | TCM/MPU protections |
+| libos scheduler semantics | approximated (round-robin, timers) | real interrupt latencies, partition switching |
+| register/CSB access, falcon windows | stubbed with recorded behaviour | true device semantics |
+| PMU/SEC2/ACR/Booter interactions | modelled as messages | boot ROM, secure state machines |
+
+Re-host fidelity must be stated per module in the session metadata, and every
+"this is what the firmware does" claim should be cross-checked against the
+physical RPC traces (PLAN B) before it is used to change the emulation.
+
+## 5. Measurement contract for `gsp-rm-vfio` accuracy
+
+Define these metrics once and use them everywhere:
+
+| # | Metric | How it is measured |
+|---|---|---|
+| M1 | **Inventory coverage** | set of controls/RPCs observed in a real run vs the emulation's handled set (and green-eye's observed set) |
+| M2 | **Reply agreement** | field-by-field diff of replies (real vs emulated); canonical-size and consumed-field checks included |
+| M3 | **Ordering agreement** | sequence alignment of the control/event stream (edit distance / LCS) |
+| M4 | **State agreement** | state-machine transitions observed in the firmware vs the emulation's internal state model |
+| M5 | **Error-path agreement** | injected faults produce the same status/notifier path |
+| M6 | **Memory side-effects** | read/write map agreement against the emulation's shadow state; snapshot hashes for fixed points |
+| M7 | **Timing** | *not claimed*; only order-of-events budgets (e.g. "reply before the 4 s poll") |
+
+Reference capture:
+* real hardware/backend: the project's existing RPC logs (module trace,
+  `gsp-phys-log-dump`, status-queue drains) and the static-config oracle;
+* green-eye: `events.jsonl` + snapshots, symbol-annotated.
+
+Comparison: `greeneye compare dumps/real-<run> dumps/greeneye-<run>
+--symbols`, then a short table of M1–M6 with counts. Never publish a single
+"accuracy %" number without the metric breakdown.
+
+## 6. Adversarial interoperability use
+
+green-eye is also a safe place to be adversarial: corrupt a reply, flip a
+capability bit, truncate a control payload, or inject a fault at a chosen
+firmware PC, then observe whether the emulation and the firmware agree on the
+failure path. The rules:
+
+1. The simulator's reaction is *evidence about the firmware*, not about
+   silicon. Confirm any conclusion against a physical cycle before it changes
+   the product.
+2. Keep the injected fault and the observed path in the session recording.
+3. Do not use simulator timing as a security proof (side-channel claims need
+   physical measurement).
+
+## 7. Validating the tool itself
+
+Before trusting a green-eye session:
+
+* the demo firmware self-test must pass (`greeneye demo`, `make test`);
+* the session must contain the expected `hook`/`watch` registrations and a
+  coherent `bp_hit` sequence (the analyzer highlights empty sessions);
+* the UART banner and control-block magic are cheap liveness checks;
+* golden sessions (checked-in expectations) for the demo detect regressions
+  in the toolchain itself.
+
+## 8. Known accuracy gaps (living list)
+
+1. No TU104 device model: no boot beyond the first unmapped access.
+2. No time/concurrency model; multi-core and partition-switch behaviour is
+   approximated.
+3. PMU/SEC2/ACR/Booter behaviour is message-level only.
+4. Re-hosted uproc code is compiled for `qemu virt`, so compiler/layout
+   differences with the shipped image must be accounted for when comparing
+   control flow.
+5. Interrupt delivery and MSI semantics differ; error-path M5 is the weakest
+   metric until the device model exists (08).
+
+Each gap maps to a roadmap item; do not silently ignore them in reports.