# 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.