kernel: Fix GSP emulation shadow binding, eventfd wiring, RPC livelocks + docs suite + repo reorg

CRITICAL FIXES (guest driver bring-up):
- gsp_emulation.c: emulation engine bound to the WRONG BAR0 - it polled the
  host physical BAR0 (bars[0].vaddr ioremap) for the doorbell and read RPCs
  from a local dma_alloc_wc buffer, while the guest writes land in the
  vzalloc'd bar0_shadow. The RPC path could never work; PBA writes even
  corrupted the host GPU's physical BAR0+0x3000. gsp_emu_init now binds
  exclusively to bar0_shadow (doorbell/mailbox/PBA aliases;
  shared_mem_dma==0 marks the alias so cleanup never dma_free's it).
- main.c SET_IRQS: DATA_EVENTFD eventfds were DISCARDED ('TODO' + kfree) -
  the guest never received MSI-X completions. Full wiring now:
  eventfd_ctx_fdget per vector, fd -1 clears, dev_close releases refs.
  gsp_emu_inject_completion_interrupt looks up vgpu->irqs[0].trigger LIVE
  (init-time copy was permanently NULL since QEMU wires after gsp_emu_init).
- gsp_rpc_client.c: BAR_TRAP/MIGRATE in emulation mode called
  gsp_rpc_submit_raw which rings the SAME doorbell the thread polls -
  self-triggered RPC livelock + multi-second stalls. Now fail fast with
  -ENOTSUPP + pr_warn_ratelimited (guest BAR access is direct MMIO).

MORE FIXES:
- main.c: nv_vgpu_config_write returned SIZE_MAX (while(count--) wrap) and
  was dead code while the VFIO write handler did unfiltered byte copies
  (guest could rewrite vendor ID/BARs). Return fixed; VFIO write handler
  now routes through the per-register filter.
- kernel/Makefile: M=$(PWD) used the env var which is stale when invoked
  via the top-level make (pointed at repo root -> kbuild silently built
  NOTHING; explains every 'stale .ko' incident). Now M=$(CURDIR).
- Warnings sweep: header prototypes for mdev/type functions, format casts
  in gsp_comm.c DRY-RUN logs, unused variable.

ROBUSTNESS (harness/tooling):
- vgpu_vm.py: run had no timeout (start could block forever);
  guest_shell recv could block forever on a wedged guest. Both now bounded;
  guest_shell pre-flights guest-ping and reports wedge diagnostics.
- stack_manager.sh: qemu/qemu-debug now launch via the vgpu_vm.py harness
  (workflow rule: never raw QEMU).

REPO REORGANIZATION:
- driver/ (legacy guest-side gsp-vgpu.ko) moved to legacy-driver-guest/
  (reference only, not built; README explains). 3 legacy un-buildable test
  files moved to legacy-driver-guest/kernel-tests/. Top-level Makefile
  cleaned of the dead DRIVER_DIR reference.

DOCUMENTATION SUITE (new):
- docs/GSP_EMULATION_ARCHITECTURE.md - emulator deep-dive: shadow BAR0
  model, doorbell protocol, dispatch table, MSI-X path, lifecycle, memory-
  model caveats
- docs/DEBUGGING.md - QEMU GDB stub workflow, serial console, QMP NMI,
  failure taxonomy, full bring-up validation checklist, EPT-livelock case
  study, version-matrix discipline
- docs/ONBOARDING.md - repo tour, coding standards (incl. virt_to_phys /
  dma_addr_t / get-put rules), first build & test
- docs/VERSION_UPGRADE.md - end-to-end new-driver-version procedure
  (firmware fetch, Ghidra analysis, configs, signatures, validation)
- docs/PERFORMANCE.md - bare-metal A/B methodology + targets
- README.md doc index; STATE.md refreshed; DEVELOPMENT_WORKFLOW.md corrected
  (load order: open-iov-vfio BEFORE nvidia; stock-driver blacklist note)

1 files changed, 98 insertions, 0 deletions

diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
new file mode 100644
index 0000000..6077920
--- /dev/null
+++ b/docs/PERFORMANCE.md
@@ -0,0 +1,98 @@
+# Open-IOV Performance Testing & A/B Methodology
+
+> How we measure vGPU performance against bare metal, interpret the results,
+> and keep overhead on the critical path honest. **Run correctness first**
+> (`docs/DEBUGGING.md` §5) — numbers from a half-working stack are noise.
+
+---
+
+## 1. What overhead is acceptable (targets)
+
+| Path | Target | Why |
+|------|--------|-----|
+| GSP RPC round-trip (doorbell→response→MSI-X) | < 50 µs (stretch: < 10 µs) | every driver op goes through here |
+| MSI-X injection (eventfd → guest handler) | < 5 µs | completion latency dominates |
+| Guest BAR0 MMIO read/write | < 2 µs (shadow RAM) | hot path for register polling |
+| CUDA kernel launch (added overhead vs bare metal) | < 10% | user-visible |
+| Memory alloc/map RPCs | < 100 µs | setup-time, amortized |
+| CUDA compute throughput | ≥ 95% of bare metal | GPU-bound, should be ~free |
+| Graphics (frame rate) | ≥ 90% of bare metal | swapchain + submission overhead |
+
+## 2. The A/B rule
+
+Every measurement runs **twice on the same machine, same boot if possible**:
+
+- **A (bare metal)**: workload on the physical GPU via the host's stock
+  driver (or our OpenRM nvidia.ko directly on the hardware).
+- **B (vGPU)**: identical workload in the guest on the emulated vGPU.
+
+Same binary, same input sizes, same environment (governor, clocks, hugepages).
+Report **B/A ratio %** — never absolute numbers alone.
+
+One variable at a time. If B regresses, you changed the stack, the workload,
+or the machine — find which before optimizing.
+
+## 3. Microbenchmarks (build these first)
+
+1. **RPC round-trip**: from the guest, submit a DEBUG/NOOP-ish RPC in a loop;
+   time doorbell-write → response-visible. Host side: `gsp_emu_get_stats()`
+   gives `total_latency_ns` and counts — divide for per-RPC host cost.
+   (Add `trace_printk` in `gsp_emu_dispatch_rpc` entry/exit for distribution;
+   read via `/sys/kernel/debug/tracing/trace`.)
+2. **MSI-X latency**: timestamp (guest TSC) at RPC submit → in the guest
+   driver's interrupt handler. Compare with the host eventfd_signal timestamp.
+3. **BAR0 shadow read latency**: guest loops reading a shadow register;
+   expect ~memory speed (uncached, so ~100-300 ns) — anything ≥ 1 µs means
+   you're trapping somewhere you shouldn't.
+4. **Doorbell polling cost**: host `top`/`perf` on `gsp_emu_N` — the adaptive
+   poll (busy → 50-100 µs sleep) should sit at ~0% CPU when idle, and react
+   within one sleep quantum under load. Tune `GSP_EMU_POLL_*` only with data.
+
+## 4. Workload benchmarks
+
+Runner: `tools/benchmark_infrastructure.sh` (extend it; keep the A/B pattern).
+In-guest execution goes through the harness (`vgpu_vm.py exec`) or the guest
+test agent (`tools/guest_agent/`).
+
+| Suite | What | Pass criterion |
+|-------|------|----------------|
+| `cuda-samples vectorAdd` | smoke + element-wise throughput | correct result; ≥ 95% B/A |
+| `simpleCUBLAS` | SGEMM TFLOPS | ≥ 95% B/A |
+| `nvbandwidth` (if available) | H2D/D2H/device copy GB/s | report; DMA path validation |
+| `glxgears -info` / a real GL app | frame rate | ≥ 90% B/A |
+| `nvenc`/`nvdec` sample | transcode fps | functional (perf later) |
+| PyTorch CUDA op (matmul loop) | end-to-end framework | ≥ 90% B/A |
+
+Always log: guest/host driver versions, GPU clocks (`nvidia-smi -q -d CLOCK`
+both sides — throttling skews everything), and the command lines.
+
+## 5. Where the overhead lives (profile in this order)
+
+1. **RPC dispatch** — the single biggest lever. Everything the guest driver
+   does funnels through the emulation thread.
+2. **Doorbell polling cadence** — too slow = latency; too hot = host CPU burn.
+3. **eventfd/MSI-X delivery** — measure, don't assume.
+4. **BAR0 uncached semantics** — shadow is UC for the guest; that's
+   MMIO-correct but slow for large reads. If the driver bulk-reads shadow,
+   consider caching-safe sub-regions.
+5. **Memory model gap** (ALLOC host-pages vs BAR1 direct VRAM) — see
+   `docs/GSP_EMULATION_ARCHITECTURE.md` §3. Until unified, DMA-heavy
+   workloads are not representative.
+
+## 6. Optimizing safely
+
+- Change one thing, re-run the A/B pair, keep the numbers with the commit.
+- Never optimize off bare-metal-only data: the goal is B/A, not A.
+- If a change makes B faster but breaks the §5 validation checklist in
+  `docs/DEBUGGING.md`, it doesn't count.
+- Record results in `STATE.md` (date, versions, B/A ratios) so regressions
+  are visible across commits.
+
+## 7. Reporting template
+
+```
+Date / commit / versions (guest=host=firmware=emulation):
+Machine / GPU / clocks locked?:
+Test, unit, A (bare), B (vGPU), B/A %:
+Notes (what changed vs last run):
+```