Some checks are pending
ci / test (push) Waiting to run
- resolve the NVIDIA branch and kernel-module flavor from PCI device IDs (Turing+ open modules; Maxwell/Pascal/Volta proprietary, masked below 595; Fermi/Kepler fall back to nouveau, reported; unknown IDs reported) - capture pci_id/pci_address in the probe; drive VIDEO_CARDS, package.use, package.accept_keywords, package.mask, modprobe.d and dracut from the plan, preserving hybrid Intel/AMD - add the nvidia_drivers install stage (after the kernel, before boot) that emerges the driver, regenerates the initramfs, records /etc/phoebus/nvidia and fails the install on failure; sys update rebuilds modules and the initramfs - refuse AI changes to x11-drivers/nvidia-drivers - live ISO: signed non-free components, stable-kernel pin (testing 7.2 breaks the 550 driver), DKMS build for the exact kernel, gated pre-greetd load, fail-safe entry, gpu-report, and a --verify-live-nvidia build gate that runs on cached rootfs builds and fails on any missing component - docs: ADR 0012, STATUS/CHANGELOG/HANDOFF, live README - also carries the pending OpenCode model-variant/streaming changes and fixes the GUI bridge install thread join that could hang
135 lines
6.9 KiB
Markdown
135 lines
6.9 KiB
Markdown
# ADR 0012: NVIDIA accelerated-driver policy and payload
|
|
|
|
- **Status:** Accepted
|
|
- **Date:** 2026-09-23
|
|
|
|
## Context
|
|
|
|
Phoebus must run NVIDIA's official accelerated driver stack on both targets:
|
|
|
|
- the **installed Gentoo system**, through Portage's `x11-drivers/nvidia-drivers`;
|
|
- the **Debian-based live ISO**, without downloading or compiling a driver at
|
|
boot.
|
|
|
|
NVIDIA's Linux driver has three relevant regimes (verified 2026-09 against
|
|
NVIDIA/Gentoo and the PCI ID database):
|
|
|
|
- **Turing (GTX 16xx / RTX 20xx) and newer** can use NVIDIA's **open kernel
|
|
modules** (`kernel-open`). The open modules are *recommended* from 560 and
|
|
*mandatory* from 595; Blackwell (RTX 50xx) requires them.
|
|
- **Maxwell, Pascal and Volta** cannot use the open modules and need the
|
|
proprietary modules from a branch that still supports them.
|
|
- **Fermi, Kepler and older** have no security-supported proprietary branch;
|
|
the in-tree `nouveau` driver is the honest choice.
|
|
|
|
The prior code classified GPUs only by vendor *name* and set
|
|
`VIDEO_CARDS="nvidia"` for any NVIDIA device, with no branch/flavor decision and
|
|
no live payload. This is unsafe: it can install a driver that cannot drive the
|
|
GPU, or claim success while the GPU is unserved.
|
|
|
|
## Decision
|
|
|
|
### 1. Classify from the PCI device ID, not marketing names
|
|
|
|
A generated table (`phoebus_core::nvidia_devices`, produced by
|
|
`scripts/generate-nvidia-devices.py` from the public PCI ID database) maps an
|
|
NVIDIA display device ID to its chip generation via the device's NVIDIA
|
|
codename. The probe records `vendor:device` and the PCI address for each
|
|
`VGA`/`3D`/`Display` controller. Unknown IDs are **reported as unknown** and
|
|
never claimed as supported.
|
|
|
|
### 2. Deterministic branch/flavor selection
|
|
|
|
One driver install covers every adapter, so the branch must serve the **oldest**
|
|
supported GPU present:
|
|
|
|
| Generation | Branch | Module flavor | Portage |
|
|
| --- | --- | --- | --- |
|
|
| Turing / Ampere / Ada / Hopper / Blackwell | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
|
|
| Maxwell / Pascal / Volta | proprietary | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-595` |
|
|
| Fermi / Kepler and older | none (nouveau) | — | no NVIDIA package |
|
|
|
|
Hybrid Intel/AMD GPUs keep their `VIDEO_CARDS` entries; the NVIDIA decision
|
|
only adds `nvidia`, or `nouveau` when the card is unserved.
|
|
|
|
### 3. The AI cannot change it
|
|
|
|
The driver branch and module flavor are **compatibility/security** decisions.
|
|
There is no AI action for them, `set_package_use` changes touching
|
|
`x11-drivers/nvidia-drivers` are refused by the fixed-policy check, and the
|
|
advisor prompt states the rule. The model may *explain* the choice, never
|
|
override it.
|
|
|
|
### 4. Installed Gentoo integration
|
|
|
|
- Scoped `package.use` (`dist-kernel`, `kernel-open`/`-kernel-open`), a scoped
|
|
`~amd64` keyword for the driver atom, and a scoped `package.mask` for the
|
|
legacy branch.
|
|
- A `modprobe.d` policy (nouveau blacklist, `nvidia_drm.modeset=1`,
|
|
`nvidia-uvm` softdep) and a dracut `force_drivers` fragment, both written
|
|
**before** the kernel is built.
|
|
- A dedicated `nvidia_drivers` install stage runs **after** the kernel and
|
|
**before** boot: it emerges the driver and regenerates the initramfs so the
|
|
modules and firmware are embedded. Its failure **fails the install**; the
|
|
resolved choice is recorded in `/etc/phoebus/nvidia` and shown in the plan.
|
|
- `sys update system` runs `@module-rebuild` and `kernel-install add-all` on
|
|
NVIDIA systems, so a kernel update rebuilds the modules and regenerates the
|
|
initramfs before the next boot.
|
|
|
|
### 5. Live ISO payload
|
|
|
|
- The signed Debian `contrib`/`non-free`/`non-free-firmware` components supply
|
|
the driver. Debian 13/testing ships branch **550.163.01**, whose proprietary
|
|
modules cover Maxwell through Ada/Hopper. **Blackwell is unsupported by that
|
|
branch**; on live it falls back to nouveau, reported, never silently claimed.
|
|
- The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Testing's
|
|
current kernel (7.2) removed the `strncpy` declaration the 550 driver still
|
|
uses, so `nvidia-kernel-dkms` cannot build against it; the rolling kernel
|
|
metas are filtered out and the exact stable kernel/headers/kbuild packages are
|
|
resolved from `trixie` and pinned in an apt setup hook.
|
|
- `livefs-hook.sh` builds the DKMS modules for that exact kernel and fails if
|
|
any module is missing. Debian renames them `nvidia-current*`; the hook and the
|
|
verifier accept either that or the upstream names.
|
|
- `build.sh` runs `--verify-live-nvidia` on **every** build (including
|
|
`PHOEBUS_REUSE_ROOTFS=1`): it checks modules, userspace libraries,
|
|
`nvidia-smi`, EGL external-platform manifests, firmware, the gated load script
|
|
and the nouveau blacklist, and records the bundled driver version, module
|
|
flavor and kernel in `/etc/phoebus/nvidia`. A missing or mismatched component
|
|
fails the build.
|
|
- Nouveau blacklisting and module options come from Debian's own
|
|
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
|
|
favour of a gated service that loads the driver before greetd/Mango **only
|
|
when an NVIDIA display device is present**, so Intel/AMD/virtual GPUs keep
|
|
their normal boot and no failed unit is recorded. The documented fail-safe
|
|
entry disables modesetting and blacklists the NVIDIA modules.
|
|
- Debian live packages and configuration never enter the Gentoo target.
|
|
|
|
A minimal live rootfs was built and its NVIDIA payload verified this session
|
|
(driver 550.163.01, kernel 6.12.107+deb13-amd64, modules `nvidia-current*`).
|
|
|
|
## Consequences
|
|
|
|
- The live image grows by the NVIDIA driver, firmware and userspace payload.
|
|
- The live branch (550) cannot accelerate Blackwell; the installed Gentoo system
|
|
can (open modules from the current branch). This asymmetry is documented.
|
|
- The live kernel is held at Debian stable rather than testing. This is
|
|
deliberate: it is both the project's stability preference and the only way the
|
|
Debian 550 driver builds. It must be revisited when Debian ships a driver
|
|
whose kernel support matches its testing kernel.
|
|
- The installed system may compile the driver from source; the `dist-kernel`
|
|
flag plus `@module-rebuild` keep it coherent across kernel updates.
|
|
- The generated device table must be regenerated when NVIDIA releases new
|
|
hardware; unknown IDs degrade safely to "unknown/nouveau" rather than a wrong
|
|
claim.
|
|
- **No NVIDIA-accelerated boot has been observed**: this host has no NVIDIA GPU
|
|
and QEMU's virtual GPU cannot establish it. A minimal live rootfs with the
|
|
driver was built and its payload verified, but the full ISO and the
|
|
live/installed NVIDIA gates are unverified here. This ADR records the design,
|
|
not a claim of working hardware acceleration.
|
|
|
|
## Non-goals
|
|
|
|
- NVIDIA's standalone `.run` installer (never; packages only).
|
|
- Bundling multiple driver branches in one live rootfs (they conflict).
|
|
- Forcing closed modules onto hardware that needs open modules, or vice versa.
|
|
- A global `~amd64` or a global `dist-kernel` switch.
|