docs: architecture rewrite - emulate vs pass-through model, phased performance roadmap

- Clear separation: EMULATE (GSP interface, BARs, config) vs PASS-THROUGH
  (compute, memory, DMA to physical GPU)
- Phased roadmap: Phase 1 (GSP-RM correctness) → Phase 2 (memory model) →
  Phase 3 (compute forwarding) → Phase 4 (performance) → Phase 5 (graphics)
- Host module architecture corrected: apt nvidia (570.211.01) for physical
  GPU, open-iov-vfio.ko for vGPU emulation, NO 610 submodule
- Host stability guarantees documented (BAR3 shadow, submodule skip)
- GSP_EMULATION_ARCHITECTURE.md: memory model corrected (BAR1/BAR3 shadows)

1 files changed, 24 insertions, 9 deletions

diff --git a/scripts/stack_manager.sh b/scripts/stack_manager.sh
index c247d08..faf345b 100755
--- a/scripts/stack_manager.sh
+++ b/scripts/stack_manager.sh
@@ -72,9 +72,11 @@ cmd_build_userspace() {
 cmd_build_all() {
     log_info "=== BUILD ALL (correct order) ==="
     cmd_build_kernel
-    cmd_build_nvidia
     cmd_build_userspace
     log_ok "=== ALL BUILDS COMPLETE ==="
+    log_info "NOTE: NVIDIA submodule (610-based) NOT built by default."
+    log_info "      Only needed for NVIDIA's native vGPU management (not QEMU)."
+    log_info "      Build separately with: stack_manager.sh build-nvidia"
 }
 
 # ============================================================
@@ -148,8 +150,10 @@ cmd_load_stack() {
     log_info "=== LOAD STACK (correct order) ==="
     cmd_load_prereqs
     cmd_load_open_iov
-    cmd_load_nvidia
     cmd_install_firmware
+    # NOTE: NVIDIA submodule NOT loaded for QEMU/vGPU work.
+    # apt nvidia (570.211.01) manages the physical GPU;
+    # open-iov-vfio handles the emulated vGPU.
     log_ok "=== DRIVER STACK LOADED ==="
     lsmod | grep -E "nvidia|open_iov|vfio|mdev"
 }
@@ -181,14 +185,25 @@ cmd_unload_stack() {
         sleep 2
     fi
 
-    # CRITICAL: nvidia.ko holds a reference to open_iov_vfio, so unload nvidia FIRST
-    for mod in nvidia_uvm nvidia_modeset nvidia_drm nvidia_peermem nvidia; do
-        if lsmod | grep -qE "^$mod\>"; then
-            log_info "Unloading $mod..."
-            sudo rmmod "$mod" || { log_err "Failed to unload $mod"; return 1; }
-            log_ok "$mod unloaded"
+    # Only unload OUR submodule nvidia.ko if it was loaded (not apt nvidia).
+    # The apt nvidia driver (e.g. 570.211.01) manages the physical GPU and
+    # must stay loaded for nvidia-smi to keep working.
+    if [[ -f "$NVIDIA_KO" ]] && lsmod | grep -q "^nvidia "; then
+        local loaded_ver want_ver
+        loaded_ver=$(cat /sys/module/nvidia/version 2>/dev/null)
+        want_ver=$(modinfo -F version "$NVIDIA_KO" 2>/dev/null)
+        if [[ -n "$loaded_ver" && "$loaded_ver" == "$want_ver" ]]; then
+            for mod in nvidia_uvm nvidia_modeset nvidia_drm nvidia_peermem nvidia; do
+                if lsmod | grep -qE "^$mod\>"; then
+                    log_info "Unloading submodule $mod..."
+                    sudo rmmod "$mod" || { log_err "Failed to unload $mod"; return 1; }
+                    log_ok "$mod unloaded"
+                fi
+            done
+        else
+            log_ok "apt nvidia ($loaded_ver) kept loaded for host GPU"
         fi
-    done
+    fi
 
     if lsmod | grep -qE "^open_iov_vfio\>"; then
         log_info "Unloading open-iov-vfio.ko..."