diff options
Diffstat (limited to 'wiki/Hardware-Software-Matrix.md')
| -rw-r--r-- | wiki/Hardware-Software-Matrix.md | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/wiki/Hardware-Software-Matrix.md b/wiki/Hardware-Software-Matrix.md new file mode 100644 index 0000000..0363636 --- /dev/null +++ b/wiki/Hardware-Software-Matrix.md @@ -0,0 +1,160 @@ +# Hardware and Software Matrix + +> **Companion summary.** This page condenses +> [`../docs/06-portability/hardware-software-matrix.md`](../docs/06-portability/hardware-software-matrix.md) +> — the canonical support matrix: the support ladder, the current status of +> every host/GPU/guest/hypervisor combination, and what adding a combination +> requires. The validation process behind every support decision is +> [`../docs/06-portability/03-device-validation-and-porting-sequence.md`](../docs/06-portability/03-device-validation-and-porting-sequence.md). +> When this page and the docs tree disagree, the docs tree wins. Front door: +> [`../docs/README.md`](../docs/README.md). + +Status: 2026-10-12, tree `master @ 2f066727`. Tags: `[reference]` continuously tested, bugs block releases; `[supported]` tested per release; `[experimental]` partial or bring-up; `[target]` designed for, bring-up in progress; `[design]` design direction, not the current build. + +## 1. Support ladder + +Support means **tested and documented**, not "should probably work". + +| 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 development hardware (RTX 2080-class); the only Reference platform today | +| 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 in the canonical document §5 | + +The design direction is that **each new host platform should require +configuration + verification, not new code** — not the current state: +selection is compile-time today and the module is built for the TU104 profile. + +## 3. Guest operating systems + +| Guest | Status | +|---|---| +| Linux x86_64 (stock `nvidia.ko`, CUDA) | **Experimental** — probe, `nvidia-smi` and the driver-API smoke pass; CE-class copies are forwarded default-off; for GR the guest launch reaches the front-end but no grid has dispatched yet (see [`Execution-Frontier.md`](Execution-Frontier.md)); no continuous guest testing yet | +| 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 — registration, guest-memory access, interrupt +injection — is deliberately narrow, so a new transport is small and isolated. + +## 5. What portability means today + +```text + host architecture GPU family driver/firmware family + ┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐ + │ x86_64 │ │ Turing (TU104) │ │ 570.144 (anchor) │ + │ aarch64 (Grace) │ │ Ampere / Ada │ │ newer families │ + │ GB10-class │ │ Hopper / datac. │ │ (gated, pending │ + └────────┬────────┘ └────────┬─────────┘ │ review) │ + │ │ └─────────┬──────────┘ + └──────────┬──────────┴───────────────────────┘ + ▼ + one combination = hardware profile + version profile + ▼ + evaluation ladder + evidence → matrix entry: + "hardware X + driver Y + firmware Z, tested at rung R on date D" +``` + +The configuration surface lives in `config/`: `config/hardware/<arch>.yaml` +(PCI IDs, BARs, memory geometry, engine lists) and +`config/versions/<driver>.yaml` (RPC/control inventories, capability tables). + +> **These files are design targets, not live configuration.** No code reads +> them today: selection is compile-time and the module is built for the TU104 +> profile. Treating the YAML surface as authoritative — or claiming +> "configuration-driven portability" — is aspirational until the profiles are +> wired into the module's load path. A profile is the *unit of support*; what +> is missing is the code that reads the profile files, not the schema. + +## 6. Adding a new combination + +**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 five-rung evaluation ladder + ([`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md)). +3. Record the differences; prefer configuration over code. +4. Publish the profile, the evidence, and any workarounds. + +Firmware-side analysis uses the risc-v-gsp-rm-debugger +([`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md)): first-touch probes +and per-pair comparisons classify each difference as profile data or logic +before any profile change lands. + +**New firmware version.** Images are versioned under +`firmware/<SERIES>-GSP/<VERSION>/` with signatures and analysis artifacts; the +work is capture, inventory diff, decode against that version's reference, then +configuration/handlers and a re-run of the ladder. + +**New driver version.** Run the trace, diff the RPC/control inventory, add +version-keyed handlers, re-run the ladder. Newer driver/firmware families are +gated pending review before any work starts. + +**Evidence expectations.** A combination is entered in the matrix only with +the profile fields recorded; the firmware/device pairing verified by hash and +version string; every first-touch difference explained as profile or logic; +per-pair comparison results with session hashes; the metric table with its +reference-capture method and stated fidelity limits; and a supervised physical +validation for the support claim. "Tested and documented" is literal: an +untested or simulator-only combination stays **Target** or **Experimental**. + +## 7. Anchor versions and engine-list portability + +The anchor is guest CUDA driver (`libcuda`) **570.144** with GSP firmware +**570.144**; the host oracle is `libcuda` **570.211.01** with CUDA toolkit +**12.0**. The versioned surface is the RM ioctl/class/control interface the +userspace driver issues — not a stable public API; see +[`CUDA-Userspace-Driver.md`](CUDA-Userspace-Driver.md). + +The engine inventory and its class-list filtering are per-architecture, +per-driver data. An earlier gap was concrete: a missing async copy engine +blocked context creation until the inventory was completed — which is why it +belongs in the hardware profile, validated against the host oracle. + +## 8. Known portability risks + +| Risk | Mitigation | +|---|---| +| Page-size/cache-attribute differences on aarch64 | keep the 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) | per-device overrides in the profile system | +| Driver-family drift (580 and newer) | version-keyed handlers; matrix-driven testing | + +## 9. Related documentation + +* [`../docs/06-portability/hardware-software-matrix.md`](../docs/06-portability/hardware-software-matrix.md) — canonical matrix: ladder, status, procedures; the validation process behind every support claim is in [`../docs/06-portability/03-device-validation-and-porting-sequence.md`](../docs/06-portability/03-device-validation-and-porting-sequence.md). +* [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md) — the five-rung evaluation ladder and evidence rules. +* [`Project-Status.md`](Project-Status.md) and [`System-Overview.md`](System-Overview.md) — current status and component map. +* [`Riscv-GSP-RM-Debugger.md`](Riscv-GSP-RM-Debugger.md) — firmware-side portability analysis. +* [`HAAEEP-and-Collaboration.md`](HAAEEP-and-Collaboration.md) — the edge use case and collaboration models. |