diff options
Diffstat (limited to 'docs/06-portability/hardware-software-matrix.md')
| -rw-r--r-- | docs/06-portability/hardware-software-matrix.md | 116 |
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 | |