1 files changed, 126 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md b/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md
new file mode 100644
index 0000000..5426bf1
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/07-PORTABILITY-PLAYBOOKS.md
@@ -0,0 +1,126 @@
+# 07 — Portability playbooks: new GSP, new device, new architecture
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+
+These playbooks cover the three churn axes the project expects: a new GSP
+firmware version, the same firmware on a new device, and a new GPU
+architecture (e.g. GB10 / DGX Spark / Surface-class). They reuse the
+project's existing version discipline and add green-eye's runtime layer.
+
+## 0. Common setup
+
+1. Acquire the firmware for the target (driver runfile or `linux-firmware`):
+   extract the GSP boot image (`.fwimage`) and record its hash. For TU10x,
+   `firmware/57X-GSP/<ver>/gsp-<ver>.fwimage.bin` is the extracted form.
+2. Lay down a versioned directory; never overwrite a working version.
+3. Build a symbol DB for the new image:
+   * import the fwimage into the existing Ghidra project tooling
+     (`tools/ghidra/analyze_fwimage.py`, `DecompileFunctions.java`),
+   * `./greeneye.sh symbols export --index <export.tsv> -o symbols-<ver>.json`.
+4. Record a baseline session of the previous version (see P1.4) so the
+   comparison has an anchor.
+
+## P1. New GSP firmware version (same family)
+
+**Goal:** know what changed in the firmware's runtime behaviour before the
+emulation is adjusted.
+
+1. **Static triage** — the project's existing flow: decompile the new
+   fwimage, diff the RPC dispatcher, subcommands, message layouts and version
+   strings against the previous version (`cudatool.py delta`-style discipline
+   for firmware; `diff_corpus.py` for the corpus).
+2. **Probe the new image** — `./greeneye.sh probe <new.fwimage>`: record the
+   first divergence and the first MMIO/read/write addresses. Compare with the
+   previous version's probe; changed first-touch addresses are early
+   structure-change signals.
+3. **Re-host / demo run** — if uproc sources for the family are available,
+   build the rehosted subset against the QEMU-virt shim and run the same
+   scripted stimulus used for the previous version.
+4. **Baseline + candidate sessions** — for each version capture:
+   * `greeneye record --kernel <rehosted elf> --duration N --snapshot <regions>`
+     or the scripted harness (`run`),
+   * the real-backend reference traces for the same workload.
+5. **Compare** — `./greeneye.sh compare dumps/<old> dumps/<new> --symbols`:
+   hit-count deltas per function, watchpoint deltas, written-page deltas.
+   Investigate every function whose call-count changed before touching the
+   emulation.
+6. **Metrics** — fill in M1–M6 from `06-ACCURACY.md` for the new version
+   against the real backend. Attach the table to the version-bump PR.
+7. **Acceptance** — no rung regression in the existing guest ladder, the
+   control inventory diff is explained, and every new/changed control has a
+   version-keyed handler or an explicit "not used" note.
+
+## P2. Same GSP version, new device
+
+**Goal:** prove device-profile portability (the project direction is
+"configuration + verification, not new code").
+
+1. Collect the device profile: PCI IDs, BAR layout/sizes, FB geometry,
+   engine inventory, interrupt topology, VBIOS/ROM specifics.
+2. Verify the firmware pairing: the image family (TU10x/GH100/LS10 …), FMC
+   partition manifests, and the version string; a mismatched pairing presents
+   as an emulation bug (the project learned this with 570.144 vs 570.211).
+3. `./greeneye.sh probe <device fwimage>` on the new device image; compare
+   first-divergence maps with the reference device. Differences here usually
+   point at profile data, not logic.
+4. Re-run the P1.4/1.5 loop with the device profile applied; record probe +
+   compare evidence in the portability matrix.
+5. Validate on the physical device with the supervised harness before
+   claiming support (`docs/06-portability/hardware-software-matrix.md`
+   discipline: tested and documented, not "should work").
+
+## P3. New architecture (GB10 / DGX Spark / Surface-class)
+
+**Goal:** survive a new silicon generation (likely a newer NV-RISCV core,
+newer PMU/SEC2 images and possibly RV64GC rather than RV64IMAC).
+
+1. **Confirm the ISA and image shape** — `file`/`readelf` the new fwimage:
+   ISA string, segments, entry, compressed/float extensions. Update the
+   rehost build flags (`-march=…`) accordingly; note that QEMU supports
+   RV64GC even if green-eye's demo uses IMAC.
+2. **Check the platform's boot variant** — newer platforms use FMC/manifest
+   partition models (`uproc/*_riscv/fmc`, `safety/PMU-*`, `conf_compute`
+   Init→ACR→RM flow). Record which partition model the image uses; the
+   rehost shim needs a matching entry/return convention.
+3. **PMU/SOE deltas** — diff the PMU/SOE headers and firmware
+   (`pmu_sw`, `uproc/soe*`) because the GSP environment provisions identity
+   and clock state through them. Any change here invalidates prior
+   environment assumptions.
+4. **Run the P1 loop** with the new architecture profile; expect the probe to
+   show *different* first-touch addresses (new register windows). Update the
+   device-model scope in `08-ROADMAP.md` with what the probe revealed.
+5. **Host portability** — green-eye itself is Python and QEMU; on aarch64
+   hosts install `qemu-system-misc` there and the same commands run. Keep
+   host-specific paths out of session metadata.
+
+## P4. A/B: bare metal vs vfio-mdev (the core accuracy ritual)
+
+**Goal:** quantify how closely the virtual function's emulation tracks the
+real firmware for a chosen workload.
+
+1. **Reference capture (real):**
+   * hardware path: the supervised physical backend cycle, capturing RPC
+     records/log dumps and the static-config oracle;
+   * or the vfio-mdev path with the same workload.
+   Save the reference event stream in a session-compatible form (or the
+   vendor logs plus a conversion note).
+2. **green-eye capture:** run the same workload's firmware-side stimulus in
+   the rehosted simulator; record hooks, watchpoints, snapshots.
+3. **Compare:** `greeneye compare` for hit/watch/write profiles; for RPC
+   payloads use M2 field agreement and M3 ordering (a small script or a
+   plugin can emit per-control events).
+4. **Report:** metric table (M1–M6), changed-function list, and an explicit
+   statement of L2/L3 limits from `06-ACCURACY.md`.
+5. **Escalation:** a divergence that changes emulation behaviour must be
+   reproduced on the physical backend before the fix lands; simulator-only
+   divergence that cannot be reproduced is recorded as a fidelity gap.
+
+## Evidence checklist (attach to any portability task)
+
+* firmware hash + version string + pairing notes;
+* `probe` output (first divergence, first-touch map);
+* symbol DB hash and the Ghidra export provenance;
+* session directories for baseline and candidate (or their sha256 list);
+* `compare` report;
+* M1–M6 table with the reference-capture method;
+* unexplained diffs list (empty is a claim, not a default).