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

diff --git a/docs/06-portability/hardware-software-matrix.md b/docs/06-portability/hardware-software-matrix.md
new file mode 100644
index 0000000..442e099
--- /dev/null
+++ b/docs/06-portability/hardware-software-matrix.md
@@ -0,0 +1,116 @@
+# Hardware and Software Matrix
+
+> What Open-IOV runs on, what it targets, and exactly how support for a new
+> hardware or software combination is added. Support here means *tested and
+> documented*, not "should probably work".
+
+## 1. Support ladder
+
+| Level | Meaning |
+|---|---|
+| **Reference** | continuously tested; bugs block releases |
+| **Supported** | tested per release; documented workarounds if any |
+| **Experimental** | known to boot/test partially; may need configuration |
+| **Target** | architecture designed for it; bring-up in progress |
+| **Out of scope** | not planned |
+
+## 2. Host platforms
+
+| Platform | Status | Notes |
+|---|---|---|
+| x86_64 + NVIDIA Turing (TU104) | **Reference** | the current development hardware (RTX 2080-class) |
+| x86_64 + Ampere / Ada consumer | **Target** | profile work; expected to be configuration + measurement |
+| x86_64 + Hopper / datacenter | **Target** | requires MIG-aware policy for multi-tenancy |
+| aarch64 + Grace-Hopper (GH200) | **Target** | host-architecture work in the memory model |
+| aarch64 + Grace-Blackwell | **Target** | as above, newer firmware/driver family |
+| GB10 (DGX Spark, Surface-class RTX laptops) | **Target** | same architecture; firmware/ROM quirks to be measured |
+| Other NVIDIA generations | **Experimental** | bring-up path documented in §5 |
+
+The defining property we are building toward: **each new host platform should
+require configuration + verification, not new code.**
+
+## 3. Guest operating systems
+
+| Guest | Status |
+|---|---|
+| Linux x86_64 (stock `nvidia.ko`, CUDA) | **Reference** (initialization; execution in progress) |
+| Linux aarch64 | **Target** |
+| Windows x86_64 (WDDM driver, CUDA, 3D) | **Target** |
+| Other Unix (FreeBSD, ...) | Out of scope until demand |
+
+**Guest rule:** the guest never contains Open-IOV code. No guest agent, no
+driver patch, no kernel parameters beyond what the stock driver needs.
+
+## 4. Hypervisors and transports
+
+| Hypervisor | Status | Transport |
+|---|---|---|
+| KVM + QEMU (VFIO mdev) | **Reference** | VFIO mdev + eventfd IRQ + DMA interface |
+| libvirt (mdev attach) | **Supported** | same, via libvirt XML |
+| Zen / KVM on other device models | **Experimental** | as above |
+| Xen (incl. Argo/OpenXT) | **Target** | Xen device model + event channels |
+| Qubes OS / Qubes OS Air | **Target** | compartmentalized VMs; GPU per compartment |
+| Cloud hypervisor / crosvm | **Experimental** | VFIO-based; needs testing |
+
+The transport boundary (how the device registers with the hypervisor, how
+guest memory is accessed, how interrupts are injected) is deliberately narrow
+so new transports are a small, isolated implementation.
+
+## 5. Adding a new combination
+
+### 5.1 New GPU / hardware profile
+
+1. Create a hardware profile: PCI IDs, BAR layout and sizes, memory geometry
+   (FB size, BAR windows), engine inventory, interrupt topology, and the
+   register values the guest driver validates during probe.
+2. Run the evaluation ladder (see
+   [`../05-operations/01-performance-correctness-security.md`](../05-operations/01-performance-correctness-security.md)).
+3. Record the differences; prefer configuration over code.
+4. Publish the profile, the evidence, and any workarounds.
+
+### 5.2 New firmware version
+
+See [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md) §4.1.
+Firmware images are versioned under `firmware/<SERIES>-GSP/<VERSION>/` with
+signatures and analysis artifacts.
+
+### 5.3 New driver version
+
+See the same document §4.2. The expected work per version is: run the trace,
+diff the inventory, decode the differences against that version's reference
+tree, add configuration/handlers, re-run the ladder.
+
+## 6. Version matrix (maintained in the repository)
+
+The authoritative matrix lives in `config/`:
+
+```
+config/
+  hardware/<arch>.yaml      # PCI IDs, BARs, memory geometry, engine lists
+  versions/<driver>.yaml    # RPC/control inventories, capability tables
+  profiles/<name>.yaml      # (hardware, driver, firmware) combinations we test
+```
+
+A profile is the unit of support: "hardware X + driver family Y + firmware Z =
+profile P, tested at rung R on date D." Releases publish the profile table.
+
+## 7. Architecture properties that enable portability
+
+| Property | Why it matters |
+|---|---|
+| No architecture-specific assumptions in the memory model | x86_64 and aarch64 hosts share the same code |
+| RPC/handler layer keyed by version | new driver families are additive |
+| Hardware constants in profiles | new GPUs are data |
+| Transport behind a narrow interface | KVM today, Xen/Argo/Qubes tomorrow |
+| Guest-independent design | Windows and Linux guests share the same host code |
+| Firmware analysis toolchain is version-generic | new firmware is analyzed with the same scripts |
+
+## 8. Known portability risks
+
+| Risk | Mitigation |
+|---|---|
+| Page-size/cache-attribute differences on aarch64 | keep memory model abstract; test on Grace early |
+| Windows driver ROM/VBIOS expectations | explicit ROM/VBIOS provisioning in the device profile; measured bring-up |
+| Xen interrupt/memory interfaces differ | narrow transport interface + Xen backend plan |
+| Vendor ROMs and laptop firmware variants (GB10/Surface) | profile system supports per-device overrides |
+| Driver-family drift (580/610+) | version-keyed handlers; matrix-driven testing |