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, 64 insertions, 21 deletions

diff --git a/kernel/main.c b/kernel/main.c
index e0e823b..3da7dc6 100644
--- a/kernel/main.c
+++ b/kernel/main.c
@@ -671,8 +671,19 @@ static int nv_vgpu_vfio_dev_open(struct vfio_device *vdev)
 static void nv_vgpu_vfio_dev_close(struct vfio_device *vdev)
 {
 	struct nv_vgpu_device *vgpu = container_of(vdev, struct nv_vgpu_device, vfio_dev);
-	
+	int i;
+
 	pr_info("nvidia-vgpu-vfio: VFIO device close\n");
+
+	/* Release eventfd trigger references wired via SET_IRQS; the next
+	 * opener re-wires its own. Prevents fd/ctx leaks across VM restarts. */
+	for (i = 0; i < NV_VGPU_MAX_IRQS; i++) {
+		if (vgpu->irqs[i].trigger) {
+			eventfd_ctx_put(vgpu->irqs[i].trigger);
+			vgpu->irqs[i].trigger = NULL;
+		}
+	}
+
 	atomic_dec(&vgpu->vfio_dev_open_count);
 	wake_up(&vgpu->vfio_dev_close_wait);
 }
@@ -712,14 +723,17 @@ static ssize_t nv_vgpu_vfio_dev_write(struct vfio_device *vdev, const char __use
 	
 	pr_info("nvidia-vgpu-vfio: VFIO device write count=%zu pos=%lld (0x%llx)\n", count, pos, pos);
 
-	/* Config space region */
+	/* Config space region - route through the per-register filter so the
+	 * guest can only modify writable registers (not vendor/device IDs,
+	 * BAR addresses, capabilities structures, etc.) */
 	if (pos >= 0x70000000000ULL && pos < 0x70000000000ULL + 4096) {
 		loff_t cfg_pos = pos - 0x70000000000ULL;
-		size_t to_write = min(count, (size_t)(4096 - cfg_pos));
-		if (copy_from_user(vgpu->pci_config + cfg_pos, buf, to_write))
-			return -EFAULT;
-		*ppos += to_write;
-		return to_write;
+		ssize_t ret;
+
+		ret = nv_vgpu_config_write(vgpu, buf, count, &cfg_pos);
+		if (ret > 0)
+			*ppos += ret;
+		return ret;
 	}
 
 	return 0;
@@ -961,11 +975,21 @@ static long nv_vgpu_vfio_dev_ioctl(struct vfio_device *vdev, unsigned int cmd,
 
 		/* Handle DATA_EVENTFD */
 		if (irq_set_ptr->flags & VFIO_IRQ_SET_DATA_EVENTFD) {
+			int i, idx, wired = 0;
+
 			if (irq_set_ptr->count == 0) {
 				kfree(irq_set_ptr);
 				return -EINVAL;
 			}
 
+			if (irq_set_ptr->index > VFIO_PCI_REQ_IRQ_INDEX ||
+			    irq_set_ptr->start + irq_set_ptr->count > NV_VGPU_MAX_IRQS) {
+				pr_err("nvidia-vgpu-vfio: SET_IRQS out of range: index=%u start=%u count=%u\n",
+				       irq_set_ptr->index, irq_set_ptr->start, irq_set_ptr->count);
+				kfree(irq_set_ptr);
+				return -EINVAL;
+			}
+
 			fds = kcalloc(irq_set_ptr->count, sizeof(int), GFP_KERNEL);
 			if (!fds) {
 				kfree(irq_set_ptr);
@@ -980,21 +1004,38 @@ static long nv_vgpu_vfio_dev_ioctl(struct vfio_device *vdev, unsigned int cmd,
 				return -EFAULT;
 			}
 
-			/* For now, just store the eventfds for INTx and MSI-X */
-			if (irq_set_ptr->index == VFIO_PCI_INTX_IRQ_INDEX) {
-				pr_info("nvidia-vgpu-vfio: SET_IRQS INTx trigger fds[%d]\n", irq_set_ptr->count);
-				/* TODO: Store eventfds for INTx */
-			} else if (irq_set_ptr->index == VFIO_PCI_MSIX_IRQ_INDEX) {
-				pr_info("nvidia-vgpu-vfio: SET_IRQS MSI-X trigger fds[%d] start=%d\n", irq_set_ptr->count, irq_set_ptr->start);
-				/* TODO: Store eventfds for MSI-X vectors */
-			} else if (irq_set_ptr->index == VFIO_PCI_MSI_IRQ_INDEX) {
-				pr_info("nvidia-vgpu-vfio: SET_IRQS MSI trigger fds[%d]\n", irq_set_ptr->count);
-				/* TODO: Store eventfds for MSI */
-			} else if (irq_set_ptr->index == VFIO_PCI_ERR_IRQ_INDEX) {
-				pr_info("nvidia-vgpu-vfio: SET_IRQS ERR trigger fds[%d]\n", irq_set_ptr->count);
-				/* TODO: Store eventfds for ERR */
+			/* Wire each eventfd to its interrupt vector trigger.
+			 * fd >= 0: take a reference and store; fd == -1: clear.
+			 * The GSP emulation engine fires vector 0 via
+			 * gsp_emu_inject_completion_interrupt(). */
+			for (i = 0; i < irq_set_ptr->count; i++) {
+				idx = irq_set_ptr->start + i;
+
+				if (fds[i] >= 0) {
+					struct eventfd_ctx *trigger;
+
+					trigger = eventfd_ctx_fdget(fds[i]);
+					if (IS_ERR(trigger)) {
+						pr_err("nvidia-vgpu-vfio: SET_IRQS bad eventfd %d for vector %d\n",
+						       fds[i], idx);
+						continue;
+					}
+					if (vgpu->irqs[idx].trigger)
+						eventfd_ctx_put(vgpu->irqs[idx].trigger);
+					vgpu->irqs[idx].trigger = trigger;
+					vgpu->irqs[idx].type = irq_set_ptr->index;
+					wired++;
+				} else if (fds[i] == -1) {
+					if (vgpu->irqs[idx].trigger) {
+						eventfd_ctx_put(vgpu->irqs[idx].trigger);
+						vgpu->irqs[idx].trigger = NULL;
+					}
+				}
 			}
 
+			pr_info("nvidia-vgpu-vfio: SET_IRQS wired %d/%d eventfds (index=%d start=%d)\n",
+				wired, irq_set_ptr->count, irq_set_ptr->index, irq_set_ptr->start);
+
 			kfree(fds);
 			kfree(irq_set_ptr);
 			return 0;
@@ -1685,6 +1726,7 @@ static ssize_t nv_vgpu_config_read(struct nv_vgpu_device *vgpu, char __user *buf
 static ssize_t nv_vgpu_config_write(struct nv_vgpu_device *vgpu, const char __user *buf, size_t count, loff_t *ppos)
 {
 	loff_t pos = *ppos;
+	size_t written = 0;
 	u8 val;
 
 	if (pos >= 256)
@@ -1737,11 +1779,12 @@ static ssize_t nv_vgpu_config_write(struct nv_vgpu_device *vgpu, const char __us
 			break;
 		}
 		pos++;
+		written++;
 	}
 
 	vgpu->config_space_dirty = true;
 	*ppos = pos;
-	return pos - *ppos + count;
+	return written;
 }
 
 /* ============================================================