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, 104 insertions, 0 deletions

diff --git a/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md b/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md
new file mode 100644
index 0000000..216bf93
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/09-GSP-FIRMWARE-NOTES.md
@@ -0,0 +1,104 @@
+# 09 — GSP/uproc firmware notes used by green-eye
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+> Exact local-source provenance is recorded in the local task record; this
+> tracked document intentionally keeps source locations generic and cites
+> public material.
+
+## 1. The microcontrollers around the GPU
+
+From the open-iov wiki **GPU Firmware** page and the linked **NVIDIA RISC-V
+Story** presentation (the project mirrors the wiki locally; the PDF is a
+public RISC-V summit deck):
+
+* **Falcon (FAst Logic CONtroller)** is NVIDIA's proprietary control
+  processor, used across >15 hardware engines for over a decade. It was
+  designed for flexibility, long memory latency, low area and security.
+  Limits that forced a successor: small addressing range, modest performance
+  (~0.67 DMIPS/MHz, ~1.4 CoreMark/MHz), no data cache, no rich OS support.
+* **NV-RISCV** is NVIDIA's own implementation of a RISC-V core chosen as the
+  next-generation falcon: more performance (>2× falcon claimed), wider
+  addressing, TCM, vectored interrupts, security features (TZ-style), with
+  area targets under 0.1 mm² at 16FF.
+* The GPU hosts several of these cores: the **GSP** (GPU System Processor)
+  running a rich firmware stack, plus security/boot engines (**SEC2**, ACR,
+  SOE) and the **PMU** microcontroller. The RISC-V Story deck documents the
+  falcon-to-RV transition and the DMA/mailbox lines between engines.
+
+## 2. GSP application structure
+
+The GSP firmware is an ELF64 RV64IMAC image (the TU104 570.144 `.fwimage` used
+by the probe has entry `0x4009000`, 33 program headers, stripped). Its
+application layer is a multi-task RTOS program:
+
+* `_start` (hand-written assembly) sets the trap vector to an early panic
+  handler, initialises the stack, pushes two zero words to help debugger
+  backtracing, and calls `appMain`. The **bootloader passes arguments in
+  a0–a5**: bootargs PA and VA, ELF PA and size, load base PA, and the
+  write-protected region id. A re-host harness must reproduce this ABI.
+* `init.c` creates the tasks and starts the RTOS; the included driver set
+  covers MPU, ODP (on-demand paging), memory, and the RISC-V system library.
+* The boot configuration selects `NVRISCV_PARTITION_SWITCH` variants, i.e.
+  images can run under a separation-kernel partition model.
+
+## 3. RTOS and libos layers
+
+Two OS layers appear in the vendor snapshots:
+
+* **SafeRTOS/NVRTOS** — the classic resident RTOS: priority scheduling,
+  timers, events/signals, IPC and DMA support; ~38 KiB TCM-resident kernel;
+  missing paging, task reset, capability security. Used by the GSP test
+  firmware partition model.
+* **LIBOS** (exokernel design, early draft) — designed to be TCM-resident
+  (projected 1–6 KiB), capability-based security, round-robin scheduler,
+  DMEM on-demand paging, module configuration so unused features are not
+  paid for. This is the direction the GSP stack evolves toward.
+
+**Implication for the simulator:** the scheduler is not the interesting part
+for RPC accuracy; the task/dispatcher semantics are. Green-eye's demo mirrors
+that shape (mailbox → dispatcher → handler → counters), and a rehost shim
+should stub the scheduler while keeping task entry points and message
+handling real.
+
+## 4. Boot and partition models
+
+* **MP-SK/FMC** (separation kernel): images are built as partitions. One
+  observed GSP test image has two partitions: a SafeRTOS first-stage
+  bootloader partition (clobbered after hand-off via partition switch), and a
+  high-sec test partition that reads performance counters, writes them to
+  shared memory and switches back.
+* **Confidential-compute skeleton**: six partition stubs — RM Proxy, RM
+  (mutually exclusive with RM Proxy), SPDM, ACR, Init and Attestation — with
+  the boot flow **Init → ACR → RM**. The vendor tooling side-loads images to
+  a live GSP with a debug command (`nvwatch …`) for bring-up.
+
+These models matter for portability: a new architecture may change the
+partition layout or boot order, and green-eye's probe is the quickest way to
+see the new first-touch sequence before a device model exists.
+
+## 5. Memory, DMA and registers
+
+* The firmware assumes **TCM** and an MPU (protection regions are generated
+  at link time); `qemu virt` has neither, so the probe loads segments into
+  RAM and faults at the first register access.
+* The engines exchange data over **CSB/TRANSCOM windows and mailboxes** with
+  DMA into host/FB memory; the physical backend work in Open-IOV already
+  models the message-queue side (status/command queues, doorbells) — that is
+  the layer green-eye can emulate first when R1 lands.
+* The GSP kernel's start path receives its memory permissions as boot args
+  from the bootloader rather than discovering them, which is why a
+  re-host should pass the same structure rather than re-derive it.
+
+## 6. How green-eye models this today (and honestly, does not)
+
+| Firmware aspect | green-eye v0.1 |
+|---|---|
+| Task/dispatcher/state-machine logic | modelled faithfully by the demo and by rehosted code |
+| RPC handler input/output behaviour | observable and recordable; schemas decode structures |
+| RTOS scheduling, interrupts, partition switch | approximated / absent |
+| Falcon/CSB/TCM/PMU registers | absent (probe reports first touch; R1 roadmap) |
+| Boot ROM chain (FWSEC/booter/SEC2) | out of scope for the VM; the physical backend owns it |
+
+Use the notes above when designing new rehost shims or a device model: the
+goal is to keep everything *above* the register/mailbox boundary real, and to
+model that boundary explicitly rather than pretend it away.