From fade84f8b5b781d29daad40699d07928dedea550 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Wed, 23 Sep 2026 13:48:07 -0400 Subject: docs: merge the legacy flat documents, add the CUDA deep-dive and link checks * Merge and remove the pre-reboot flat documents, preserving their still-useful material in the structured tree: debugging workflows and the EPT-livelock case study (05-operations/02), performance microbenchmarks and A/B methodology (05-operations/01), the version-upgrade runbook (05-operations/02 section 4, with corrected host/guest framing), kernel-code pitfalls (07-developers) and the OpenRM build/load order (03-architecture/06 section 7). The remaining legacy files were verified redundant and removed. * docs/README now records where each migrated topic lives. * Portability: the config YAML files are called out as design targets that no code reads yet, with what adding support actually requires today. * Getting started: the OpenRM step is marked optional (native vGPU-management workflows only; the emulated path uses the distro driver). * tools docs: rmtool/rmtop marked as planned, pointing at the implemented tools/rmq subset. * wiki: new CUDA-Userspace-Driver deep-dive page (public-safe, links the canonical userspace/cuda analysis) and index update. * scripts/check-docs-links.py plus a CI step so relative links cannot rot. * STATE.md references to removed documents repointed. --- docs/06-portability/hardware-software-matrix.md | 40 ++++++++++++++++++++----- 1 file changed, 32 insertions(+), 8 deletions(-) (limited to 'docs/06-portability/hardware-software-matrix.md') diff --git a/docs/06-portability/hardware-software-matrix.md b/docs/06-portability/hardware-software-matrix.md index b8393f4..49c4bbe 100644 --- a/docs/06-portability/hardware-software-matrix.md +++ b/docs/06-portability/hardware-software-matrix.md @@ -27,7 +27,9 @@ | 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.** +require configuration + verification, not new code.** That is the design +direction, not the current state — the profile files are not read by any code +yet and selection is compile-time (see §6). ## 3. Guest operating systems @@ -90,13 +92,31 @@ config/ versions/.yaml # RPC/control inventories, capability tables ``` -There is no `profiles/` directory today. Note also that the code currently -hardcodes the TU104 profile, so the YAML surface is the intended interface -rather than the path the module reads at load time — treating it as -authoritative is aspirational until the profiles are wired in. - -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. +> **The `config/hardware/*.yaml` and `config/versions/*.yaml` files are +> design targets, not live configuration.** No code currently reads them: +> hardware/version 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. There is no `profiles/` directory today; +> `config/` is the only profile surface. + +**What "adding support" requires today** (TU104/570.144 is the reference): + +1. New GPU: edit the compile-time hardware constants/table for the target + (PCI IDs, BAR layout and sizes, memory geometry, engine inventory, + interrupt topology, probe-time register values) and rebuild the module; + the `config/hardware/*.yaml` file is documentation until the plumbing + exists. +2. New driver/firmware family: capture the init trace, diff the + RPC/control inventory, add version-keyed handlers, and register the + firmware signature for runtime identification; the `config/versions/*.yaml` + file is documentation until the plumbing exists. +3. Re-run the evaluation ladder and record the combination as + "hardware X + driver family Y + firmware Z, tested at rung R on date D." + Releases publish the table. + +A profile is the *unit of support* — what is missing is the code that reads +the profile files, not the profile schema. ### 6.1 Userspace driver facts @@ -131,6 +151,10 @@ start at | 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 | +These are design properties, not a description of the current build: today the +module is compiled for one profile (TU104) and the `config/` YAML is not on the +load path (see §6). + ## 8. Known portability risks | Risk | Mitigation | -- cgit v1.2.3