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

diff --git a/docs/09-reference/glossary-and-faq.md b/docs/09-reference/glossary-and-faq.md
new file mode 100644
index 0000000..255d1a6
--- /dev/null
+++ b/docs/09-reference/glossary-and-faq.md
@@ -0,0 +1,103 @@
+# Glossary and FAQ
+
+## Glossary
+
+| Term | Meaning |
+|---|---|
+| **AMAPlib** | NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules. Studied for page-table and memory-layout semantics. |
+| **BAR0 / BAR1 / BAR3** | PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window. |
+| **CE** | Copy Engine: DMA engine; also used for UVM's internal work. |
+| **CUDASW** | The family of NVIDIA user-space software that sits between applications and the driver: `libcuda`, `libcudart`, JIT compiler, fatbinary loader, and friends. |
+| **Doorbell** | A register/memory location a driver writes to signal "new work is available" for a channel or queue. |
+| **Engine type** | Numeric identifier for an execution engine (`GR = 0x1`, `COPY0 = 0x9`, ...). |
+| **FWSEC** | Firmware security processor stage of the GSP boot sequence. |
+| **GNND / GB10** | NVIDIA "Grace-Blackwell" systems-on-chip used in DGX Spark and Surface-class laptops; explicit portability targets. |
+| **GPFIFO** | GPU FIFO: a ring of entries, each pointing to a push buffer for a channel. |
+| **GR** | The graphics/compute engine that executes shaders (graphics pipelines and CUDA kernels). |
+| **GSP** | GPU System Processor: the embedded RISC-V (RV64IMAC) that runs firmware containing the Resource Manager. |
+| **GSP-RM** | The Resource Manager running on the GSP ("self-hosted RM"). |
+| **GMMU** | GPU Memory Management Unit: page tables, TLB, fault handling. |
+| **HAL** | Hardware Abstraction Layer: per-generation functions that program registers and formats. |
+| **mdev** | Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO). |
+| **MSGQ** | The GSP message queue transport: shared-memory element rings with a page table, plus doorbells. |
+| **PBDMA** | Push-buffer DMA engine in the host scheduler that fetches and executes push buffers. |
+| **PDB** | Page Directory Base: root of a GPU page table. |
+| **PDE / PTE** | Page-directory entry / page-table entry. |
+| **Push buffer** | A stream of method calls (engine commands) submitted via a GPFIFO. |
+| **RMCore** | The RM's object system: classes, handles, parents, methods. |
+| **RM / RM API** | NVIDIA's Resource Manager and the API used to allocate objects and issue controls. |
+| **resserv / resource server** | The RM component that owns allocation authority, privileges and lifetimes. |
+| **Runlist** | The scheduler's list of channels eligible to run. |
+| **SEC2** | Secure copy engine used by UVM for protected operations. |
+| **Semaphore / tracker** | Memory location written by the GPU to signal progress; UVM's tracker waits on it. |
+| **SRIOV / VF** | Single-root I/O virtualization / virtual functions (hardware partitioning). |
+| **TSG** | Time-Slice Group: channels sharing a scheduling slot. |
+| **USERD** | Per-channel control block in VRAM: PUT/GET pointers and control state. |
+| **UVM** | NVIDIA's unified memory module: VA spaces, page trees, faults, channel manager. |
+| **VA / PA / GPA / IOVA** | Virtual address / physical address / guest physical address / I/O virtual address. |
+| **vidmem / sysmem / aperture** | GPU local memory / system memory / the way an address is qualified (`ADDR_FBMEM = 2`, `ADDR_SYSMEM = 1`). |
+| **VGX version** | The version the guest announces during RPC negotiation; selects message layouts. |
+| **vGPU** | Virtual GPU: this project's device. |
+| **WPR** | Write-Protected Region: VRAM area reserved for firmware. |
+
+## FAQ
+
+**Is this a replacement for vLLM on bare metal?**
+No. Continuous batching on bare-metal hosts is the right answer for centralized
+inference. Open-IOV is for compute *inside guests*: Windows/Linux CUDA, 3D,
+video, and secure edge isolation. See the orientation docs.
+
+**Does the guest driver need to be patched?**
+No, and that is a hard project rule. No guest driver patches, no host driver
+patches, no firmware patches, no hypervisor patches.
+
+**Does it work with the distribution's NVIDIA driver on the host?**
+Yes — in the standalone configuration the distribution driver owns the physical
+GPU and Open-IOV is an independent module. Building NVIDIA's OpenRM modules from
+source is only needed for the native-vGPU-management workflows.
+
+**Why is `nvidia-smi` working but CUDA not?**
+Because CUDA requires *execution*: kernels must run on real hardware. The
+current state runs the entire initialization path (including UVM's start-up)
+but stops short of executing engine work. See the known-knowns document for
+the exact status and plan.
+
+**How is this legal / license-clean?**
+Open-IOV is BSD-3-Clause (GPL-2.0 for kernel modules that link GPL-only kernel
+exports); we interoperate with unmodified NVIDIA software rather than
+relicensing it. See the legal document.
+
+**Will it support Windows guests?**
+Yes, it is a target: same architecture, measured bring-up. See the portability
+matrix.
+
+**Can I run several VMs on one GPU?**
+Yes — that is a core design goal (per-VM mdev, IOMMU isolation, explicit
+scheduling). Multi-tenant maturity depends on the scheduling/isolation work in
+the known-unknowns list.
+
+**Does it support Xen / Qubes OS Air / Argo / OpenXT?**
+Designed for them; the transport backends are on the roadmap. The emulation
+core is hypervisor-independent by construction.
+
+**What about MIG?**
+MIG is a hardware partitioning mechanism; Open-IOV's scheduling policy can use
+it where available. It is part of the multi-tenancy work.
+
+**How fast is it?**
+Initialization currently completes in the same order of magnitude as native;
+execution forwarding is not implemented yet. Performance claims follow the
+published methodology in the operations docs.
+
+**Where do I report bugs or ask for help?**
+Open an issue with the standard captures listed in the debugging document. A
+reproduction plus logs is worth more than a description.
+
+**Can my company use this commercially?**
+Yes, under BSD-3-Clause (kernel modules GPL-2.0), with no fee. We also welcome
+co-development; see the ecosystem document.
+
+**How do I contribute support for my GPU/driver/hypervisor?**
+Follow the "adding a new combination" workflows in the portability and
+maintenance docs; the deliverable is a profile plus evidence from the
+evaluation ladder.