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

diff --git a/wiki/Glossary.md b/wiki/Glossary.md
new file mode 100644
index 0000000..2c61a83
--- /dev/null
+++ b/wiki/Glossary.md
@@ -0,0 +1,163 @@
+# Glossary
+
+## Terms & Abbreviations
+
+### General
+| Term | Definition |
+|------|------------|
+| **GSP** | GPU System Processor - NVIDIA's on-GPU RISC-V microcontroller |
+| **vGPU** | Virtual GPU - Partitioned GPU for multi-tenant workloads |
+| **VF** | Virtual Function - Single vGPU instance with dedicated resources |
+| **PF** | Physical Function - Host GPU managing VFs (SR-IOV) |
+| **IOV** | I/O Virtualization - SR-IOV implementation |
+| **RPC** | Remote Procedure Call - GSP-host communication protocol |
+| **BAR** | Base Address Register - PCIe memory-mapped I/O window |
+| **WPR** | Write/Read Protect Region - Memory isolation mechanism |
+| **SR-IOV** | Single Root I/O Virtualization - PCIe virtualization standard |
+
+### Firmware Architecture
+| Term | Definition |
+|------|------------|
+| **RV64IMAC** | RISC-V 64-bit ISA with Integer, Multiply, Atomic, Compressed extensions |
+| **Dispatcher** | Central RPC routing function (primary/secondary) |
+| **Jump Table** | Array of function pointers for sub-command dispatch |
+| **Sub-Command** | Specific operation within an RPC type |
+| **Descriptor** | Return structure with ID and echoed parameters |
+| **Entry Point** | Firmware boot address (0x04009000) |
+| **Frame Guard** | Stack canary at 0x041DC350 |
+
+### Memory Management
+| Term | Definition |
+|------|------------|
+| **VRAM** | Video RAM - GPU local memory |
+| **Sysmem** | System Memory - Host DRAM |
+| **Page Table** | GPU virtual-to-physical mapping tables |
+| **Pinning** | Locking pages for DMA access |
+| **Bounce Buffer** | Intermediate buffer for data transfer |
+| **Aperture** | Mappable BAR window size |
+| **Backing Store** | Memory backing emulated BAR regions |
+
+### RPC Types
+| RPC | Name | Purpose |
+|-----|------|---------|
+| 0x01 | **ALLOC** | Allocate GPU memory |
+| 0x02 | **FREE** | Free GPU memory |
+| 0x03 | **MAP** | Map memory to VF address space |
+| 0x04 | **UNMAP** | Unmap memory from VF |
+| 0x05 | **PIN** | Pin pages for DMA |
+| 0x06 | **UNPIN** | Unpin pages |
+| 0x07 | **SCHEDULE** | VF scheduling control |
+| 0x08 | **YIELD** | Voluntary yield |
+| 0x09 | **NOTIFY** | Event notification |
+| 0x0A | **BAR_TRAP** | BAR access emulation |
+| 0x0B | **MIGRATE** | Live VF migration |
+| 0x0C | **DEBUG** | Debug interface |
+
+### Migration
+| Term | Definition |
+|------|------------|
+| **Pre-copy** | Iterative page transfer while VF runs |
+| **Post-copy** | Start VF on destination, fetch pages on demand |
+| **Quiesce** | Pause VF for consistent state snapshot |
+| **Dirty Page** | Page modified since last transfer |
+| **Cutover** | Switch execution from source to destination |
+| **Token** | Opaque migration context handle |
+
+### BAR Emulation
+| Term | Definition |
+|------|------------|
+| **BAR1** | Primary 32-bit BAR for register access |
+| **Bar1Rest** | BAR1 state restoration |
+| **ForceBarAccess** | Hypervisor bypass of VF permissions |
+| **Aperture** | Configurable BAR window size/offset |
+
+### WPR (Write/Read Protect Region)
+| Term | Definition |
+|------|------------|
+| **Write Protect** | Trap on write access to region |
+| **Read Protect** | Trap on read access to region |
+| **NV_WPR** | NVIDIA-specific WPR extensions |
+| **Completion** | Successful trap handling |
+| **Timeout** | Trap handling exceeded time limit |
+
+### Hardware Registers
+| Register | Purpose |
+|----------|---------|
+| **Doorbell** | Host→GSP notification (PCIe BAR0 + 0x1000) |
+| **Message Ring** | Shared memory for RPC messages |
+| **Cache Manager** | 0x429B428 - Flush/invalidate |
+| **Allocator Arena** | 0x429B450 - Memory allocation |
+| **Global Error Flag** | 0x04296048 - Global error state |
+| **Stack Canary** | 0x041DC350 - Frame integrity |
+
+### Tools & Scripts
+| Tool | Purpose |
+|------|---------|
+| **analyzeHeadless** | Ghidra headless analyzer |
+| **DecompileFunctions.java** | Ghidra script for batch decompilation |
+| **trace_all_subsystems.py** | Binary analysis script |
+| **RPC_HANDLER_MAP.md** | Complete RPC address map |
+| **FINAL_REPORT.md** | Full analysis report |
+
+### Debugging
+| Term | Definition |
+|------|------------|
+| **ebreak** | RISC-V breakpoint instruction (fatal in FW) |
+| **String Ref** | Cross-reference to string literal |
+| **XRef** | Cross-reference (code/data) |
+| **Pcode** | Ghidra's intermediate representation |
+| **VBIOS** | Video BIOS - firmware for GPU initialization |
+
+### Calling Convention (RISC-V)
+| Register | ABI Name | Purpose |
+|----------|----------|---------|
+| x0 | zero | Hardwired zero |
+| x1 | ra | Return address |
+| x2 | sp | Stack pointer |
+| x3 | gp | Global pointer |
+| x4 | tp | Thread pointer |
+| x5-7 | t0-t2 | Temporaries |
+| x8 | s0/fp | Frame pointer |
+| x9 | s1 | Callee-saved (RA save) |
+| x10-11 | a0-a1 | Arguments/returns |
+| x12 | s4 | Callee-saved (RA save) |
+| x13-17 | a2-a6 | Arguments |
+| x18-27 | s2-s11 | Callee-saved |
+| x28-31 | t3-t6 | Temporaries |
+
+### Firmware Sections (ELF)
+| Section | Purpose |
+|---------|---------|
+| `.text` | Executable code |
+| `.rodata` | Read-only data |
+| `.data` | Initialized data |
+| `.bss` | Zero-initialized data |
+| `.section_task_rm_*` | Task-specific sections |
+
+### Migration Phases
+| Phase | Description |
+|-------|-------------|
+| **QUERY** | Check migratability |
+| **PREPARE** | Quiesce, snapshot |
+| **TRANSFER** | Iterative page copy |
+| **COMMIT** | Final sync, cutover |
+| **CLEANUP** | Release resources |
+
+## File Naming Conventions
+
+### Decompiled Output
+```
+FUN_ram_<ADDRESS>_ram_<ADDRESS>.c
+```
+- `FUN_ram_057A1AC0_ram_057A1AC0.c` = Function at 0x057A1AC0
+
+### Ghidra Projects
+```
+gsp-<purpose>/
+```
+- `gsp-subcmds`, `gsp-rpc-handlers`, `gsp-bar-fns`, etc.
+
+## References
+- RISC-V ISA: https://riscv.org/technical/specifications/
+- SR-IOV Spec: https://pcisig.com/specifications/iov/
+- Ghidra: https://ghidra-sre.org/
\ No newline at end of file