Open-IOV: initial public release

Open-IOV virtualizes NVIDIA GPUs so that unmodified guest drivers run with
real GPU functionality - CUDA first, 3D and video to follow - on unmodified
hosts, without a proprietary vGPU license and without patching any driver,
firmware or hypervisor.

Core principle: emulate the interface, pass through the work.

  kernel/     open-iov-vfio.ko - host VFIO mdev driver: virtual GPU device
              (PCI config space, BAR shadows, MSI-X), GSP boot emulation,
              GSP-RM message-queue/RPC emulation, memory model (GPU-VA to
              guest-PA discovery) and the semaphore-completion service that
              advances guest UVM progress.
  userspace/  libiov.so management API and examples.
  tools/      guest diagnostics, firmware analysis wrappers, RM probes.
  scripts/    stack manager, VM harness, build/load/test automation.
  config/     hardware/version profiles (the portability surface).
  docs/       documentation tree - start at docs/README.md.
  wiki/       long-form firmware and protocol deep dives.

Status: initialization works end to end for a stock 570.144 Linux guest on
Turing (TU104): driver probe, nvidia-smi, the full GSP-RM control battery,
object creation and the early CUDA/UVM start-up path. GPU work forwarding -
the step that makes CUDA kernels execute on real hardware - is the active
work item; see docs/04-implementation/01-known-knowns-and-unknowns.md.

License: BSD-3-Clause for the project; GPL-2.0 for kernel modules that link
GPL-only kernel interfaces. See LICENSE and docs/09-reference/legal-and-licensing.md.

1 files changed, 179 insertions, 0 deletions

diff --git a/tools/gdb_scripts/nvidia_init.gdb b/tools/gdb_scripts/nvidia_init.gdb
new file mode 100644
index 0000000..c217419
--- /dev/null
+++ b/tools/gdb_scripts/nvidia_init.gdb
@@ -0,0 +1,179 @@
+# nvidia_init.gdb - GDB script for debugging NVIDIA driver initialization in guest
+# Usage: gdb -x nvidia_init.gdb ./vmlinux
+# Then: (gdb) target remote localhost:1234
+
+# ============================================================
+# CONFIGURATION
+# ============================================================
+# Path to guest kernel vmlinux with debug symbols
+# set pagination off
+# set confirm off
+
+# ============================================================
+# BREAKPOINTS - NVIDIA Driver Probe/Init
+# ============================================================
+
+# Core probe entry points
+break nvidia_probe
+break nvidia_init_module
+break nvidia_exit_module
+
+# GSP/RM initialization
+break nv_init_gsp
+break nv_gsp_init
+break nv_gsp_firmware_load
+break nv_gsp_bootstrap
+break nv_gsp_rpc_init
+
+# VFIO/mdev integration
+break nvidia_vgpu_vfio_get_ops
+break nvidia_vgpu_vfio_set_ops
+break nv_vgpu_mdev_register_parent
+break nv_vgpu_mdev_unregister_parent
+break nv_vgpu_create_callback
+break nv_vgpu_delete_callback
+break nv_vgpu_bar_info_callback
+break nv_vgpu_start_callback
+
+# PCI config space
+break nvidia_pci_probe
+break nvidia_pci_remove
+break pci_enable_device
+break pci_request_regions
+
+# MSI/MSI-X
+break pci_enable_msi_block
+break pci_enable_msix_range
+break nvidia_setup_msi
+break nvidia_setup_msix
+
+# BAR mapping
+break pci_iomap
+break pci_iounmap
+break nvidia_map_bars
+
+# Interrupt handling
+break request_threaded_irq
+break free_irq
+break nvidia_isr
+break nvidia_msi_isr
+break nvidia_msix_isr
+
+# DMA mapping
+break dma_map_page
+break dma_unmap_page
+break dma_map_sg
+break dma_unmap_sg
+
+# GSP RPC communication (OpenRM internal)
+break nv_gsp_rpc_send
+break nv_gsp_rpc_recv
+break nv_gsp_doorbell_ring
+break nv_gsp_doorbell_poll
+
+# ============================================================
+# WATCHPOINTS - Key Data Structures
+# ============================================================
+
+# Watch for GSP firmware load completion
+# watch *(int*)nv_gsp_fw_loaded
+
+# Watch for MSI-X table setup
+# watch *(int*)nv_msix_table_configured
+
+# ============================================================
+# COMMANDS - Helper Functions
+# ============================================================
+
+define nvidia_backtrace
+    bt
+    printf "\n=== NVIDIA Driver Stack ===\n"
+    info registers
+end
+document nvidia_backtrace
+    Show backtrace with register state for NVIDIA driver
+end
+
+define nvidia_pci_state
+    printf "=== PCI Config Space ===\n"
+    # Requires access to pci_dev structure
+    # p/x ((struct pci_dev*)$rdi)->vendor
+    # p/x ((struct pci_dev*)$rdi)->device
+    # p/x ((struct pci_dev*)$rdi)->command
+    # p/x ((struct pci_dev*)$rdi)->status
+end
+document nvidia_pci_state
+    Print PCI device state
+end
+
+define nvidia_gsp_state
+    printf "=== GSP State ===\n"
+    # p/x nv_gsp_fw_version
+    # p/x nv_gsp_fw_loaded
+    # p/x nv_gsp_rpc_initialized
+end
+document nvidia_gsp_state
+    Print GSP firmware state
+end
+
+define nvidia_vfio_state
+    printf "=== VFIO/mdev State ===\n"
+    # p/x nv_vgpu_mdev_registered
+    # p/x nv_vgpu_vfio_ops
+end
+document nvidia_vfio_state
+    Print VFIO/mdev registration state
+end
+
+# ============================================================
+# TRACEPOINTS (if kernel has tracepoints enabled)
+# ============================================================
+
+# trace nvidia:nvidia_probe_entry
+# trace nvidia:nvidia_probe_exit
+# trace nvidia:gsp_firmware_load
+# trace nvidia:gsp_rpc_send
+# trace nvidia:gsp_rpc_recv
+
+# ============================================================
+# AUTOMATION - Continue and Log
+# ============================================================
+
+# Log all breakpoint hits to file
+set logging file nvidia_init_debug.log
+set logging on
+
+# Auto-continue after logging (uncomment for automated runs)
+# set confirm off
+# commands 1
+#   nvidia_backtrace
+#   continue
+# end
+
+# ============================================================
+# CONVENIENCE ALIASES
+# ============================================================
+
+define hook-stop
+    # Print current function on every stop
+    printf "\n=== STOPPED at %s ===\n", __func__
+    # Print key state
+    # nvidia_gsp_state
+end
+
+# ============================================================
+# USAGE NOTES
+# ============================================================
+# 1. Compile guest kernel with CONFIG_DEBUG_INFO=y CONFIG_GDB_SCRIPTS=y
+# 2. Copy vmlinux from guest to host
+# 3. Launch QEMU: ./scripts/qemu_gdb_attach.sh
+# 4. In another terminal: gdb -x tools/gdb_scripts/nvidia_init.gdb ./vmlinux
+# 5. (gdb) target remote localhost:1234
+# 6. (gdb) continue
+# 
+# For specific debugging:
+# - PCI probe issues: break nvidia_probe
+# - GSP firmware load: break nv_gsp_firmware_load
+# - MSI-X setup: break pci_enable_msix_range
+# - BAR mapping: break pci_iomap
+# - RPC communication: break nv_gsp_rpc_send
\ No newline at end of file