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

diff --git a/legacy-driver-guest/debugfs/gsp_debugfs.c b/legacy-driver-guest/debugfs/gsp_debugfs.c
new file mode 100644
index 0000000..f3df124
--- /dev/null
+++ b/legacy-driver-guest/debugfs/gsp_debugfs.c
@@ -0,0 +1,273 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * GSP vGPU-IO Driver - Debugfs Interface
+ */
+
+#include "gsp_core.h"
+#include <linux/debugfs.h>
+#include <linux/seq_file.h>
+
+static int gsp_debugfs_vfs_show(struct seq_file *s, void *unused)
+{
+    struct gsp_device *gsp = s->private;
+    struct gsp_vf *vf;
+    
+    seq_printf(s, "%-4s %-12s %-10s %-18s %-18s\n",
+               "ID", "STATE", "REFCNT", "BAR1", "PAGE_TABLE");
+    
+    mutex_lock(&gsp->vf_lock);
+    list_for_each_entry(vf, &gsp->vf_list, list) {
+        seq_printf(s, "%-4u %-12d %-10d 0x%016llx-0x%016llx 0x%016llx-0x%016llx\n",
+                   vf->id, vf->state, atomic_read(&vf->refcount),
+                   vf->bar1_offset, vf->bar1_offset + vf->bar1_size,
+                   vf->pt_base, vf->pt_base + vf->pt_size);
+    }
+    mutex_unlock(&gsp->vf_lock);
+    
+    return 0;
+}
+
+static int gsp_debugfs_vfs_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_vfs_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_vfs_fops = {
+    .open = gsp_debugfs_vfs_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+static int gsp_debugfs_vf_show(struct seq_file *s, void *unused)
+{
+    struct gsp_vf *vf = s->private;
+    struct gsp_wpr_region *rgn;
+    
+    seq_printf(s, "VF %u\n", vf->id);
+    seq_printf(s, "  State:       %d\n", vf->state);
+    seq_printf(s, "  Refcount:    %d\n", atomic_read(&vf->refcount));
+    seq_printf(s, "  BAR1:        0x%llx - 0x%llx (size: 0x%llx)\n",
+               vf->bar1_offset, vf->bar1_offset + vf->bar1_size, vf->bar1_size);
+    seq_printf(s, "  Page Table:  0x%llx - 0x%llx (size: 0x%llx)\n",
+               vf->pt_base, vf->pt_base + vf->pt_size, vf->pt_size);
+    seq_printf(s, "  Cmd Buffer:  0x%llx - 0x%llx (size: 0x%llx)\n",
+               vf->cmd_base, vf->cmd_base + vf->cmd_size, vf->cmd_size);
+    seq_printf(s, "  BAR State:\n");
+    seq_printf(s, "    Aperture:  0x%llx - 0x%llx\n",
+               vf->bar_state.aperture_offset,
+               vf->bar_state.aperture_offset + vf->bar_state.aperture_size);
+    seq_printf(s, "    ForceAcc:  %s (VF: %u)\n",
+               vf->bar_state.force_access ? "enabled" : "disabled",
+               vf->bar_state.force_vf);
+    seq_printf(s, "  WPR Regions:\n");
+    
+    mutex_lock(&vf->wpr_lock);
+    list_for_each_entry(rgn, &vf->wpr_list, list) {
+        seq_printf(s, "    [0x%llx, 0x%llx) flags=0x%x\n",
+                   rgn->base, rgn->base + rgn->size, rgn->flags);
+    }
+    mutex_unlock(&vf->wpr_lock);
+    
+    if (vf->migration) {
+        seq_printf(s, "  Migration:\n");
+        seq_printf(s, "    State:     %d\n", vf->migration->state);
+        seq_printf(s, "    Dst VF:    %llu\n", vf->migration->dst_vf);
+        seq_printf(s, "    Token:     0x%llx\n", vf->migration->token);
+        seq_printf(s, "    Progress:  %llu pages, %llu bytes\n",
+                   vf->migration->progress.pages_transferred,
+                   vf->migration->progress.bytes_transferred);
+    }
+    
+    return 0;
+}
+
+static int gsp_debugfs_vf_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_vf_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_vf_fops = {
+    .open = gsp_debugfs_vf_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+static int gsp_debugfs_rpc_show(struct seq_file *s, void *unused)
+{
+    struct gsp_device *gsp = s->private;
+    
+    seq_printf(s, "RPC Statistics:\n");
+    seq_printf(s, "  Total:       %lld\n", atomic64_read(&gsp->rpc_total));
+    seq_printf(s, "  Errors:      %lld\n", atomic64_read(&gsp->rpc_errors));
+    seq_printf(s, "  BAR Traps:   %lld\n", atomic64_read(&gsp->bar_traps));
+    seq_printf(s, "  WPR Events:  %lld\n", atomic64_read(&gsp->wpr_events));
+    seq_printf(s, "  Migrations:  %lld\n", atomic64_read(&gsp->migrations));
+    
+    return 0;
+}
+
+static int gsp_debugfs_rpc_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_rpc_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_rpc_fops = {
+    .open = gsp_debugfs_rpc_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+static int gsp_debugfs_bar_show(struct seq_file *s, void *unused)
+{
+    struct gsp_vf *vf = s->private;
+    
+    seq_printf(s, "VF %u BAR State:\n", vf->id);
+    seq_printf(s, "  Aperture Offset:  0x%llx\n", vf->bar_state.aperture_offset);
+    seq_printf(s, "  Aperture Size:    0x%llx\n", vf->bar_state.aperture_size);
+    seq_printf(s, "  Force Access:     %s\n", vf->bar_state.force_access ? "enabled" : "disabled");
+    seq_printf(s, "  Force VF:         %u\n", vf->bar_state.force_vf);
+    seq_printf(s, "  Backing Store:    %p\n", vf->bar_state.backing_store);
+    seq_printf(s, "  Backing Size:     0x%zx\n", vf->bar_state.backing_size);
+    
+    return 0;
+}
+
+static int gsp_debugfs_bar_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_bar_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_bar_fops = {
+    .open = gsp_debugfs_bar_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+static int gsp_debugfs_wpr_show(struct seq_file *s, void *unused)
+{
+    struct gsp_vf *vf = s->private;
+    struct gsp_wpr_region *rgn;
+    
+    seq_printf(s, "VF %u WPR Regions:\n", vf->id);
+    
+    mutex_lock(&vf->wpr_lock);
+    list_for_each_entry(rgn, &vf->wpr_list, list) {
+        seq_printf(s, "  [0x%llx, 0x%llx) size=0x%llx flags=0x%x\n",
+                   rgn->base, rgn->base + rgn->size, rgn->size, rgn->flags);
+    }
+    mutex_unlock(&vf->wpr_lock);
+    
+    return 0;
+}
+
+static int gsp_debugfs_wpr_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_wpr_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_wpr_fops = {
+    .open = gsp_debugfs_wpr_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+static int gsp_debugfs_migration_show(struct seq_file *s, void *unused)
+{
+    struct gsp_vf *vf = s->private;
+    
+    if (!vf->migration) {
+        seq_printf(s, "No active migration\n");
+        return 0;
+    }
+    
+    seq_printf(s, "VF %u Migration:\n", vf->id);
+    seq_printf(s, "  State:           %d\n", vf->migration->state);
+    seq_printf(s, "  Destination VF:  %llu\n", vf->migration->dst_vf);
+    seq_printf(s, "  Token:           0x%llx\n", vf->migration->token);
+    seq_printf(s, "  Flags:           0x%x\n", vf->migration->flags);
+    seq_printf(s, "  Pages Xfer:      %llu\n", vf->migration->progress.pages_transferred);
+    seq_printf(s, "  Bytes Xfer:      %llu\n", vf->migration->progress.bytes_transferred);
+    seq_printf(s, "  Dirty Pages:     %llu\n", vf->migration->progress.dirty_pages);
+    seq_printf(s, "  Cancelled:       %s\n", vf->migration->cancelled ? "yes" : "no");
+    
+    return 0;
+}
+
+static int gsp_debugfs_migration_open(struct inode *inode, struct file *file)
+{
+    return single_open(file, gsp_debugfs_migration_show, inode->i_private);
+}
+
+static const struct file_operations gsp_debugfs_migration_fops = {
+    .open = gsp_debugfs_migration_open,
+    .read = seq_read,
+    .llseek = seq_lseek,
+    .release = single_release,
+};
+
+/* VF Debugfs Directory Creation */
+static void gsp_debugfs_vf_create(struct gsp_vf *vf)
+{
+    char name[16];
+    struct dentry *vf_dir;
+    
+    snprintf(name, sizeof(name), "vf%u", vf->id);
+    vf_dir = debugfs_create_dir(name, vf->gsp->debugfs_vfs_dir);
+    if (!vf_dir)
+        return;
+    
+    debugfs_create_file("status", 0444, vf_dir, vf, &gsp_debugfs_vf_fops);
+    debugfs_create_file("bar", 0444, vf_dir, vf, &gsp_debugfs_bar_fops);
+    debugfs_create_file("wpr", 0444, vf_dir, vf, &gsp_debugfs_wpr_fops);
+    debugfs_create_file("migration", 0444, vf_dir, vf, &gsp_debugfs_migration_fops);
+}
+
+/* Main Debugfs Init */
+int gsp_debugfs_init(struct gsp_device *gsp)
+{
+    gsp->debugfs_root = debugfs_create_dir("gsp-vgpu", NULL);
+    if (!gsp->debugfs_root)
+        return -ENOMEM;
+    
+    debugfs_create_file("vfs", 0444, gsp->debugfs_root, gsp, &gsp_debugfs_vfs_fops);
+    debugfs_create_file("rpc", 0444, gsp->debugfs_root, gsp, &gsp_debugfs_rpc_fops);
+    
+    gsp->debugfs_vfs_dir = debugfs_create_dir("vfs", gsp->debugfs_root);
+    if (!gsp->debugfs_vfs_dir) {
+        debugfs_remove_recursive(gsp->debugfs_root);
+        return -ENOMEM;
+    }
+    
+    /* Create entries for existing VFs */
+    mutex_lock(&gsp->vf_lock);
+    struct gsp_vf *vf;
+    list_for_each_entry(vf, &gsp->vf_list, list)
+        gsp_debugfs_vf_create(vf);
+    mutex_unlock(&gsp->vf_lock);
+    
+    return 0;
+}
+
+void gsp_debugfs_fini(struct gsp_device *gsp)
+{
+    if (gsp->debugfs_root)
+        debugfs_remove_recursive(gsp->debugfs_root);
+}
+
+/* Export for VF creation/destruction */
+void gsp_debugfs_vf_add(struct gsp_vf *vf)
+{
+    gsp_debugfs_vf_create(vf);
+}
+
+void gsp_debugfs_vf_remove(struct gsp_vf *vf)
+{
+    char name[16];
+    snprintf(name, sizeof(name), "vf%u", vf->id);
+    debugfs_remove_recursive(debugfs_lookup(name, vf->gsp->debugfs_vfs_dir));
+}
\ No newline at end of file