docs: merge the legacy flat documents, add the CUDA deep-dive and link checks

* Merge and remove the pre-reboot flat documents, preserving their still-useful
  material in the structured tree: debugging workflows and the EPT-livelock
  case study (05-operations/02), performance microbenchmarks and A/B
  methodology (05-operations/01), the version-upgrade runbook
  (05-operations/02 section 4, with corrected host/guest framing), kernel-code
  pitfalls (07-developers) and the OpenRM build/load order
  (03-architecture/06 section 7). The remaining legacy files were verified
  redundant and removed.
* docs/README now records where each migrated topic lives.
* Portability: the config YAML files are called out as design targets that no
  code reads yet, with what adding support actually requires today.
* Getting started: the OpenRM step is marked optional (native vGPU-management
  workflows only; the emulated path uses the distro driver).
* tools docs: rmtool/rmtop marked as planned, pointing at the implemented
  tools/rmq subset.
* wiki: new CUDA-Userspace-Driver deep-dive page (public-safe, links the
  canonical userspace/cuda analysis) and index update.
* scripts/check-docs-links.py plus a CI step so relative links cannot rot.
* STATE.md references to removed documents repointed.

1 files changed, 0 insertions, 302 deletions

diff --git a/docs/refactored-architecture.md b/docs/refactored-architecture.md
deleted file mode 100644
index f45df2f..0000000
--- a/docs/refactored-architecture.md
+++ /dev/null
@@ -1,302 +0,0 @@
-# Open-IOV vGPU-IO Architecture
-
-> **Status: superseded (historical).** Part of the pre-2026-09-23 docs; kept
-> as a record. Current entry point: [docs/README.md](README.md). Architecture
-> replacement:
-> [03-architecture/01](03-architecture/01-system-overview.md) and
-> [03-architecture/06](03-architecture/06-host-module-and-hybrid-model.md).
-
-> **Status**: Living document. Updated 2026-09-22 post host-stability fix.
-> **Supersedes**: Previous refactored-architecture.md (v1.0).
-
----
-
-## 1. Problem Statement
-
-**Goal**: Enable unmodified NVIDIA GPU drivers (OpenRM 570.144+) to run in guest VMs with **full GPU functionality** (CUDA, graphics, video, AI/ML) on consumer and data-center GPUs without proprietary GRID licenses.
-
-**Correctness requirement**: Guest must see a fully functional NVIDIA GPU. `nvidia-smi`, CUDA, OpenGL/Vulkan, and compute must all work.
-
-**Performance requirement**: GPU compute must execute on the physical GPU hardware, not in software. Target: < 5% overhead vs native for CUDA kernel launches.
-
-**Constraints**:
-- Guest runs **stock** `nvidia.ko` + standard NVIDIA userspace (no Open-IOV code in guest)
-- Host runs **apt** `nvidia-driver-570` for physical GPU management (570.211.01)
-- Host runs **open-iov-vfio.ko** for vGPU emulation (mediated device, mdev)
-- No SR-IOV required (works on consumer GPUs like RTX 2080 Super)
-
----
-
-## 2. Core Architectural Principle: Emulate the Interface, Pass Through the Work
-
-A vGPU is a **mediated passthrough** device. Some functions must be emulated (the guest expects virtual hardware), others must be passed through to the physical GPU (for performance).
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│  EMULATE (software — guest expects virtual hardware)                │
-│  • PCI config space (guest sees virtual TU104 [10de:1ed3])          │
-│  • BAR0 register interface (shadow, not physical GPU BAR0)          │
-│  • GSP boot sequence (FWSEC/Booter/RISCV auto-complete)             │
-│  • GSP-RM protocol layer (command queue, reply format)              │
-│  • Interrupt routing (eventfd → guest MSI-X)                        │
-│  • Display output (headless / virtual display)                      │
-│  • BAR3 instance memory window (shadow, not physical GPU)          │
-└──────────────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────────────┐
-│  PASS-THROUGH (hardware — for performance)                          │
-│  • GPU compute (CUDA kernels) → execute on physical GPU             │
-│  • GPU memory (guest VRAM) → backed by real GPU VRAM or DMA-mapped │
-│  • DMA operations → use real GPU DMA engines                        │
-│  • Channel/pushbuffer work → physical GPU channels                  │
-│  • Graphics rendering → physical GPU render pipeline                │
-│  • Video encode/decode → physical GPU NVENC/NVDEC engines           │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-**Why not full emulation?** Software emulation of CUDA kernels would be 100-1000x slower than native. The physical GPU must do the actual compute work.
-
-**Why not full passthrough?** The guest driver expects to manage the GSP, boot firmware, and own the GPU. We can't give it direct physical GPU access (the host driver already owns it). The GSP emulation layer translates guest commands into host GPU operations.
-
----
-
-## 3. Host Module Architecture (Corrected 2026-09-22)
-
-```
-╔══════════════════════════════════════════════════════════════════════╗
-║ HOST KERNEL SPACE                                                    ║
-║                                                                      ║
-║  ┌────────────────────────────────────────────────────────────────┐  ║
-║  │ nvidia.ko (apt 570.211.01)                                    │  ║
-║  │  • Manages physical RTX 2080 Super (GSP firmware booted)      │  ║
-║  │  • Provides /dev/nvidia0 for nvidia-smi on host               │  ║
-║  │  • Owns physical GPU interrupts, BARs, VRAM                   │  ║
-║  │  • NOT modified, NOT rebuilt — stock Ubuntu package            │  ║
-║  └────────────────────────────────────────────────────────────────┘  ║
-║                                                                      ║
-║  ┌────────────────────────────────────────────────────────────────┐  ║
-║  │ open-iov-vfio.ko (Open-IOV vGPU VFIO driver)                  │  ║
-║  │  • Registers mdev parent on the physical GPU's PCI device     │  ║
-║  │  • Creates mdev types (nvidia-vgpu-turing, etc.)              │  ║
-║  │  • Per-mdev: emulated PCI config, BAR0 shadow, BAR1 vidmem,   │  ║
-║  │    BAR3 shadow, MSI-X emulation, GSP emulation thread        │  ║
-║  │  • Exports VFIO device ops (read/write/ioctl/mmap)            │  ║
-║  │  • Self-contained: depends only on vfio, mdev                  │  ║
-║  │  • NO dependency on nvidia submodule (removed 2026-09-22)     │  ║
-║  └────────────────────────────────────────────────────────────────┘  ║
-║                                                                      ║
-║  ┌────────────────────────────────────────────────────────────────┐  ║
-║  │ vfio / mdev (kernel prerequisites)                             │  ║
-║  │  • vfio, vfio_iommu_type1, vfio_pci, mdev                      │  ║
-║  │  • IOMMU domain management, device isolation                   │  ║
-║  └────────────────────────────────────────────────────────────────┘  ║
-║                                                                      ║
-║ PHYSICAL GPU: RTX 2080 Super (TU104, 10de:1ed3)                    ║
-║  • Managed by apt nvidia driver (host nvidia-smi works)             ║
-║  • open-iov-vfio registers mdev parent but does NOT drive the GPU   ║
-║  • Guest vGPU is a software construct — physical GPU unaffected     ║
-╚══════════════════════════════════════════════════════════════════════╝
-                              │ VFIO mdev
-                              │ /sys/bus/mdev/devices/<UUID>/
-                              ▼
-╔══════════════════════════════════════════════════════════════════════╗
-║ GUEST VM (QEMU/KVM)                                                  ║
-║  ┌────────────────────────────────────────────────────────────────┐  ║
-║  │ nvidia.ko (stock 570.144)                                     │  ║
-║  │  • PCI probe: sees TU104 [10de:1ed3] via emulated config      │  ║
-║  │  • BAR0: shadow (vzalloc'd, mapped via VFIO)                  │  ║
-║  │  • BAR1: emulated vidmem (vzalloc'd host RAM)                 │  ║
-║  │  • BAR3: shadow (vzalloc'd)                                    │  ║
-║  │  • MSI-X: eventfd → QEMU → guest ISR                          │  ║
-║  │  • GSP client: msgq RPCs via emulated GSP-RM channel          │  ║
-║  │  • NO Open-IOV code in guest                                   │  ║
-║  └────────────────────────────────────────────────────────────────┘  ║
-╚══════════════════════════════════════════════════════════════════════╝
-```
-
-### Why no nvidia submodule on host?
-
-The **nvidia-open-gpu-kernel-modules submodule (610.57.04-based)** was originally intended for NVIDIA's *native* vGPU management (RM callbacks like `vgpu_create_callback`). For our QEMU emulated-VFIO path, it's **unnecessary and harmful**:
-
-1. **Unnecessary**: open-iov-vfio.ko handles all VFIO emulation independently
-2. **Harmful**: Loading the 610-based submodule alongside apt 570.211.01 causes driver conflicts that crash the host GSP (WPR2 stuck, `unexpected WPR2 already up`)
-
-**Root cause fixed 2026-09-22** (`85d0668`): stack_manager skips submodule when apt nvidia is present.
-
----
-
-## 4. Emulated Component Details
-
-### 4.1 BAR0 Shadow (16 MB vzalloc)
-
-The guest's BAR0 is a software shadow, NOT the physical GPU's BAR0.
-
-| BAR0 offset      | Region                              | Who writes | Who reads |
-|-------------------|-------------------------------------|------------|-----------|
-| `0x000-0xFFF`     | Emulated registers (PMC boot, etc.) | shadow     | shadow    |
-| `0x1000`          | RPC request mailbox                 | guest      | emu thread|
-| `0x1080`          | RPC response mailbox                | emu thread | guest     |
-| `0x2000`          | MSI-X table (32 entries)            | guest      | guest     |
-| `0x3000`          | MSI-X PBA (pending bits)            | emu thread | guest     |
-| `0x110040`        | GSP MAILBOX0 (boot args)            | guest      | emu thread|
-| `0x110C00`        | GSP doorbell                        | guest      | emu thread|
-| `0x300000`        | VBIOS (1MB PROM window)             | host init  | guest     |
-| rest              | Emulated register space             | shadow     | shadow    |
-
-**Critical**: The GSP emulation thread polls the **shadow** exclusively. Touching the physical GPU's BAR0 (even via `ioremap`) caused the original GSP crash (fixed `f60ae7f`).
-
-### 4.2 BAR1 Emulated Vidmem (256 MB vzalloc)
-
-Guest VRAM aperture backed by host RAM. This is a **placeholder** — for real compute, this must be backed by physical GPU memory (see Phase 3 below).
-
-### 4.3 BAR3 Shadow (32 MB vzalloc)
-
-Instance memory window. **Must be shadowed** — mapping to the physical GPU's BAR3 would let guest writes corrupt host GPU instance memory (fixed `85d0668`).
-
-### 4.4 GSP Boot Emulation
-
-The guest driver boots "GSP" through falcon stages:
-
-1. **FWSEC FRTS** (GSP falcon CPUCTL) → auto-complete: HALTED + VBIOS_SCRATCH[0x0E]=0 + WPR2 ADDR
-2. **Booter Load** (SEC2 falcon CPUCTL) → auto-complete: SEC2_MAILBOX0=0 + HALTED + RISCV_STATUS=1
-3. **GSP-RM msgq init** (libos args via MAILBOX0/1) → our emulation parses the queue chain and processes RPCs
-
-### 4.5 GSP-RM Emulation
-
-The guest's physical-path driver uses the **real GSP-RM msgq protocol** (not the old PV doorbell/BAR0-shared-mem). Our emulation:
-- Parses `LibosMemoryRegionInitArgument` chain from GSP MAILBOX0/1
-- Finds the shared queue buffer in guest sysmem (129 non-contiguous 4K pages)
-- Processes commands from the command queue
-- Writes replies to the status queue
-- Injects MSI-X interrupts
-
-Key RPC types handled: GSP_INIT_DONE, SET_SYSTEM_INFO, SET_REGISTRY, SET_GUEST_SYSTEM_INFO, GET_GSP_STATIC_INFO, GSP_RM_CONTROL (multiple sub-commands).
-
----
-
-## 5. Phased Implementation Roadmap
-
-### Phase 1: Correctness — GSP-RM Emulation Complete (IN PROGRESS)
-
-**Goal**: `nvidia-smi` works in the guest. Guest driver fully initializes.
-
-**What's needed**: Complete GSP-RM reply content for the RM init sequence:
-- `INTERNAL_GET_DEVICE_INFO_TABLE` (0x20800a40) — 11 device entries
-- `FIFO_GET_DEVICE_INFO_TABLE` (0x20801112) — 12 engine entries
-- `INTERNAL_INTR_GET_KERNEL_TABLE` (0x20800a5c) — 8 entries + subtreeMap
-- `GspStaticConfigInfo` — full TU104 config
-- All remaining `GSP_RM_CONTROL` sub-commands
-
-**Oracle**: The host apt nvidia driver (570.211.01) has a **real GSP** managing the physical GPU. Use `tools/rmq/rmq` or `nvidia-smi` on host to dump ground-truth struct layouts. Compare against `kernel/gsp_rm_tu104.h`.
-
-**Current blocker**: `RmInitNvDevice` fails with `Cannot initialize the device (0x24:0x72:1099)`. The fn-10 FREE timeout during cleanup is characterized but not fully resolved.
-
-### Phase 2: Memory Model — Guest VRAM Backed by Real GPU Memory
-
-**Goal**: Guest CUDA memory allocations land in physical GPU VRAM (or DMA-coherent host memory accessible by the GPU).
-
-**What's needed**:
-- Replace emulated vidmem (BAR1 host RAM) with DMA-mapped region the physical GPU can access
-- Implement `SET_PAGE_DIRECTORY`, `UPDATE_PDE_2`, `ALLOC` handlers that map guest allocations to real GPU address space
-- Ensure cache coherency between guest CPU and GPU DMA
-
-**Key challenge**: The guest's GPU VA space must map to physical GPU VRAM addresses. The host driver's GSP manages the physical GPU's memory. We'd need to either:
-- (a) Cooperate with host GSP (share VRAM regions) — complex
-- (b) Use a dedicated VRAM partition for the guest — requires host driver cooperation
-- (c) Use system memory with DMA mapping (slower but simpler) — guest sees "unified memory"
-
-### Phase 3: Compute Forwarding — Guest Work Executes on Physical GPU
-
-**Goal**: CUDA kernels launched in the guest execute on the physical GPU.
-
-**What's needed**:
-- Guest channel/pushbuffer writes are intercepted and forwarded to host GPU channels
-- GPU context switching between host and guest contexts
-- Completion interrupts relayed from host GPU to guest
-
-**Approach options**:
-1. **GSP-RM translation**: Translate guest GSP-RM compute commands to host GSP-RM commands. The host GSP firmware already knows how to schedule work on the GPU. We'd be a "GSP proxy".
-2. **Channel forwarding**: Intercept guest channel doorbell writes, translate guest pushbuffer contents, submit to host GPU channels. Requires deep understanding of GPU channel format.
-3. **UVM integration**: Use the host's Unified Virtual Memory (UVM) to share CUDA memory between host and guest. Launch kernels via host CUDA APIs on behalf of guest.
-
-**Most promising**: Option 1 (GSP-RM translation). The guest driver sends GSP-RM commands for compute (ALLOC, MAP, SCHEDULE). Our emulation translates these to equivalent host GSP-RM commands via the host driver. The host GSP firmware executes them on the physical GPU. Results are relayed back.
-
-### Phase 4: Performance Optimization
-
-**Goal**: < 5% overhead vs native for CUDA workloads.
-
-**What's needed**:
-- Optimize GSP-RM translation latency (batch commands, avoid unnecessary copies)
-- Direct DMA mapping for large memory transfers
-- Interrupt coalescing for high-frequency completions
-- Profile and eliminate hot-path bottlenecks (doorbell polling, shared memory access)
-
-### Phase 5: Graphics & Video
-
-**Goal**: OpenGL/Vulkan rendering, NVENC/NVDEC video.
-
-**What's needed**:
-- Display surface management (virtual display or forwarded framebuffer)
-- Graphics pipeline forwarding (similar to compute forwarding)
-- Video engine access (NVENC/NVDEC on physical GPU)
-
----
-
-## 6. Testing Strategy
-
-### Correctness Testing (Phase 1)
-- [x] Host nvidia-smi works with open-iov-vfio loaded
-- [x] mdev create/remove lifecycle clean (no hang, no host GPU corruption)
-- [x] QEMU guest boots with vGPU attached
-- [x] Guest PCI probe detects vGPU (TU104 [10de:1ed3])
-- [x] Guest nvidia driver loads and creates /dev/nvidia0
-- [ ] Guest RmInitAdapter completes (RmInitNvDevice succeeds)
-- [ ] Guest nvidia-smi shows GPU
-- [ ] Guest CUDA context creation
-
-### Performance Testing (Phases 2-4)
-- [ ] GSP-RM round-trip latency < 10μs
-- [ ] CUDA kernel launch overhead < 5% vs native
-- [ ] Memory bandwidth within 10% of native
-- [ ] Graphics frame time within 5% of native
-
----
-
-## 7. Key Files
-
-| File | Role |
-|------|------|
-| `kernel/gsp_emulation.c/h` | GSP emulation thread, falcon boot auto-complete, MSI-X injection |
-| `kernel/gsp_rm_emulation.c/h` | GSP-RM msgq protocol emulation (guest sysmem queues) |
-| `kernel/gsp_rm_tu104.h` | TU104 hardware tables (engines, interrupts, falcons, device info) |
-| `kernel/gsp_rpc_client.c/h` | RPC API + emulation implementations |
-| `kernel/bar_emulation.c/h` | BAR0 shadow allocation, MSI-X shadow state |
-| `kernel/bar_init.c` | BAR init (shadow vidmem, BAR3 shadow, physical ioremap for reference) |
-| `kernel/main.c` | VFIO ops, mdev create/remove, PCI config space, VFIO mmap |
-| `kernel/memory.c` | DMA mapping, VRAM management |
-| `kernel/irq.c` | MSI-X/MSI setup and injection |
-| `tools/rmq/rmq.c` | Host RM API client (oracle for GSP-RM ground truth) |
-
----
-
-## 8. Host Stability Guarantees (2026-09-22)
-
-After the host-stability fix (`85d0668`), the following are guaranteed:
-
-1. **open-iov-vfio.ko loads/unloads cleanly** with apt nvidia driver present
-2. **Host nvidia-smi works throughout** the full lifecycle (load, mdev, QEMU, unload)
-3. **No host GPU corruption** — no WPR2 stuck, no GSP crash, no module hang
-4. **Guest driver probe is safe** — even when RmInitNvDevice fails, host is unaffected
-5. **mdev create/remove is clean** — gsp_emu thread starts/stops properly
-
-**Root causes that were fixed**:
-- Submodule nvidia.ko conflict with apt nvidia → skip submodule
-- BAR3 physical mapping to guest → vzalloc'd shadow
-- GSP-RM teardown garbage declaring GSP death → quiet stop polling
-
----
-
-*Document Version: 2.0 (Emulate vs Pass-Through Architecture)*
-*Updated: 2026-09-22 (post host-stability fix)*
-*Repository: ~/Git/integdev_gpu_drv/open-iov*
-*Git Commit: 85d0668 (host stability fix)*