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, 40 insertions, 31 deletions

diff --git a/kernel/gsp_emulation.c b/kernel/gsp_emulation.c
index 60805eb..bfd8be7 100644
--- a/kernel/gsp_emulation.c
+++ b/kernel/gsp_emulation.c
@@ -239,16 +239,23 @@ static int gsp_emu_dispatch_rpc(struct gsp_emu_context *ctx,
 
 void gsp_emu_inject_completion_interrupt(struct gsp_emu_context *ctx, u32 seq_id)
 {
+    struct eventfd_ctx *trigger = NULL;
+
     /* Write to MSI-X PBA (Pending Bit Array) at BAR0+0x3000 */
     if (ctx->bar0_vaddr) {
         u32 *pba = (u32 *)(ctx->bar0_vaddr + GSP_EMU_MSIX_PBA_OFFSET);
         writel(1, pba); /* Set pending bit for vector 0 */
     }
 
+    /* Look up the vector-0 trigger LIVE: QEMU wires eventfds via
+     * VFIO_DEVICE_SET_IRQS after gsp_emu_init runs, so an init-time copy
+     * would be stale (NULL). */
+    if (ctx->vgpu)
+        trigger = ctx->vgpu->irqs[0].trigger;
+
     /* Signal eventfd for VFIO interrupt delivery */
-    if (ctx->msix_trigger[0]) {
-        eventfd_signal(ctx->msix_trigger[0]);
-    }
+    if (trigger)
+        eventfd_signal(trigger);
 }
 
 /* ============================================================
@@ -321,6 +328,7 @@ static int gsp_emu_thread_fn(void *data)
 
 int gsp_emu_init(struct nv_vgpu_device *vgpu)
 {
+    struct nv_vgpu_bar_emul_ctx *bar_ctx;
     struct gsp_emu_context *ctx;
     int ret = 0;
 
@@ -337,46 +345,47 @@ int gsp_emu_init(struct nv_vgpu_device *vgpu)
     init_completion(&ctx->thread_stopped);
     spin_lock_init(&ctx->lock);
 
-    /* Use already-mapped BAR0 virtual address (mapped by nv_vgpu_bar_init) */
-    if (!vgpu->bars[0].vaddr) {
-        nv_vgpu_err(vgpu, "BAR0 virtual address not available");
+    /* The guest's BAR0 is the emulation shadow (vzalloc'd by
+     * nv_vgpu_bar_emul_init, mapped to the guest via VFIO mmap) - NOT the
+     * host physical BAR0 (vgpu->bars[0].vaddr, which belongs to the real GPU
+     * and the host nvidia driver). All guest doorbell writes, RPC messages,
+     * MSI-X table writes and PBA reads land in the shadow, so the emulation
+     * engine must operate on the shadow exclusively. Polling the physical
+     * BAR0 would never see guest traffic and would corrupt host GPU state. */
+    bar_ctx = (struct nv_vgpu_bar_emul_ctx *)vgpu->bar_emul_ctx;
+    if (!bar_ctx || !bar_ctx->bar0_shadow) {
+        nv_vgpu_err(vgpu, "BAR0 emulation shadow not available");
         ret = -ENODEV;
         goto err_free_ctx;
     }
 
-    ctx->bar0_vaddr = vgpu->bars[0].vaddr;
+    ctx->bar0_vaddr = (void __iomem *)bar_ctx->bar0_shadow;
 
-    /* Locate doorbell register at BAR0+0x110C00 */
+    /* Doorbell register at BAR0+0x110C00 (guest-visible shadow) */
     ctx->doorbell_reg = ctx->bar0_vaddr + GSP_EMU_DOORBELL_OFFSET;
 
-    /* Allocate shared memory (4KB, page-aligned, WC mapping) */
+    /* RPC shared memory at BAR0+0x1000. This ALIASES the guest-visible
+     * shadow - it is NOT a separate allocation. shared_mem_dma stays 0 to
+     * mark it as aliased so cleanup does not dma_free it. */
     ctx->shared_mem_size = GSP_EMU_SHARED_MEM_SIZE;
-    ctx->shared_mem_virt = dma_alloc_wc(&vgpu->pdev->dev, ctx->shared_mem_size,
-                                         &ctx->shared_mem_dma, GFP_KERNEL);
-    if (!ctx->shared_mem_virt) {
-        nv_vgpu_err(vgpu, "Failed to allocate shared memory");
-        ret = -ENOMEM;
-        goto err_free_ctx;
-    }
-
-    /* Map shared memory into guest BAR0 at offset 0x1000 */
     ctx->shared_mem = ctx->bar0_vaddr + GSP_EMU_SHARED_MEM_OFFSET;
+    ctx->shared_mem_virt = (void *)ctx->shared_mem;
+    ctx->shared_mem_dma = 0;
 
-    /* Initialize RPC client with already-mapped BAR0 virtual address and doorbell */
+    /* Initialize RPC client with the shadow BAR0 base and doorbell */
     ctx->rpc_client = gsp_client_init_emulation(&vgpu->dev, ctx->bar0_vaddr, ctx->doorbell_reg);
     if (IS_ERR(ctx->rpc_client)) {
         ret = PTR_ERR(ctx->rpc_client);
         nv_vgpu_err(vgpu, "Failed to init GSP RPC client: %d", ret);
-        goto err_free_shared_mem;
+        goto err_free_ctx;
     }
 
     /* Enable emulation mode in RPC client */
     gsp_rpc_emulation_set(true);
 
-    /* Get MSI-X eventfd triggers from IRQ context */
-    for (int i = 0; i < NV_VGPU_MAX_IRQS; i++) {
-        ctx->msix_trigger[i] = vgpu->irqs[i].trigger;
-    }
+    /* NOTE: MSI-X eventfd triggers are NOT copied here - QEMU wires them
+     * via VFIO_DEVICE_SET_IRQS later, so gsp_emu_inject_completion_interrupt
+     * looks them up live from vgpu->irqs[]. */
 
     /* Start emulation thread */
     ctx->thread = kthread_run(gsp_emu_thread_fn, ctx, "gsp_emu_%u", vgpu->vgpu_id);
@@ -395,10 +404,9 @@ int gsp_emu_init(struct nv_vgpu_device *vgpu)
 
 err_fini_client:
     gsp_client_fini(ctx->rpc_client);
-err_free_shared_mem:
-    dma_free_wc(&vgpu->pdev->dev, ctx->shared_mem_size,
-                ctx->shared_mem_virt, ctx->shared_mem_dma);
 err_free_ctx:
+    /* shared_mem_virt aliases the BAR0 shadow (owned by bar_emulation),
+     * nothing to free here */
     kfree(ctx);
     return ret;
 }
@@ -433,14 +441,15 @@ void gsp_emu_cleanup(struct nv_vgpu_device *vgpu)
         ctx->rpc_client = NULL;
     }
 
-    /* Free shared memory */
-    if (ctx->shared_mem_virt) {
+    /* Shared memory aliases the BAR0 shadow (owned by bar_emulation) -
+     * only free it if it was a standalone DMA allocation (dma != 0) */
+    if (ctx->shared_mem_virt && ctx->shared_mem_dma) {
         dma_free_wc(&vgpu->pdev->dev, ctx->shared_mem_size,
                     ctx->shared_mem_virt, ctx->shared_mem_dma);
-        ctx->shared_mem_virt = NULL;
     }
+    ctx->shared_mem_virt = NULL;
 
-    /* BAR0 is managed by nv_vgpu_bar_init/cleanup, don't unmap here */
+    /* BAR0 shadow is managed by nv_vgpu_bar_emul_init/cleanup */
     ctx->bar0_vaddr = NULL;
 
     vgpu->gsp_comm_ctx = NULL;