feat(nvidia): hardware-driven driver policy, installed integration and live payload
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
This commit is contained in:
Phoebus 2026-09-22 21:53:28 -07:00
parent 040181abc2
commit b4a6b5df80
38 changed files with 3107 additions and 163 deletions

View file

@ -5,6 +5,64 @@ this file is the curated, human-readable summary.
Format: Keep a Changelog. Dates are UTC.
## 2026-09-23 — NVIDIA accelerated driver policy, live payload and installed integration
- **Hardware-driven driver policy (`phoebus-core::nvidia`):** a deterministic,
testable decision from the PCI display device IDs, backed by a generated table
(`nvidia_devices.rs`) derived from the public PCI ID database via each device's
NVIDIA chip codename. Turing/Ampere/Ada/Hopper/Blackwell use the current
`x11-drivers/nvidia-drivers` branch with NVIDIA's **open** kernel modules
(`kernel-open`); Maxwell/Pascal/Volta use the proprietary branch with
`-kernel-open` and are masked `>=x11-drivers/nvidia-drivers-595`; Fermi/Kepler
and older fall back to the in-tree `nouveau` and are reported, never claimed as
NVIDIA success. Unknown NVIDIA device IDs are reported as unknown.
- **Probe captures PCI identity:** display devices now carry `pci_id`
(`vendor:device`) and `pci_address`; `VIDEO_CARDS` uses the resolved plan
(`nvidia` only when a branch can serve the GPU, otherwise `nouveau`), while
hybrid Intel/AMD GPUs are preserved.
- **Installed Gentoo system:** scoped `package.use` (`dist-kernel`,
`kernel-open`/`-kernel-open`), a scoped `~amd64` keyword for the driver atom,
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 written **before** the kernel is built. A new
`nvidia_drivers` install stage (after the kernel, before boot) emerges the
driver and regenerates the initramfs so the modules are embedded; its failure
fails the install and the resolved choice is recorded in `/etc/phoebus/nvidia`
and shown in the plan. `sys update system` now runs `@module-rebuild` and
`kernel-install add-all` on NVIDIA systems so kernel/module/initramfs updates
stay coherent.
- **AI boundary:** the model cannot change the driver branch or module flavor;
a `set_package_use` change touching `x11-drivers/nvidia-drivers` is refused by
the fixed-policy check and the advisor prompt says so.
- **Live ISO:** the signed `contrib`/`non-free`/`non-free-firmware` components
are enabled and the NVIDIA driver, firmware and Wayland/EGL/GBM userspace are
bundled (`live-packages.list`). The live kernel is **pinned to Debian stable
(trixie, 6.12 LTS)** because testing's newer kernel (7.2) removed the
`strncpy` declaration the 550 driver still uses; installing the rolling kernel
metas would make `nvidia-kernel-dkms` unbuildable. `livefs-hook.sh` builds the
DKMS modules for that exact kernel (`nvidia-current*` on Debian) and fails if
any module is missing. Nouveau blacklisting and module options come from
Debian's own `nvidia-kernel-common`; its unconditional modules-load entry is
replaced by a gated `phoebus-nvidia.service` that loads the driver before
greetd/Mango only when an NVIDIA device is present. The documented fail-safe
entry disables modesetting and blacklists the NVIDIA modules. `build.sh`
verifies the assembled rootfs on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`) with `--verify-live-nvidia` and records the bundled
driver version, module flavor and kernel in `/etc/phoebus/nvidia`; a missing
module, library or firmware file fails the build.
- **Proven this session:** a minimal live rootfs (stable kernel + NVIDIA) was
built with `mmdebstrap` and the payload verified end to end: driver
`550.163.01`, kernel `6.12.107+deb13-amd64`, modules `nvidia-current`,
`-modeset`, `-uvm`, `-drm`. The full desktop ISO was **not** assembled here
(the host has ~10 GiB free and the build wants more), and no NVIDIA hardware
was available, so acceleration is unverified.
- **Not verified:** actual NVIDIA acceleration cannot be exercised on this host
(no NVIDIA GPU; QEMU's virtual GPU does not establish it). No NVIDIA hardware
passthrough setup is available or authorized. The live/installed NVIDIA boot
gates are **unverified** here (see `docs/STATUS.md`); this is implementation +
unit/integration tests + a proven payload build, not a claim of working
hardware acceleration.
## 2026-09-22 — Installer UX streamlining and DWM keybindings in Mango
- **Flatpak non-removable invariant:** Flatpak is a defining, required subsystem of

View file

@ -3,64 +3,105 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-22), installer UX streamlining and DWM keybindings.
- **Current focus:** Overhauled the graphical installer's defaults and usability based on live user testing:
1. Welcome window closes upon clicking "Install Phoebus OS" so the installer runs full-screen in Mango's tiling layout.
2. Rewrote dropdowns into `PhoebusCombo` with chevron toggle, live search filter, and full scrollable list with vertical scrollbar.
3. Switched keymap detection from ancient VT console trees to modern XKB rules (`evdev.lst`/`base.lst`) with human-readable labels, and filtered locales for clean UTF-8.
4. Removed "Test the live keyboard" card.
5. Simplified Account step: single username field (auto-populating fullname), single password field with "Use same password to encrypt disk" toggle, and removed the artificial 8-character length limit.
6. Removed manual options for desktop/filesystem/Nix/Flatpak; system defaults strictly to Mango + DMS, Btrfs with snapshots, and Nix + Flatpak enabled.
7. Removed typing "ERASE" and the confirmation checkbox; the overview screen clearly highlights the target and "Install now" starts directly.
8. Fixed the live install log details viewer with a dedicated scrollable log box and 1.5s refresh timer.
9. Added canonical DWM / DWL keybindings to `MANGO_CONFIG_DEFAULT` (Mod+Shift+Return terminal, Mod+Return zoom, Mod+j/k focusstack, Mod+Shift+j/k movestack, Mod+h/l setmfact, Mod+i/d incnmaster, Mod+Shift+c/q killclient, Mod+t/m/f layouts, Mod+Shift+Space float toggle, Mod+Tab view previous, Mod+1..9 tags, Mod+Shift+1..9 movetotag, mouse window drag/resize, Mod+Shift+r reload_config).
10. Enforced Flatpak as an essential, non-removable invariant across the entire system: removed `set_flatpak` from the AI advisor action list and examples so models never propose toggling it; added `fixed_policy_violation` check rejecting any proposal to disable Flatpak; filtered redundant Flatpak proposals in the GUI bridge and shell; enforced Flatpak in `validate_config`; and locked Flatpak to 'yes (required)' in the TUI.
- **Last updated:** this session (2026-09-23), NVIDIA accelerated-driver support
(policy, installed Gentoo integration, live ISO payload).
- **Current focus:** Implemented NVIDIA support end to end in code and tests:
1. `phoebus-core::nvidia` (plus generated `nvidia_devices.rs` from the PCI ID
database) resolves a driver branch and kernel-module flavor from the PCI
device IDs: Turing+ → current branch with open modules; Maxwell/Pascal/Volta
→ proprietary branch (`-kernel-open`, masked below 595); Fermi/Kepler and
older → nouveau fallback, reported. Unknown IDs are reported.
2. The probe now captures `pci_id`/`pci_address`; `VIDEO_CARDS`, `package.use`,
`package.accept_keywords`, `package.mask`, `modprobe.d` and dracut follow
the plan (hybrid Intel/AMD preserved).
3. Installed Gentoo: a new `nvidia_drivers` install stage (after kernel,
before boot) emerges the driver and regenerates the initramfs; it fails the
install on failure and records the choice in `/etc/phoebus/nvidia` (also
shown in the plan). `sys update system` runs `@module-rebuild` +
`kernel-install add-all` on NVIDIA systems.
4. Live ISO: signed non-free components, bundled driver/firmware/userspace,
DKMS built for the exact live kernel in `livefs-hook.sh`, a live-only
`phoebus-nvidia.service` that loads the driver before greetd/Mango, a
nouveau blacklist, a fail-safe boot entry, and a `--verify-live-nvidia`
build gate that runs on every build (including cached rootfs) and fails on
any missing/mismatched module, library or firmware.
5. The AI cannot change the driver: `set_package_use` on
`x11-drivers/nvidia-drivers` is refused and the advisor prompt says so.
- **Last verified (this session):**
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets` (clean, 0 errors).
- `cargo test --workspace` all tests passing (0 failures).
- Static release binary (`phoebus-installer`) built with `+crt-static` and copied to `/home/dominic/vmlab/serve/phoebus-installer`.
- Disposable graphical VM, rebuilt ISO
(`sha256 125d002b…`, 1.6 GiB): `gui` **28/28** PASS and `opencode` **18/18**
PASS, including the keyboard-suggestion regression, the blocked AI gate,
a real model response and validated proposal, and the new
"editing the model invalidates the connection" regression.
- `gui-install` (new mode) passed every journey assertion on a fresh 30 GiB
qcow2 — AI connect/accept, disk, account, ERASE, confirmation toggle —
and the backend then reported real stages with elapsed time and no
fabricated percentage. The install itself was still compiling the kernel
after four hours (the base-package stage alone took ~116 min on this host),
so the harness timed out; the **completed install + detached boot gate is
BLOCKED on host build time** (see `docs/VM-BOOT-VERIFICATION.md`).
- **Not yet verified this session:** the **complete graphical install and
detached boot** (BLOCKED on host build time — the 4h harness run was still
compiling the kernel; see blockers), the installed **Mango desktop**
rollback and NVIDIA checks are unchanged; rollback (`sys undo`) and the AI
sandbox remain unit-tested but not VM-verified, and the physical-seat desktop
and a separate physical computer remain open (see blockers).
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
finished with 0 errors (pre-existing warnings only).
- All tests pass for `phoebus-core` (142), `phoebus-ai` (35),
`phoebus-executor` (129), `phoebus-tui`, and every `phoebus-installer`
integration test (`plan_golden`, `cli_coverage` incl. the new
`--verify-live-nvidia` gate, `live_iso`, `ai_guidance`, `sys_cli`); the
non-`gui_bridge` installer library tests pass. The `gui_bridge` dry-run
tests block in this environment (pre-existing; unrelated to this change).
- New tests: PCI classification (representative IDs), branch/flavor policy,
Kepler/unknown fallback, hybrid, package/`modprobe`/dracut config, plan
exposure and stage ordering, live-payload verification (complete, missing
module, missing userspace/firmware, missing kernel, Debian `nvidia-current*`
naming), the AI refusal, and the `@module-rebuild`/`kernel-install` update
coordination.
- **Live NVIDIA payload build proven**: a minimal `mmdebstrap` rootfs
(Debian testing userspace + the pinned stable kernel) built the DKMS modules
and passed `--verify-live-nvidia` end to end: driver `550.163.01`, kernel
`6.12.107+deb13-amd64`, modules `nvidia-current/-modeset/-uvm/-drm`,
userspace + EGL/GBM + firmware present. The live kernel is now pinned to
Debian stable because testing's 7.2 kernel removed `strncpy` and breaks the
550 driver.
- **Not yet verified this session:** the **full desktop live ISO** was not
assembled (host disk ~10 GiB free; the build wants more), and the live/
installed NVIDIA boot gates are unrun: this host has no NVIDIA GPU (see
blockers). Actual NVIDIA acceleration is **not** verified. Rollback
(`sys undo`), the AI sandbox, the physical-seat desktop and a separate
physical computer remain open as before.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Installed Mango desktop**: install the default profile (Mango + DMS) in a
1. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
(or an explicitly authorized passthrough VM) boot the built live ISO and the
installed system and confirm: `phoebus-nvidia.service` loaded the driver,
`nvidia-smi` works, `cat /sys/module/nvidia_drm/parameters/modeset` is `Y`,
Mango/DMS logs in accelerated, XWayland/Flatpak render, monitors and
suspend/resume work, and a kernel update rebuilds the modules and initramfs.
Needs an NVIDIA GPU; none is available here and passthrough must not be
reconfigured unilaterally.
2. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
now bundles and verifies the NVIDIA payload. It needs more free space than
the ~12 GiB this host has; free space (do not delete unrelated files) and run
the `gui` harness to confirm ordinary virtual-GPU boot is unchanged.
3. **Installed Mango desktop**: install the default profile (Mango + DMS) in a
graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle,
the dwl fallback, and the welcome/installer absence on the installed system.
2. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run
4. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run
`sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the
recovery entry with no network or model (ADR 0007). Needed: (a) free the
>=20 GiB `make doctor` wants for the harness; (b) an automated driver for the
break-update/undo/recovery sequence — the harness has no such mode.
3. **Narrow the live broker privilege**: replace the live-only `NOPASSWD: ALL`
5. **Narrow the live broker privilege**: replace the live-only `NOPASSWD: ALL`
rule for the GUI bridge with the smallest practical command-scoped rule once
a safe sudoers form is verified (ADR 0011 context).
4. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
6. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
5. **Release gates on a CI runner**: `phoebus-release gates --execute` and
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- **NVIDIA hardware verification is BLOCKED**: this host has no NVIDIA GPU and
QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup
is available or authorized. Unit/integration tests and the live-payload
verifier pass, and a minimal live rootfs with the driver was built and
verified, but no NVIDIA-accelerated boot has been observed. The **full desktop
ISO** also cannot be assembled here: `df` shows ~10 GiB free. Unblock by
providing an NVIDIA GPU (or an authorized passthrough VM) and freeing disk
space, then running `installer/live/build.sh` and the `gui`/`install`/`boot`
harness modes. Note: the live kernel is pinned to Debian stable because
testing's 7.2 kernel breaks Debian's 550 driver; revisit when Debian ships a
matching driver.
- **The complete graphical install and detached boot are BLOCKED on host build
time.** The `gui-install` journey passes every assertion and starts a real
install, but on this host the base packages take ~116 min and the

View file

@ -114,7 +114,10 @@ still not VM-verified.
| `sys` verbs | yes | yes | yes | no |
| OpenCode pinned bootstrap | yes | yes | no | n/a |
| Release manifest/verify | yes | yes | no | n/a |
| NVIDIA proprietary | architecture only | no | no | no |
| NVIDIA PCI device classification + branch/flavor policy | yes | yes | no | no |
| NVIDIA installed Gentoo integration (Portage/modprobe/dracut/initramfs) | yes | yes | no | no |
| NVIDIA live ISO payload (bundled modules/firmware/userspace) | yes | yes (verifier + guards) | no | no |
| NVIDIA kernel/module/initramfs update coordination (`@module-rebuild`) | yes | yes | no | no |
| UKI | no (deferred) | no | no | no |
## Known limitations
@ -125,7 +128,22 @@ still not VM-verified.
installer for that purpose.
- **Flatpak apps** were not installed from the remote; only the runtime and
the flathub remote were verified.
- **NVIDIA** is architecturally allowed but not verified on hardware.
- **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped
Portage configuration, a live payload that is build-time verified, and
kernel/module/initramfs update coordination) and covered by Rust tests and the
live-payload verifier. A minimal live rootfs with the stable kernel and NVIDIA
driver was **built and verified** this session (driver 550.163.01, kernel
6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on
hardware**: this host has no NVIDIA GPU and QEMU's virtual GPU cannot
establish NVIDIA acceleration; no passthrough setup is available or
authorized. The full desktop ISO was not assembled here (the host has ~10 GiB
free; the build wants more) and the live/installed NVIDIA boot gates are
unrun. See `docs/VM-BOOT-VERIFICATION.md` for the exact unblock commands. The
live kernel is pinned to Debian stable (trixie 6.12 LTS) because testing's
kernel (7.2) breaks Debian's 550 driver; the bundled branch covers Maxwell
through Ada/Hopper, and Blackwell falls back to nouveau on the live medium.
The installed Gentoo system uses the current branch with NVIDIA's open kernel
modules on Turing and newer.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback is NOT VM-verified.** It is implemented and unit-tested end to end

View file

@ -639,7 +639,34 @@ re-verified on the final ISO.
- The graphical session was verified with the **headless** wlroots backend
(no logind seat in the serial harness). A physical VT / seat path is
architected (`phoebus-session`) but was not exercised on real hardware.
- NVIDIA proprietary support is architecturally allowed but **NOT VERIFIED**.
- NVIDIA proprietary support is implemented (hardware-driven branch/flavor
policy, scoped Portage configuration, a build-time-verified live payload, and
kernel/module/initramfs update coordination) with Rust tests. 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*`). It is
**NOT VERIFIED on hardware**: no NVIDIA GPU is present on this host, QEMU's
virtual GPU cannot establish NVIDIA acceleration, and no passthrough setup is
available or authorized. The full desktop ISO was not assembled here (the
host has ~10 GiB free; the build wants more).
The live kernel is pinned to Debian **stable** because Debian testing's
current kernel (7.2) removed the `strncpy` declaration the 550 driver uses, so
`nvidia-kernel-dkms` fails to build against it. The bundled branch covers
Maxwell through Ada/Hopper; Blackwell falls back to nouveau on the live
medium. The installed Gentoo system uses the current branch with open kernel
modules on Turing and newer.
**Unblock (hardware):** boot the built ISO on a machine with an NVIDIA GPU
(or an authorized passthrough VM) and check: `systemctl status
phoebus-nvidia.service`, `nvidia-smi`, `cat
/sys/module/nvidia_drm/parameters/modeset` == `Y`, an accelerated
Mango/DMS session, XWayland/Flatpak rendering, monitor handling and
suspend/resume. Then boot the installed Gentoo system and confirm the same,
plus that a kernel update rebuilds the modules via `@module-rebuild` and
regenerates the initramfs. **Unblock (build):** free sufficient disk space and
run `installer/live/build.sh` (it fails, by design, if the NVIDIA payload is
missing or mismatched), then the `gui` harness mode to confirm ordinary
virtual-GPU boot is unchanged.
- UKI is deferred (BLS is used).
- The installer rebuilds `sys-apps/systemd` from source because
boot/policykit/cryptsetup USE differ from the binhost. Shipping a matching

View file

@ -0,0 +1,135 @@
# 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.

View file

@ -17,5 +17,6 @@ and link it here.
| [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted |
| [0010](0010-graphical-installer-frontend.md) | Graphical installer frontend and typed bridge | Accepted |
| [0011](0011-opencode-connection-boundary.md) | OpenCode connection boundary | Accepted |
| [0012](0012-nvidia-driver-policy.md) | NVIDIA accelerated-driver policy and payload | Accepted |
Format: Context / Decision / Consequences / Status.

View file

@ -341,6 +341,16 @@ fn fixed_policy_violation(change: &ProposedChange) -> Option<String> {
ProposedChange::SetFlatpak { value: false } => Some(
"Flatpak is a required workstation subsystem and cannot be disabled or removed".into(),
),
ProposedChange::SetPackageUse { atom, flag, .. }
if atom.starts_with("x11-drivers/nvidia-drivers") =>
{
let _ = flag;
Some(
"the NVIDIA driver branch and kernel-module flavor are selected from the \
detected PCI device IDs and cannot be changed by the model"
.into(),
)
}
_ => None,
}
}
@ -559,6 +569,24 @@ mod tests {
assert!(config.packages.package_use.is_empty());
}
#[test]
fn review_refuses_to_change_the_nvidia_driver() {
let text = r#"{
"version": 1,
"changes": [
{"action":"set_package_use","atom":"x11-drivers/nvidia-drivers","flag":"kernel-open","enabled":false}
],
"rationale": [{"action":"set_package_use","reason":"force proprietary"}]
}"#;
let proposal = parse_proposal(text).unwrap();
let mut config = InstallConfig::default();
assert!(matches!(
review(&mut config, &proposal),
Err(AiError::Rejected(_))
));
assert!(config.packages.package_use.is_empty());
}
#[test]
fn review_refuses_to_weaken_required_settings() {
for (action, value) in [

View file

@ -245,8 +245,9 @@ propose disabling signature verification, enabling ~amd64 globally, weakening
LUKS2/Btrfs/systemd/UEFI, or any shell/command action; do not invent package
atoms; Flatpak, Nix, and the Mango + DMS desktop profile are required, non-removable
core subsystems of Phoebus OS (never propose disabling, toggling, or removing them);
keep required boot/encryption/filesystem/desktop settings fixed. You do not have
a shell and cannot execute anything.";
the NVIDIA driver branch and kernel-module flavor are selected from the detected
PCI device IDs and are not proposable; keep required boot/encryption/filesystem/desktop
settings fixed. You do not have a shell and cannot execute anything.";
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ChatMessage {
@ -503,6 +504,8 @@ mod tests {
gpus: vec![GpuInfo {
vendor: GpuVendor::Intel,
description: "iGPU".into(),
pci_id: None,
pci_address: None,
}],
..Default::default()
};

View file

@ -405,6 +405,8 @@ pub struct AiConfig {
pub opencode_provider: String,
/// OpenCode model id (e.g. `deepseek-chat`).
pub opencode_model: String,
/// OpenCode model variant (e.g. `default`, `low`, `high`, `max`).
pub opencode_variant: String,
}
impl AiConfig {
@ -421,6 +423,16 @@ impl AiConfig {
Some(server)
}
}
/// OpenCode model variant, defaulting to "default".
pub fn opencode_variant(&self) -> &str {
let v = self.opencode_variant.trim();
if v.is_empty() {
"default"
} else {
v
}
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]

View file

@ -82,6 +82,12 @@ impl CpuInfo {
pub struct GpuInfo {
pub vendor: GpuVendor,
pub description: String,
/// PCI `vendor:device` (lower-case hex), e.g. `10de:2482`, when known.
#[serde(default)]
pub pci_id: Option<String>,
/// PCI address, e.g. `0000:01:00.0`, when known.
#[serde(default)]
pub pci_address: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@ -228,14 +234,20 @@ mod tests {
GpuInfo {
vendor: GpuVendor::Intel,
description: "iGPU".into(),
pci_id: None,
pci_address: None,
},
GpuInfo {
vendor: GpuVendor::Intel,
description: "iGPU2".into(),
pci_id: None,
pci_address: None,
},
GpuInfo {
vendor: GpuVendor::Nvidia,
description: "dGPU".into(),
pci_id: None,
pci_address: None,
},
],
..Default::default()

View file

@ -12,6 +12,8 @@ pub mod effects;
pub mod emergelog;
pub mod error;
pub mod hardware;
pub mod nvidia;
pub mod nvidia_devices;
pub mod plan;
pub mod policy;
pub mod rollback;
@ -31,6 +33,7 @@ pub use config::{
pub use disk::{Disk, DiskKind, ProtectionReason};
pub use error::{CoreError, Result};
pub use hardware::{CpuInfo, FirmwareMode, GpuInfo, GpuVendor, HardwareReport, NetworkDevice};
pub use nvidia::{NvidiaDevice, NvidiaGeneration, NvidiaModuleFlavor, NvidiaPlan, NvidiaSupport};
pub use plan::{InstallPlan, InstallStep};
pub use policy::{
append_history, load_history, InstallMethod, PackageDecision, PackageDecisionReason,

View file

@ -0,0 +1,629 @@
//! NVIDIA accelerated-driver policy.
//!
//! This module turns the probed PCI display devices into a deterministic driver
//! decision: which NVIDIA driver branch, which kernel-module flavor (NVIDIA's
//! open kernel modules or the proprietary modules), and the exact scoped
//! Portage, dracut, modprobe and Debian-live configuration that follows from
//! it.
//!
//! It is data driven, not marketing-name driven. Device generation is resolved
//! from the PCI device ID via [`crate::nvidia_devices`], which is generated
//! from the public PCI ID database. The AI may explain the decision but has no
//! action that can change it (see `phoebus-ai`'s fixed-policy check).
//!
//! Branch policy (NVIDIA/Gentoo, verified 2026-09):
//!
//! * **Turing / Ampere / Ada / Hopper / Blackwell** use the current
//! `x11-drivers/nvidia-drivers` branch with NVIDIA's *open* kernel modules
//! (`USE=kernel-open`). The open modules support Turing (GTX 16xx / RTX 20xx)
//! and newer. They are mandatory from driver 595 and are required for
//! Blackwell (RTX 50xx).
//! * **Maxwell / Pascal / Volta** cannot use the open modules. They are pinned
//! to the newest proprietary branch below the open-mandatory cut (595) with
//! `USE=-kernel-open`, and `>=x11-drivers/nvidia-drivers-595` is masked.
//! * **Fermi / Kepler and older** are not served by a security-supported
//! proprietary branch; they fall back to the in-tree `nouveau` driver. This
//! is reported, never silently substituted as NVIDIA success.
//!
//! The Debian live medium ships a single signed branch (550.163.01 in Debian
//! 13/testing). That branch's proprietary kernel modules cover Maxwell through
//! Ada/Hopper; it does not support Blackwell, so Blackwell live boots fall back
//! to nouveau and are reported.
use serde::{Deserialize, Serialize};
use crate::hardware::{GpuInfo, GpuVendor, HardwareReport};
use crate::nvidia_devices;
/// The Gentoo package that provides the NVIDIA driver.
pub const GENTOO_ATOM: &str = "x11-drivers/nvidia-drivers";
/// The first NVIDIA driver series that makes the open kernel modules mandatory
/// (`USE=kernel-open` can no longer be disabled). Maxwell/Pascal/Volta are
/// pinned below this cut.
pub const OPEN_MANDATORY_SERIES: u32 = 595;
/// The NVIDIA branch bundled on the Debian live medium. It is a property of
/// the signed Debian archive, not of the detected GPU.
pub const LIVE_DEBIAN_BRANCH: &str = "550.163.01";
/// The Debian package that builds the proprietary kernel module for the live
/// kernel.
pub const LIVE_PROPRIETARY_KMOD: &str = "nvidia-kernel-dkms";
/// The Debian package that builds the open kernel module (Turing+ only).
pub const LIVE_OPEN_KMOD: &str = "nvidia-open-kernel-dkms";
/// NVIDIA GPU architecture generation, derived from the PCI device ID.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NvidiaGeneration {
Fermi,
Kepler,
Maxwell,
Pascal,
Volta,
Turing,
Ampere,
Ada,
Hopper,
Blackwell,
}
impl NvidiaGeneration {
/// Every generation, oldest first.
pub const ALL: [NvidiaGeneration; 10] = [
NvidiaGeneration::Fermi,
NvidiaGeneration::Kepler,
NvidiaGeneration::Maxwell,
NvidiaGeneration::Pascal,
NvidiaGeneration::Volta,
NvidiaGeneration::Turing,
NvidiaGeneration::Ampere,
NvidiaGeneration::Ada,
NvidiaGeneration::Hopper,
NvidiaGeneration::Blackwell,
];
pub fn as_str(self) -> &'static str {
match self {
NvidiaGeneration::Fermi => "Fermi",
NvidiaGeneration::Kepler => "Kepler",
NvidiaGeneration::Maxwell => "Maxwell",
NvidiaGeneration::Pascal => "Pascal",
NvidiaGeneration::Volta => "Volta",
NvidiaGeneration::Turing => "Turing",
NvidiaGeneration::Ampere => "Ampere",
NvidiaGeneration::Ada => "Ada",
NvidiaGeneration::Hopper => "Hopper",
NvidiaGeneration::Blackwell => "Blackwell",
}
}
/// Whether NVIDIA's open kernel modules support this generation.
pub fn supports_open_modules(self) -> bool {
matches!(
self,
NvidiaGeneration::Turing
| NvidiaGeneration::Ampere
| NvidiaGeneration::Ada
| NvidiaGeneration::Hopper
| NvidiaGeneration::Blackwell
)
}
/// The support decision for this generation.
pub fn support(self) -> NvidiaSupport {
match self {
NvidiaGeneration::Fermi | NvidiaGeneration::Kepler => NvidiaSupport::Unsupported,
NvidiaGeneration::Maxwell | NvidiaGeneration::Pascal | NvidiaGeneration::Volta => {
NvidiaSupport::Proprietary
}
_ => NvidiaSupport::Open,
}
}
}
/// How an NVIDIA generation is served.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NvidiaSupport {
/// Current branch with NVIDIA's open kernel modules.
Open,
/// A proprietary branch (Maxwell/Pascal/Volta), open modules unsupported.
Proprietary,
/// No security-supported proprietary branch: `nouveau` fallback.
Unsupported,
}
/// The kernel-module flavor actually installed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NvidiaModuleFlavor {
Open,
Proprietary,
}
impl NvidiaModuleFlavor {
pub fn as_str(self) -> &'static str {
match self {
NvidiaModuleFlavor::Open => "open",
NvidiaModuleFlavor::Proprietary => "proprietary",
}
}
}
/// One probed NVIDIA display device.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NvidiaDevice {
/// `vendor:device`, lower-case hex, e.g. `10de:2482`.
pub pci_id: String,
/// PCI address, e.g. `0000:01:00.0`, when known.
pub pci_address: Option<String>,
pub description: String,
/// `None` when the PCI ID database has no recognised NVIDIA codename.
pub generation: Option<NvidiaGeneration>,
}
impl NvidiaDevice {
/// Whether the device is claimed by the selected proprietary/open driver.
pub fn is_supported(&self) -> bool {
self.generation
.map(|g| g.support() != NvidiaSupport::Unsupported)
.unwrap_or(false)
}
/// The generation's support class, `Unsupported` for unknown hardware.
pub fn support(&self) -> NvidiaSupport {
self.generation
.map(|g| g.support())
.unwrap_or(NvidiaSupport::Unsupported)
}
}
/// The resolved NVIDIA driver decision for one machine.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NvidiaPlan {
/// Every NVIDIA display device that was probed.
pub devices: Vec<NvidiaDevice>,
/// True when at least one device is served by an NVIDIA branch.
pub supported: bool,
/// The newest supported generation present, if any.
pub generation: Option<NvidiaGeneration>,
/// The module flavor for the selected branch.
pub flavor: Option<NvidiaModuleFlavor>,
/// Human-readable branch label.
pub branch: String,
/// Why this decision was made (and what is left on nouveau).
pub reason: String,
}
impl NvidiaPlan {
/// The decision for a machine with no NVIDIA GPU.
pub fn none() -> Self {
Self {
devices: Vec::new(),
supported: false,
generation: None,
flavor: None,
branch: "none".into(),
reason: "no NVIDIA display device detected".into(),
}
}
/// Resolve the driver decision from probed hardware.
pub fn for_hardware(hardware: &HardwareReport) -> Self {
let devices: Vec<NvidiaDevice> = hardware
.gpus
.iter()
.filter(|g| g.vendor == GpuVendor::Nvidia)
.map(nvidia_device)
.collect();
if devices.is_empty() {
return Self::none();
}
let supported: Vec<&NvidiaDevice> = devices.iter().filter(|d| d.is_supported()).collect();
if supported.is_empty() {
let known: Vec<&str> = devices
.iter()
.map(|d| d.generation.map(|g| g.as_str()).unwrap_or("unknown"))
.collect();
return Self {
devices,
supported: false,
generation: None,
flavor: None,
branch: "nouveau".into(),
reason: format!(
"no security-supported NVIDIA branch for {}; using the in-tree nouveau fallback",
known.join(", ")
),
};
}
// The branch must serve the oldest supported adapter present, because
// one driver install covers every card. Maxwell/Pascal/Volta force the
// proprietary branch; otherwise the open modules are used.
let needs_proprietary = supported
.iter()
.any(|d| d.support() == NvidiaSupport::Proprietary);
let flavor = if needs_proprietary {
NvidiaModuleFlavor::Proprietary
} else {
NvidiaModuleFlavor::Open
};
let generation = supported
.iter()
.filter_map(|d| d.generation)
.max()
.unwrap_or(NvidiaGeneration::Turing);
let mut reason = match flavor {
NvidiaModuleFlavor::Open => format!(
"{} uses the current branch with NVIDIA's open kernel modules",
generation.as_str()
),
NvidiaModuleFlavor::Proprietary => format!(
"{} requires the proprietary branch (open kernel modules do not support Maxwell/Pascal/Volta)",
generation.as_str()
),
};
let unclaimed: Vec<String> = devices
.iter()
.filter(|d| !d.is_supported())
.map(|d| {
format!(
"{} ({})",
d.pci_id,
d.generation.map(|g| g.as_str()).unwrap_or("unknown")
)
})
.collect();
if !unclaimed.is_empty() {
reason.push_str(&format!(
"; {} remains on the nouveau fallback",
unclaimed.join(", ")
));
}
Self {
devices,
supported: true,
generation: Some(generation),
flavor: Some(flavor),
branch: match flavor {
NvidiaModuleFlavor::Open => {
format!("current open kernel modules (>= {OPEN_MANDATORY_SERIES})")
}
NvidiaModuleFlavor::Proprietary => {
format!("proprietary (for Maxwell/Pascal/Volta; capped below {OPEN_MANDATORY_SERIES})")
}
},
reason,
}
}
/// The `VIDEO_CARDS` entry this decision contributes.
pub fn video_cards_entry(&self) -> Option<&'static str> {
self.supported.then_some("nvidia")
}
/// The `x11-drivers/nvidia-drivers` atom, or `None` for nouveau.
pub fn gentoo_atom(&self) -> Option<&'static str> {
self.supported.then_some(GENTOO_ATOM)
}
/// Scoped `package.use` lines for the selected branch.
pub fn gentoo_package_use(&self) -> Vec<String> {
match self.flavor {
Some(NvidiaModuleFlavor::Open) => {
vec![format!("{GENTOO_ATOM} dist-kernel kernel-open")]
}
Some(NvidiaModuleFlavor::Proprietary) => {
vec![format!("{GENTOO_ATOM} dist-kernel -kernel-open")]
}
None => Vec::new(),
}
}
/// `package.mask` lines. Maxwell/Pascal/Volta must stay below the branch
/// that made the open modules mandatory.
pub fn gentoo_package_mask(&self) -> Vec<String> {
match self.flavor {
Some(NvidiaModuleFlavor::Proprietary) => {
vec![format!(">={GENTOO_ATOM}-{OPEN_MANDATORY_SERIES}")]
}
_ => Vec::new(),
}
}
/// Scoped `package.accept_keywords` lines. The NVIDIA branch is a hardware
/// enabler; the keyword stays scoped to this atom, never a global `~amd64`.
pub fn gentoo_accept_keywords(&self) -> Vec<String> {
self.supported
.then(|| format!("{GENTOO_ATOM} ~amd64"))
.into_iter()
.collect()
}
/// Kernel modules that must be present and loaded for acceleration.
pub fn kernel_modules(&self) -> Vec<&'static str> {
if self.supported {
vec!["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"]
} else {
Vec::new()
}
}
/// `/etc/modprobe.d` content: keep `nouveau` off the claimed GPU, enable
/// DRM modesetting, and make `nvidia-uvm` a soft dependency so dracut does
/// not embed a dangling module reference.
pub fn modprobe_conf(&self) -> Option<String> {
if !self.supported {
return None;
}
let mut o = String::new();
o.push_str("# NVIDIA accelerated driver (generated by the Phoebus installer).\n");
o.push_str("# Keep the in-tree nouveau driver from binding the GPU that the\n");
o.push_str("# selected NVIDIA branch is meant to drive.\n");
o.push_str("blacklist nouveau\n");
o.push_str("options nouveau modeset=0\n");
o.push_str("options nvidia_drm modeset=1\n");
o.push_str("softdep nvidia post: nvidia-uvm\n");
Some(o)
}
/// `/etc/dracut.conf.d` fragment that forces the modules (and their
/// firmware) into the initramfs for early KMS.
pub fn dracut_conf(&self) -> Option<String> {
if !self.supported {
return None;
}
let drivers = self.kernel_modules().join(" ");
Some(format!(
"# NVIDIA accelerated driver: load DRM/modeset early (generated).\nforce_drivers+=\" {drivers} \"\n"
))
}
/// The live-medium module flavor. The bundled Debian branch is decided at
/// build time; this reflects what the live image records.
pub fn live_flavor(&self) -> NvidiaModuleFlavor {
// The live branch's proprietary modules cover every generation the
// Debian branch supports (Maxwell..Ada/Hopper). Open modules are only
// needed on the installed system for Turing+.
NvidiaModuleFlavor::Proprietary
}
/// Debian packages bundled in the live rootfs so the ISO needs no network
/// and compiles nothing at boot.
pub fn live_packages(&self) -> Vec<&'static str> {
let mut out = vec![
// Kernel modules (built for the exact live kernel during the build).
LIVE_PROPRIETARY_KMOD,
// Userspace: GLX/EGL/GLES/VDPAU/Vulkan, nvidia-smi, modprobe.
"nvidia-driver",
"nvidia-vulkan-icd",
"nvidia-suspend-common",
// Wayland/EGL/GBM integration for nvidia-drm.
"libnvidia-egl-gbm1",
"libnvidia-egl-wayland1",
// Firmware must be present or the module refuses to initialise.
"firmware-nvidia-graphics",
"firmware-nvidia-gsp",
];
out.sort_unstable();
out.dedup();
out
}
/// A human-readable decision line for the installation plan.
pub fn render(&self) -> Option<String> {
if self.devices.is_empty() {
return None;
}
let mut out = String::new();
out.push_str(&format!(" NVIDIA driver : {}\n", self.branch));
if let Some(flavor) = self.flavor {
out.push_str(&format!(
" Module flavor: {}\n",
match flavor {
NvidiaModuleFlavor::Open => "open (kernel-open)",
NvidiaModuleFlavor::Proprietary => "proprietary (kernel-open disabled)",
}
));
}
for device in &self.devices {
out.push_str(&format!(
" {} {} [{}]\n",
device.pci_id,
device
.generation
.map(|g| g.as_str())
.unwrap_or("unknown generation"),
device.description
));
}
out.push_str(&format!(" {}\n", self.reason));
Some(out)
}
}
/// Build a [`NvidiaDevice`] from a probed display device.
fn nvidia_device(gpu: &GpuInfo) -> NvidiaDevice {
let pci_id = gpu.pci_id.clone().unwrap_or_default();
let generation = gpu
.pci_id
.as_deref()
.and_then(parse_pci_pair)
.and_then(|(vendor, device)| {
if vendor == 0x10de {
nvidia_devices::generation_for_device(device)
} else {
None
}
});
NvidiaDevice {
pci_id,
pci_address: gpu.pci_address.clone(),
description: gpu.description.clone(),
generation,
}
}
/// Parse `vendor:device` (hex) into `(vendor, device)`.
pub fn parse_pci_pair(value: &str) -> Option<(u16, u16)> {
let (vendor, device) = value.split_once(':')?;
let vendor = u16::from_str_radix(vendor.trim(), 16).ok()?;
let device = u16::from_str_radix(device.trim(), 16).ok()?;
Some((vendor, device))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::hardware::{GpuInfo, HardwareReport};
fn nvidia(id: &str, description: &str) -> GpuInfo {
GpuInfo {
vendor: GpuVendor::Nvidia,
description: description.into(),
pci_id: Some(id.into()),
pci_address: Some("0000:01:00.0".into()),
}
}
fn hardware(gpus: Vec<GpuInfo>) -> HardwareReport {
HardwareReport {
gpus,
..Default::default()
}
}
#[test]
fn turing_uses_open_modules() {
let hw = hardware(vec![nvidia("10de:1e04", "TU102 [GeForce RTX 2080 Ti]")]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(plan.supported);
assert_eq!(plan.generation, Some(NvidiaGeneration::Turing));
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Open));
assert_eq!(plan.video_cards_entry(), Some("nvidia"));
assert_eq!(plan.gentoo_package_mask(), Vec::<String>::new());
assert!(plan.gentoo_package_use()[0].contains("kernel-open"));
}
#[test]
fn pascal_uses_the_proprietary_branch_and_is_masked_below_595() {
let hw = hardware(vec![nvidia("10de:1b81", "GP104 [GeForce GTX 1070]")]);
let plan = NvidiaPlan::for_hardware(&hw);
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary));
assert_eq!(
plan.gentoo_package_mask(),
vec![">=x11-drivers/nvidia-drivers-595".to_string()]
);
assert!(plan.gentoo_package_use()[0].contains("-kernel-open"));
}
#[test]
fn blackwell_uses_open_modules() {
let hw = hardware(vec![nvidia("10de:2b85", "GB202 [GeForce RTX 5090]")]);
let plan = NvidiaPlan::for_hardware(&hw);
assert_eq!(plan.generation, Some(NvidiaGeneration::Blackwell));
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Open));
}
#[test]
fn kepler_falls_back_to_nouveau_and_is_reported() {
let hw = hardware(vec![nvidia("10de:0fc0", "GK107 [GeForce GT 640]")]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(!plan.supported);
assert_eq!(plan.branch, "nouveau");
assert!(plan.reason.contains("nouveau"));
assert_eq!(plan.gentoo_atom(), None);
assert!(plan.modprobe_conf().is_none());
}
#[test]
fn unknown_nvidia_device_is_not_claimed() {
let hw = hardware(vec![nvidia("10de:dead", "NVIDIA Corporation Device")]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(!plan.supported);
assert!(plan.reason.contains("unknown"));
}
#[test]
fn hybrid_system_keeps_the_igpu_and_selects_nvidia() {
let hw = hardware(vec![
GpuInfo {
vendor: GpuVendor::Intel,
description: "Intel UHD".into(),
pci_id: Some("8086:9a60".into()),
pci_address: Some("0000:00:02.0".into()),
},
nvidia("10de:2482", "GA104 [GeForce RTX 3070]"),
]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(plan.supported);
assert_eq!(plan.generation, Some(NvidiaGeneration::Ampere));
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Open));
}
#[test]
fn mixed_old_and_new_picks_the_proprietary_branch_for_the_oldest() {
let hw = hardware(vec![
nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"),
nvidia("10de:2482", "GA104 [GeForce RTX 3070]"),
]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(plan.supported);
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary));
}
#[test]
fn no_nvidia_gpu_has_no_plan() {
let hw = hardware(vec![GpuInfo {
vendor: GpuVendor::Amd,
description: "AMD Radeon".into(),
pci_id: Some("1002:73ff".into()),
pci_address: Some("0000:03:00.0".into()),
}]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(!plan.supported);
assert!(plan.render().is_none());
}
#[test]
fn modprobe_and_dracut_are_consistent() {
let hw = hardware(vec![nvidia("10de:2482", "GA104 [GeForce RTX 3070]")]);
let plan = NvidiaPlan::for_hardware(&hw);
let modprobe = plan.modprobe_conf().unwrap();
assert!(modprobe.contains("blacklist nouveau"));
assert!(modprobe.contains("options nvidia_drm modeset=1"));
let dracut = plan.dracut_conf().unwrap();
for module in plan.kernel_modules() {
assert!(dracut.contains(module), "dracut must force {module}");
}
}
#[test]
fn live_packages_include_module_firmware_and_wayland_gl() {
let hw = hardware(vec![nvidia("10de:2482", "GA104 [GeForce RTX 3070]")]);
let plan = NvidiaPlan::for_hardware(&hw);
let packages = plan.live_packages();
for expected in [
LIVE_PROPRIETARY_KMOD,
"firmware-nvidia-graphics",
"firmware-nvidia-gsp",
"libnvidia-egl-gbm1",
"libnvidia-egl-wayland1",
] {
assert!(packages.contains(&expected), "missing {expected}");
}
}
#[test]
fn parse_pci_pair_is_strict() {
assert_eq!(parse_pci_pair("10de:2482"), Some((0x10de, 0x2482)));
assert_eq!(parse_pci_pair("zzzz"), None);
}
}

View file

@ -0,0 +1,156 @@
//! NVIDIA PCI device-ID classification table.
//!
//! GENERATED FILE - do not edit by hand. Regenerate with
//! `scripts/generate-nvidia-devices.py`. The table is derived
//! from the public PCI ID database (`pci.ids`, NVIDIA vendor `10de`)
//! by mapping each device's NVIDIA chip codename to its generation.
//!
//! Source: https://pci-ids.ucw.cz/v2.2/pci.ids
//! Source SHA-256: 44b158db134c3177013378c299c462608af53f0f1043da2fac7affde73be0d73
use super::nvidia::NvidiaGeneration;
/// The PCI ID database revision this table was generated from.
pub const SOURCE_SHA256: &str = "44b158db134c3177013378c299c462608af53f0f1043da2fac7affde73be0d73";
/// Classify an NVIDIA PCI device ID (the `device` half of the
/// `vendor:device` pair, fully qualified).
///
/// `None` means the database has no recognised NVIDIA chip codename for
/// the device: it is reported as unknown and never claimed as supported.
pub fn generation_for_device(device_id: u16) -> Option<NvidiaGeneration> {
use NvidiaGeneration::*;
match device_id {
0x06c0 | 0x06c4 | 0x06ca | 0x06cb | 0x06cd | 0x0be5 | 0x0be9 | 0x0bea | 0x0beb | 0x0bee
| 0x0dc0 | 0x0dc4 | 0x0dc5 | 0x0dc6 | 0x0dcd | 0x0dce | 0x0dd1 | 0x0dd2 | 0x0dd3
| 0x0dd6 | 0x0de0 | 0x0de1 | 0x0de2 | 0x0de3 | 0x0de4 | 0x0de5 | 0x0de7 | 0x0de8
| 0x0de9 | 0x0dea | 0x0deb | 0x0dec | 0x0ded | 0x0dee | 0x0def | 0x0df0 | 0x0df1
| 0x0df2 | 0x0df3 | 0x0df4 | 0x0df5 | 0x0df6 | 0x0df7 | 0x0e08 | 0x0e09 | 0x0e0c
| 0x0e22 | 0x0e23 | 0x0e24 | 0x0e30 | 0x0e31 | 0x0f00 | 0x0f01 | 0x0f02 | 0x0f03
| 0x0f06 | 0x1040 | 0x1042 | 0x1045 | 0x1048 | 0x1049 | 0x104a | 0x104b | 0x104c
| 0x104d | 0x1050 | 0x1051 | 0x1052 | 0x1054 | 0x1055 | 0x1056 | 0x1057 | 0x1058
| 0x1059 | 0x105a | 0x105b | 0x107c | 0x107d | 0x1080 | 0x1081 | 0x1082 | 0x1084
| 0x1086 | 0x1087 | 0x1088 | 0x1089 | 0x108b | 0x1140 | 0x1200 | 0x1201 | 0x1202
| 0x1203 | 0x1205 | 0x1206 | 0x1207 | 0x1208 | 0x1210 | 0x1211 | 0x1212 | 0x1213
| 0x1241 | 0x1243 | 0x1244 | 0x1245 | 0x1246 | 0x1247 | 0x1248 | 0x1249 | 0x124b
| 0x124d | 0x1251 => Some(Fermi),
0x0e0a | 0x0e0b | 0x0e0f | 0x0e1a | 0x0e1b | 0x0fc0 | 0x0fc1 | 0x0fc2 | 0x0fc4 | 0x0fc5
| 0x0fc6 | 0x0fc8 | 0x0fc9 | 0x0fcb | 0x0fcc | 0x0fcd | 0x0fce | 0x0fcf | 0x0fd0
| 0x0fd1 | 0x0fd2 | 0x0fd3 | 0x0fd4 | 0x0fd5 | 0x0fd6 | 0x0fd7 | 0x0fd8 | 0x0fd9
| 0x0fda | 0x0fdb | 0x0fdc | 0x0fdd | 0x0fde | 0x0fdf | 0x0fe0 | 0x0fe1 | 0x0fe2
| 0x0fe3 | 0x0fe4 | 0x0fe5 | 0x0fe6 | 0x0fe8 | 0x0fe9 | 0x0fea | 0x0fec | 0x0fed
| 0x0fee | 0x0ff0 | 0x0ff1 | 0x0ffd | 0x1001 | 0x1003 | 0x1004 | 0x1005 | 0x1007
| 0x1008 | 0x100a | 0x100c | 0x1180 | 0x1182 | 0x1183 | 0x1184 | 0x1185 | 0x1186
| 0x1187 | 0x1188 | 0x1189 | 0x118c | 0x118e | 0x1191 | 0x1193 | 0x1195 | 0x1198
| 0x1199 | 0x119a | 0x119d | 0x119e | 0x119f | 0x11a0 | 0x11a1 | 0x11a2 | 0x11a3
| 0x11a4 | 0x11a5 | 0x11a7 | 0x11a9 | 0x11aa | 0x11ac | 0x11c0 | 0x11c1 | 0x11c2
| 0x11c3 | 0x11c4 | 0x11c5 | 0x11c6 | 0x11c7 | 0x11c8 | 0x11cb | 0x11d0 | 0x11d1
| 0x11d2 | 0x11d3 | 0x11e0 | 0x11e1 | 0x11e2 | 0x11e3 | 0x11e7 | 0x11ff | 0x1280
| 0x1281 | 0x1282 | 0x1283 | 0x1284 | 0x1285 | 0x1286 | 0x1287 | 0x1288 | 0x1289
| 0x128a | 0x128b | 0x128c | 0x1290 | 0x1291 | 0x1292 | 0x1293 | 0x1294 | 0x1295
| 0x1296 | 0x1298 | 0x12a0 | 0x12ad | 0x12ae | 0x12af | 0x12b0 | 0x12b1 | 0x130b => {
Some(Kepler)
}
0x0fb0 | 0x0fba | 0x0fbb | 0x0fbc | 0x1340 | 0x1341 | 0x1344 | 0x1346 | 0x1347 | 0x1348
| 0x1349 | 0x134b | 0x134d | 0x134e | 0x134f | 0x137d | 0x1380 | 0x1381 | 0x1382
| 0x1390 | 0x1391 | 0x1392 | 0x1393 | 0x1398 | 0x1399 | 0x139a | 0x139b | 0x139c
| 0x139d | 0x13ad | 0x13ae | 0x13be | 0x13bf | 0x13c0 | 0x13c1 | 0x13c2 | 0x13c3
| 0x13c4 | 0x13d7 | 0x13d8 | 0x13d9 | 0x13da | 0x13e4 | 0x1401 | 0x1402 | 0x1404
| 0x1406 | 0x1407 | 0x1427 | 0x1617 | 0x1618 | 0x1619 | 0x161a | 0x1667 | 0x174d
| 0x174e | 0x179c | 0x17c2 | 0x17c8 => Some(Maxwell),
0x0fb8 | 0x10ef | 0x10f0 | 0x10f1 | 0x15c2 | 0x1725 | 0x172e | 0x172f | 0x1b00 | 0x1b01
| 0x1b02 | 0x1b04 | 0x1b06 | 0x1b07 | 0x1b80 | 0x1b81 | 0x1b82 | 0x1b83 | 0x1b84
| 0x1b87 | 0x1ba0 | 0x1ba1 | 0x1ba2 | 0x1ba9 | 0x1baa | 0x1bad | 0x1bc7 | 0x1c00
| 0x1c01 | 0x1c02 | 0x1c03 | 0x1c04 | 0x1c06 | 0x1c07 | 0x1c09 | 0x1c20 | 0x1c21
| 0x1c22 | 0x1c23 | 0x1c2d | 0x1c35 | 0x1c36 | 0x1c81 | 0x1c82 | 0x1c83 | 0x1c8c
| 0x1c8d | 0x1c8e | 0x1c8f | 0x1c90 | 0x1c91 | 0x1c92 | 0x1c94 | 0x1c96 | 0x1d01
| 0x1d02 | 0x1d10 | 0x1d11 | 0x1d12 | 0x1d13 | 0x1d16 => Some(Pascal),
0x1d81 | 0x1d83 | 0x1d84 | 0x1dbe | 0x1dc1 | 0x1df4 => Some(Volta),
0x10f7 | 0x10f8 | 0x10f9 | 0x1ad6 | 0x1ad7 | 0x1ad8 | 0x1ad9 | 0x1ada | 0x1adb | 0x1aeb
| 0x1aec | 0x1aed | 0x1e02 | 0x1e03 | 0x1e04 | 0x1e07 | 0x1e09 | 0x1e2d | 0x1e2e
| 0x1e81 | 0x1e82 | 0x1e84 | 0x1e87 | 0x1e89 | 0x1e90 | 0x1e91 | 0x1e93 | 0x1eab
| 0x1eae | 0x1ec2 | 0x1ec7 | 0x1f02 | 0x1f03 | 0x1f04 | 0x1f06 | 0x1f07 | 0x1f08
| 0x1f09 | 0x1f0a | 0x1f0b | 0x1f10 | 0x1f11 | 0x1f12 | 0x1f14 | 0x1f15 | 0x1f2e
| 0x1f42 | 0x1f47 | 0x1f81 | 0x1f82 | 0x1f83 | 0x1f91 | 0x1f92 | 0x1f94 | 0x1f95
| 0x1f96 | 0x1f97 | 0x1f98 | 0x1f99 | 0x1f9c | 0x1f9d | 0x1f9f | 0x1fa0 | 0x1fa1
| 0x2182 | 0x2183 | 0x2184 | 0x2186 | 0x2187 | 0x2188 | 0x2189 | 0x2191 | 0x2192
| 0x21c2 | 0x21c3 | 0x21c4 => Some(Turing),
0x1aef | 0x1af1 | 0x2080 | 0x2081 | 0x2082 | 0x20b0 | 0x20b1 | 0x20b2 | 0x20b3 | 0x20b4
| 0x20b5 | 0x20b8 | 0x20b9 | 0x20bb | 0x20bd | 0x20be | 0x20bf | 0x20c0 | 0x20c2
| 0x20f0 | 0x20f1 | 0x20f2 | 0x20f3 | 0x20f5 | 0x20f6 | 0x20fd | 0x20fe | 0x20ff
| 0x2200 | 0x2203 | 0x2204 | 0x2205 | 0x2206 | 0x2207 | 0x2208 | 0x220a | 0x220d
| 0x2216 | 0x222b | 0x222f | 0x228b | 0x228e | 0x2291 | 0x2414 | 0x2420 | 0x2460
| 0x2480 | 0x2482 | 0x2483 | 0x2484 | 0x2486 | 0x2487 | 0x2488 | 0x2489 | 0x248a
| 0x248c | 0x248d | 0x248e | 0x249c | 0x249d | 0x249f | 0x24a0 | 0x24a4 | 0x24ac
| 0x24ad | 0x24af | 0x24bf | 0x24c0 | 0x24c7 | 0x24c8 | 0x24c9 | 0x24dc | 0x24dd
| 0x24df | 0x24e0 | 0x24fa | 0x2501 | 0x2503 | 0x2504 | 0x2505 | 0x2507 | 0x2508
| 0x2509 | 0x2520 | 0x2521 | 0x2523 | 0x252f | 0x2531 | 0x2544 | 0x2560 | 0x2561
| 0x2563 | 0x2571 | 0x2582 | 0x2583 | 0x2584 | 0x25a0 | 0x25a2 | 0x25a3 | 0x25a4
| 0x25a5 | 0x25a6 | 0x25a7 | 0x25a9 | 0x25aa | 0x25ab | 0x25ad | 0x25af | 0x25ed
| 0x25f9 | 0x25fa | 0x25fb => Some(Ampere),
0x22ba | 0x22bb | 0x22bc | 0x22bd | 0x22be | 0x2681 | 0x2684 | 0x2685 | 0x2689 | 0x26af
| 0x2702 | 0x2703 | 0x2704 | 0x2705 | 0x2709 | 0x2717 | 0x2757 | 0x2782 | 0x2783
| 0x2785 | 0x2786 | 0x2788 | 0x27a0 | 0x27e0 | 0x2803 | 0x2805 | 0x2808 | 0x2820
| 0x2822 | 0x2860 | 0x2882 | 0x28a0 | 0x28a1 | 0x28a3 | 0x28e0 | 0x28e1 | 0x28e3 => {
Some(Ada)
}
0x22a3 | 0x2302 | 0x230c | 0x230e | 0x2313 | 0x2321 | 0x2322 | 0x2324 | 0x2328 | 0x2329
| 0x232c | 0x2330 | 0x2331 | 0x2335 | 0x2336 | 0x2337 | 0x2338 | 0x2339 | 0x233a
| 0x233b | 0x233d | 0x2342 | 0x2343 | 0x2345 | 0x2348 | 0x237e | 0x237f | 0x23b0
| 0x23f0 => Some(Hopper),
0x22ce | 0x22d0 | 0x22d1 | 0x22e8 | 0x22e9 | 0x22eb | 0x22ec | 0x2900 | 0x2901 | 0x2909
| 0x2920 | 0x2924 | 0x2925 | 0x293d | 0x2940 | 0x2941 | 0x297e | 0x2980 | 0x29bb
| 0x29bc | 0x29c0 | 0x29f1 | 0x2b00 | 0x2b85 | 0x2b87 | 0x2b8c | 0x2c02 | 0x2c05
| 0x2c09 | 0x2c18 | 0x2c19 | 0x2c58 | 0x2c59 | 0x2d04 | 0x2d05 | 0x2d18 | 0x2d19
| 0x2d58 | 0x2d59 | 0x2d83 | 0x2d98 | 0x2dd8 | 0x2e03 | 0x2e06 | 0x2e12 | 0x2e13
| 0x2e2a | 0x2f04 | 0x2f06 | 0x2f18 | 0x2f58 | 0x2f80 | 0x3180 | 0x3182 | 0x31a1
| 0x31c0 | 0x31c2 | 0x31c3 | 0x31fe | 0x3200 | 0x3224 | 0x323e | 0x3340 | 0x3400 => {
Some(Blackwell)
}
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn representative_devices_classify() {
assert_eq!(
generation_for_device(0x1380),
Some(NvidiaGeneration::Maxwell)
);
assert_eq!(
generation_for_device(0x1b81),
Some(NvidiaGeneration::Pascal)
);
assert_eq!(generation_for_device(0x1d81), Some(NvidiaGeneration::Volta));
assert_eq!(
generation_for_device(0x1e04),
Some(NvidiaGeneration::Turing)
);
assert_eq!(
generation_for_device(0x2482),
Some(NvidiaGeneration::Ampere)
);
assert_eq!(generation_for_device(0x2684), Some(NvidiaGeneration::Ada));
assert_eq!(
generation_for_device(0x2330),
Some(NvidiaGeneration::Hopper)
);
assert_eq!(
generation_for_device(0x2b85),
Some(NvidiaGeneration::Blackwell)
);
assert_eq!(
generation_for_device(0x0fc0),
Some(NvidiaGeneration::Kepler)
);
}
#[test]
fn unknown_device_is_not_classified() {
assert_eq!(generation_for_device(0x0000), None);
}
}

View file

@ -18,6 +18,9 @@ pub enum InstallStep {
PortageConfigure,
PackagesBase,
KernelInstall,
/// Install the NVIDIA accelerated driver (no-op without supported hardware)
/// and regenerate the initramfs so its modules are embedded.
NvidiaDrivers,
BootInstall,
UsersConfigure,
ServicesConfigure,
@ -34,6 +37,7 @@ impl InstallStep {
InstallStep::PortageConfigure => "portage_configure",
InstallStep::PackagesBase => "packages_base",
InstallStep::KernelInstall => "kernel_install",
InstallStep::NvidiaDrivers => "nvidia_drivers",
InstallStep::BootInstall => "boot_install",
InstallStep::UsersConfigure => "users_configure",
InstallStep::ServicesConfigure => "services_configure",
@ -52,6 +56,7 @@ impl InstallStep {
InstallStep::PortageConfigure,
InstallStep::PackagesBase,
InstallStep::KernelInstall,
InstallStep::NvidiaDrivers,
InstallStep::BootInstall,
InstallStep::UsersConfigure,
InstallStep::ServicesConfigure,
@ -186,6 +191,12 @@ impl InstallPlan {
" AI assistant : {}\n",
if config.ai.enabled { "yes" } else { "no" }
));
if let Some(hw) = hardware {
if let Some(line) = crate::nvidia::NvidiaPlan::for_hardware(hw).render() {
o.push_str(" GPU acceleration:\n");
o.push_str(&line);
}
}
o
}
@ -255,4 +266,40 @@ mod tests {
assert!(text.contains("TARGET: /dev/vda"));
assert!(text.contains("vda 30G"));
}
#[test]
fn plan_exposes_the_resolved_nvidia_driver() {
use crate::hardware::{GpuInfo, GpuVendor, HardwareReport};
let mut hw = HardwareReport::default();
hw.gpus.push(GpuInfo {
vendor: GpuVendor::Nvidia,
description: "GA104 [GeForce RTX 3070]".into(),
pci_id: Some("10de:2482".into()),
pci_address: Some("0000:01:00.0".into()),
});
let cfg = InstallConfig::default();
let text = InstallPlan::for_config(&cfg).render_human(&cfg, Some(&hw));
assert!(text.contains("GPU acceleration:"));
assert!(text.contains("NVIDIA driver"));
assert!(text.contains("open (kernel-open)"));
assert!(text.contains("10de:2482"));
}
#[test]
fn plan_omits_gpu_acceleration_without_an_nvidia_gpu() {
use crate::hardware::HardwareReport;
let cfg = InstallConfig::default();
let text =
InstallPlan::for_config(&cfg).render_human(&cfg, Some(&HardwareReport::default()));
assert!(!text.contains("GPU acceleration:"));
}
#[test]
fn step_sequence_places_nvidia_after_the_kernel_and_before_boot() {
let names: Vec<&str> = InstallStep::sequence().iter().map(|s| s.name()).collect();
let kernel = names.iter().position(|n| *n == "kernel_install").unwrap();
let nvidia = names.iter().position(|n| *n == "nvidia_drivers").unwrap();
let boot = names.iter().position(|n| *n == "boot_install").unwrap();
assert!(kernel < nvidia && nvidia < boot);
}
}

View file

@ -183,15 +183,29 @@ pub fn makeopts(cores: u32, memory_mib: u64, build_jobs: Option<u32>) -> String
}
pub fn video_cards(hardware: &HardwareReport) -> String {
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
let mut cards: Vec<String> = Vec::new();
let push = |card: &str, cards: &mut Vec<String>| {
if !cards.iter().any(|c| c == card) {
cards.push(card.to_string());
}
};
for vendor in hardware.gpu_vendors() {
match vendor {
GpuVendor::Intel => cards.push("intel".into()),
GpuVendor::Intel => push("intel", &mut cards),
GpuVendor::Amd => {
cards.push("amdgpu".into());
cards.push("radeonsi".into());
push("amdgpu", &mut cards);
push("radeonsi", &mut cards);
}
// An NVIDIA GPU the selected proprietary/open branch cannot serve
// uses the in-tree nouveau driver; it is never claimed as NVIDIA.
GpuVendor::Nvidia => {
if nvidia.supported {
push("nvidia", &mut cards);
} else {
push("nouveau", &mut cards);
}
}
GpuVendor::Nvidia => cards.push("nvidia".into()),
GpuVendor::Unknown => {}
}
}
@ -253,7 +267,7 @@ pub fn repos_conf() -> String {
/// GURU is git-only (no rsync), so `dev-vcs/git` must be installed before it
/// can be synced. It is a reviewed, signed-over-git community overlay; the
/// installer scopes `~amd64` to the specific packages rather than unmasking it.
pub const GURU_REPO_URI: &str = "https://anongit.gentoo.org/git/proj/guru.git";
pub const GURU_REPO_URI: &str = "https://anongit.gentoo.org/git/repo/proj/guru.git";
pub fn guru_repos_conf() -> String {
let mut o = String::new();
@ -333,7 +347,7 @@ pub fn binrepos_conf(config: &InstallConfig) -> String {
o
}
pub fn package_use(config: &InstallConfig) -> String {
pub fn package_use(config: &InstallConfig, hardware: &HardwareReport) -> String {
let mut o = String::new();
o.push_str(&format!(
"# {} installer policy\n",
@ -385,15 +399,51 @@ pub fn package_use(config: &InstallConfig) -> String {
o.push_str(&format!("{} {}{}\n", entry.atom, prefix, entry.flag));
}
}
// NVIDIA accelerated driver. Derived from the PCI device IDs, never from a
// name or an AI proposal; Maxwell/Pascal/Volta keep the proprietary branch
// (`-kernel-open`) while Turing and newer use NVIDIA's open modules.
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
let nvidia_use = nvidia.gentoo_package_use();
if !nvidia_use.is_empty() {
o.push_str("# NVIDIA accelerated driver (hardware-derived)\n");
for line in &nvidia_use {
o.push_str(line);
o.push('\n');
}
}
o
}
pub fn accept_keywords_policy() -> String {
/// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay below the
/// branch that made NVIDIA's open kernel modules mandatory.
pub fn package_mask(config: &InstallConfig, hardware: &HardwareReport) -> String {
let _ = config;
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
let mask = nvidia.gentoo_package_mask();
let mut o = String::new();
if !mask.is_empty() {
o.push_str("# NVIDIA: proprietary branch required for Maxwell/Pascal/Volta.\n");
for line in &mask {
o.push_str(line);
o.push('\n');
}
}
o
}
pub fn accept_keywords_policy(hardware: &HardwareReport) -> String {
let mut o = String::new();
o.push_str("# Phoebus: scoped testing keywords for hardware/desktop enablement.\n");
o.push_str("# This is NOT a global ~amd64 switch.\n");
o.push_str("sys-kernel/linux-firmware\n");
o.push_str("gui-wm/dwl\n");
// The NVIDIA driver is a hardware enabler; the keyword is scoped to the
// atom so the branch selection (and its pinned mask) stays deterministic.
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
for line in nvidia.gentoo_accept_keywords() {
o.push_str(&line);
o.push('\n');
}
o
}
@ -411,7 +461,7 @@ pub fn install_conf() -> String {
o
}
pub fn dracut_conf(config: &InstallConfig) -> String {
pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String {
let mut o = String::new();
o.push_str(&format!(
"# {} dracut configuration\n",
@ -421,6 +471,11 @@ pub fn dracut_conf(config: &InstallConfig) -> String {
o.push_str("hostonly=\"no\"\n");
o.push_str("compress=\"zstd\"\n");
o.push_str("add_dracutmodules+=\" crypt btrfs \"\n");
// NVIDIA: force the DRM/modeset modules (and their firmware) into the
// initramfs so the compositor never starts against a modeset-less GPU.
if let Some(nvidia) = crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf() {
o.push_str(&nvidia);
}
o
}
@ -1113,6 +1168,70 @@ pub fn default_session_command(profile: DesktopProfile) -> &'static str {
/// The live ISO's unprivileged user.
pub const LIVE_USER: &str = "phoebus";
/// `phoebus-nvidia-load`: live-only. It runs before the graphical session and
/// loads NVIDIA's accelerated stack only when an NVIDIA display device is
/// present, so systems without one keep the in-tree driver and never record a
/// failed unit.
pub const PHOEBUS_NVIDIA_LOAD_SCRIPT: &str = r#"#!/bin/bash
# Load the NVIDIA accelerated driver on the live medium, but only when an
# NVIDIA display controller is actually present. nouveau is blacklisted by
# nvidia-kernel-common, so nothing else claims the GPU first. Debian's
# nvidia-kernel-dkms names the modules nvidia-current*, and its modprobe
# `install` directives map the upstream names used below.
set -u
if ! grep -lq 0x10de /sys/bus/pci/devices/*/vendor 2>/dev/null; then
echo "phoebus-nvidia: no NVIDIA display device; leaving the in-tree driver in charge"
exit 0
fi
if ! modprobe nvidia-drm; then
echo "phoebus-nvidia: could not load nvidia-drm; run phoebus-gpu-report" >&2
exit 1
fi
# Unified memory is a soft dependency; a failure here is not fatal for the
# desktop but is reported.
modprobe nvidia-uvm || echo "phoebus-nvidia: nvidia-uvm did not load" >&2
echo "phoebus-nvidia: NVIDIA modules loaded"
"#;
/// `phoebus-nvidia.service`: load the driver before greetd/Mango.
pub const PHOEBUS_NVIDIA_SERVICE: &str = r#"[Unit]
Description=Load the NVIDIA accelerated driver (Phoebus live)
Documentation=man:nvidia(4)
After=systemd-modules-load.service
Before=display-manager.service greetd.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/phoebus-nvidia-load
TimeoutStartSec=30
[Install]
WantedBy=multi-user.target
"#;
/// `phoebus-gpu-report`: live diagnostics when NVIDIA initialisation is
/// suspect. Read-only.
pub const PHOEBUS_GPU_REPORT_SCRIPT: &str = r#"#!/bin/bash
# Phoebus GPU diagnostics: what claimed the display, and did nvidia_drm come up?
set -u
echo "== display devices =="
lspci -nnk 2>/dev/null | grep -A3 -Ei 'VGA|3D controller|Display controller' || echo "(lspci unavailable)"
echo
echo "== loaded GPU modules =="
grep -E 'nvidia|nouveau' /proc/modules 2>/dev/null || echo "(neither nvidia nor nouveau is loaded)"
echo
echo "== nvidia_drm modeset =="
cat /sys/module/nvidia_drm/parameters/modeset 2>/dev/null || echo "(nvidia_drm not loaded)"
echo
echo "== nvidia-smi =="
nvidia-smi 2>&1 | head -20 || true
echo
echo "== recent kernel GPU messages =="
dmesg 2>/dev/null | grep -Ei 'nvidia|nouveau|drm' | tail -30 \
|| echo "(dmesg needs privileges; try: sudo dmesg | grep -Ei 'nvidia|nouveau|drm')"
"#;
/// A named desktop asset, so the live ISO build and the installer use exactly
/// the same configuration and session scripts. `None` for an unknown name.
pub fn desktop_asset(name: &str) -> Option<String> {
@ -1134,6 +1253,10 @@ pub fn desktop_asset(name: &str) -> Option<String> {
"install-desktop" => PHOEBUS_INSTALL_DESKTOP_ENTRY.to_string(),
"greetd-installed" => greetd_config(default_cmd),
"greetd-live" => greetd_config_live(LIVE_USER, live_cmd),
// Live-only NVIDIA driver loading and diagnostics.
"nvidia-load" => PHOEBUS_NVIDIA_LOAD_SCRIPT.to_string(),
"nvidia-service" => PHOEBUS_NVIDIA_SERVICE.to_string(),
"gpu-report" => PHOEBUS_GPU_REPORT_SCRIPT.to_string(),
"wayland-session-mango" => wayland_session_entry(DesktopProfile::Mango)?.1,
"wayland-session-dwl" => wayland_session_entry(DesktopProfile::Dwl)?.1,
// The brand system lives in `brand`; route the shared `--emit-asset`
@ -1442,10 +1565,10 @@ mod tests {
fn desktop_none_has_no_x_use_block() {
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::None;
let text = package_use(&cfg);
let text = package_use(&cfg, &crate::hardware::HardwareReport::default());
assert!(!text.contains("x11-libs/cairo X"));
cfg.desktop.profile = DesktopProfile::Dwl;
let text = package_use(&cfg);
let text = package_use(&cfg, &crate::hardware::HardwareReport::default());
assert!(text.contains("x11-libs/cairo X"));
assert!(text.contains("media-libs/libglvnd X"));
assert!(text.contains("sys-fs/btrfs-progs -man"));
@ -1474,7 +1597,7 @@ mod tests {
fn package_use_is_clean_and_keeps_required_flags() {
let mut cfg = InstallConfig::default();
cfg.desktop.profile = DesktopProfile::Dwl;
let text = package_use(&cfg);
let text = package_use(&cfg, &crate::hardware::HardwareReport::default());
// Required boot/encryption/session flags stay.
assert!(text.contains("sys-apps/systemd boot policykit cryptsetup"));
assert!(text.contains("sys-kernel/installkernel dracut systemd systemd-boot"));
@ -1494,7 +1617,7 @@ mod tests {
flag: "wayland".into(),
enabled: false,
});
let text = package_use(&cfg);
let text = package_use(&cfg, &crate::hardware::HardwareReport::default());
assert!(text.contains("www-client/firefox -wayland"));
}
@ -1762,4 +1885,80 @@ mod tests {
.contains("Install Phoebus"));
assert!(desktop_asset("does-not-exist").is_none());
}
#[test]
fn live_nvidia_assets_are_bounded_and_ordered_before_greetd() {
let load = desktop_asset("nvidia-load").unwrap();
assert!(load.contains("0x10de"));
assert!(load.contains("modprobe nvidia"));
let service = desktop_asset("nvidia-service").unwrap();
assert!(service.contains("Before=display-manager.service greetd.service"));
assert!(service.contains("ExecStart=/usr/local/bin/phoebus-nvidia-load"));
let report = desktop_asset("gpu-report").unwrap();
assert!(report.contains("nvidia-smi"));
assert!(report.contains("nvidia_drm"));
}
fn nvidia_hw(id: &str) -> HardwareReport {
let mut hw = HardwareReport::default();
hw.gpus.push(crate::hardware::GpuInfo {
vendor: GpuVendor::Nvidia,
description: id.into(),
pci_id: Some(id.into()),
pci_address: None,
});
hw
}
#[test]
fn nvidia_turing_uses_open_modules_and_scoped_keywords() {
let cfg = InstallConfig::default();
let hw = nvidia_hw("10de:1e04");
assert_eq!(video_cards(&hw), "nvidia");
let use_text = package_use(&cfg, &hw);
assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open"));
assert!(package_mask(&cfg, &hw).trim().is_empty());
assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64"));
let dracut = dracut_conf(&cfg, &hw);
assert!(dracut.contains("force_drivers+="));
assert!(dracut.contains("nvidia_drm"));
}
#[test]
fn nvidia_pascal_uses_proprietary_and_masks_the_open_mandatory_branch() {
let cfg = InstallConfig::default();
let hw = nvidia_hw("10de:1b81");
let use_text = package_use(&cfg, &hw);
assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel -kernel-open"));
assert_eq!(
package_mask(&cfg, &hw),
"# NVIDIA: proprietary branch required for Maxwell/Pascal/Volta.\n\
>=x11-drivers/nvidia-drivers-595\n"
);
}
#[test]
fn nvidia_kepler_uses_nouveau_not_a_claim_of_nvidia() {
let cfg = InstallConfig::default();
let hw = nvidia_hw("10de:0fc0");
assert_eq!(video_cards(&hw), "nouveau");
assert!(!package_use(&cfg, &hw).contains("nvidia-drivers"));
assert!(package_mask(&cfg, &hw).is_empty());
assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers"));
assert!(!dracut_conf(&cfg, &hw).contains("nvidia"));
}
#[test]
fn hybrid_nvidia_keeps_the_integrated_gpu_in_video_cards() {
let mut hw = nvidia_hw("10de:2482");
hw.gpus.push(crate::hardware::GpuInfo {
vendor: GpuVendor::Intel,
description: "Intel UHD".into(),
pci_id: Some("8086:9a60".into()),
pci_address: None,
});
let cards = video_cards(&hw);
assert!(cards.contains("nvidia"));
assert!(cards.contains("intel"));
}
}

View file

@ -490,6 +490,29 @@ pub fn execute(
"@world".into(),
],
)?;
// A system with the NVIDIA out-of-tree driver must rebuild its
// modules against any newly installed kernel and regenerate the
// initramfs, so modules, userspace libraries and the boot image stay
// coherent before the next reboot. The record is written by the
// installer (or by the installed system's driver setup).
if root.join("etc/phoebus/nvidia").is_file() {
run_in_target(
exec,
root,
"sys",
"rebuild NVIDIA modules",
"emerge",
&["@module-rebuild".into()],
)?;
run_in_target(
exec,
root,
"sys",
"regenerate the initramfs",
"kernel-install",
&["add-all".into()],
)?;
}
"system update complete".to_string()
}
SystemAction::CreateSnapshot { operation } => {
@ -656,6 +679,36 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
);
}
#[test]
fn updating_an_nvidia_system_rebuilds_modules_and_the_initramfs() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
std::fs::create_dir_all(exec.root.join("etc/phoebus")).unwrap();
std::fs::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").unwrap();
std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap();
let auth = auth();
execute(
&exec,
&SystemAction::UpdateSystem,
Some(&auth),
Path::new(&exec.root),
)
.unwrap();
let specs = runner.recorded();
assert!(
specs
.iter()
.any(|s| s.args.iter().any(|a| a == "@module-rebuild")),
"the NVIDIA modules must be rebuilt after a kernel update"
);
assert!(
specs
.iter()
.any(|s| s.args.iter().any(|a| a == "kernel-install")),
"the initramfs must be regenerated with the rebuilt modules"
);
}
#[test]
fn protective_snapshot_id_is_preserved_in_the_outcome() {
let runner = RecordingRunner::new();

View file

@ -7,7 +7,7 @@
use std::path::{Path, PathBuf};
use phoebus_core::system as sysgen;
use phoebus_core::InstallConfig;
use phoebus_core::{HardwareReport, InstallConfig};
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
@ -22,12 +22,24 @@ pub fn write_install_conf(exec: &Exec) -> Result<()> {
Ok(())
}
pub fn write_dracut_conf(exec: &Exec, config: &InstallConfig) -> Result<()> {
pub fn write_dracut_conf(
exec: &Exec,
config: &InstallConfig,
hardware: &HardwareReport,
) -> Result<()> {
exec.target().write(
"etc/dracut.conf.d/10-phoebus.conf",
sysgen::dracut_conf(config),
sysgen::dracut_conf(config, hardware),
)?;
exec.logger.info("wrote /etc/dracut.conf.d/10-phoebus.conf");
// NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be
// in place before the kernel is built and its initramfs generated.
if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() {
exec.target()
.write("etc/modprobe.d/phoebus-nvidia.conf", conf)?;
exec.logger
.info("wrote /etc/modprobe.d/phoebus-nvidia.conf (nouveau blacklist, modeset)");
}
Ok(())
}
@ -323,6 +335,31 @@ mod tests {
Exec::new(Box::new(runner), logger, false, path.join("root"), path)
}
#[test]
fn nvidia_hardware_writes_modprobe_and_dracut_before_the_kernel_build() {
use phoebus_core::hardware::{GpuInfo, GpuVendor};
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let cfg = InstallConfig::default();
let mut hw = HardwareReport::default();
hw.gpus.push(GpuInfo {
vendor: GpuVendor::Nvidia,
description: "GA104 [GeForce RTX 3070]".into(),
pci_id: Some("10de:2482".into()),
pci_address: Some("0000:01:00.0".into()),
});
write_dracut_conf(&exec, &cfg, &hw).unwrap();
let dracut =
std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/10-phoebus.conf")).unwrap();
assert!(dracut.contains("force_drivers+="));
assert!(dracut.contains("nvidia_drm"));
let modprobe =
std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap();
assert!(modprobe.contains("blacklist nouveau"));
assert!(modprobe.contains("options nvidia_drm modeset=1"));
}
#[test]
fn recovery_entry_reuses_kernel_and_initrd() {
let runner = RecordingRunner::new();

View file

@ -102,14 +102,36 @@ impl CommandOutput {
}
}
pub type StreamSink = Arc<dyn Fn(&str) + Send + Sync>;
pub trait ProcessRunner: Send + Sync {
fn execute(&self, spec: &CommandSpec) -> Result<CommandOutput>;
fn is_streaming(&self) -> bool {
false
}
}
/// The real process runner.
pub struct RealRunner;
#[derive(Clone, Default)]
pub struct RealRunner {
sink: Option<StreamSink>,
}
impl RealRunner {
pub fn new() -> Self {
Self { sink: None }
}
pub fn with_sink(sink: StreamSink) -> Self {
Self { sink: Some(sink) }
}
}
impl ProcessRunner for RealRunner {
fn is_streaming(&self) -> bool {
self.sink.is_some()
}
fn execute(&self, spec: &CommandSpec) -> Result<CommandOutput> {
let start = Instant::now();
let mut command = Command::new(&spec.program);
@ -142,19 +164,66 @@ impl ProcessRunner for RealRunner {
}
}
let output = child
.wait_with_output()
.map_err(|source| ExecError::Spawn {
let mut stdout_pipe = child.stdout.take();
let mut stderr_pipe = child.stderr.take();
let (stdout, stderr) = std::thread::scope(|s| {
let out_handle = s.spawn(|| {
let mut captured = Vec::new();
if let Some(pipe) = stdout_pipe.take() {
let mut reader = std::io::BufReader::new(pipe);
let mut buf = Vec::new();
use std::io::BufRead;
while let Ok(n) = reader.read_until(b'\n', &mut buf) {
if n == 0 {
break;
}
captured.extend_from_slice(&buf);
if let Some(sink) = &self.sink {
let text = String::from_utf8_lossy(&buf);
sink(&text);
}
buf.clear();
}
}
captured
});
let err_handle = s.spawn(|| {
let mut captured = Vec::new();
if let Some(pipe) = stderr_pipe.take() {
let mut reader = std::io::BufReader::new(pipe);
let mut buf = Vec::new();
use std::io::BufRead;
while let Ok(n) = reader.read_until(b'\n', &mut buf) {
if n == 0 {
break;
}
captured.extend_from_slice(&buf);
if let Some(sink) = &self.sink {
let text = String::from_utf8_lossy(&buf);
sink(&text);
}
buf.clear();
}
}
captured
});
(out_handle.join().unwrap(), err_handle.join().unwrap())
});
let status = child.wait().map_err(|source| ExecError::Spawn {
program: spec.program.clone(),
source,
})?;
let duration = start.elapsed();
let status = output.status.code().unwrap_or(-1);
let code = status.code().unwrap_or(-1);
Ok(CommandOutput {
status,
success: output.status.success(),
stdout: output.stdout,
stderr: output.stderr,
status: code,
success: status.success(),
stdout,
stderr,
duration,
})
}
@ -276,7 +345,7 @@ mod tests {
#[test]
fn real_runner_runs_a_trivial_command() {
let runner = RealRunner;
let runner = RealRunner::new();
let spec = CommandSpec::new("test", "true", "true");
assert!(runner.execute(&spec).unwrap().success);
}

View file

@ -53,6 +53,13 @@ impl Exec {
return Ok(CommandOutput::dry_run());
}
let stdin_hidden = spec.stdin.is_some();
self.logger.command_start(
&spec.stage,
&spec.operation,
&spec.program,
&spec.args,
stdin_hidden,
);
let output = self.runner.execute(&spec)?;
self.logger.command(
&spec.stage,
@ -63,12 +70,14 @@ impl Exec {
output.duration,
stdin_hidden,
);
if !self.runner.is_streaming() {
if !output.stdout.is_empty() {
self.logger.output(&output.stdout);
}
if !output.stderr.is_empty() {
self.logger.output(&output.stderr);
}
}
if !output.success {
return Err(ExecError::Command {
stage: spec.stage.clone(),

View file

@ -15,6 +15,7 @@ pub mod encryption;
pub mod error;
pub mod exec;
pub mod kernel;
pub mod live_nvidia;
pub mod log;
pub mod nix;
pub mod opencode;

View file

@ -0,0 +1,496 @@
//! Validation and recording of the NVIDIA payload bundled in the live ISO.
//!
//! The live medium must already contain the driver's kernel modules (built for
//! the exact live kernel), userspace libraries, Wayland/EGL/GBM integration and
//! firmware: nothing is compiled or downloaded at boot. This verifier runs on
//! the assembled rootfs on every build, including a `PHOEBUS_REUSE_ROOTFS=1`
//! build, so a cached rootfs can never silently ship without the payload.
use std::path::{Path, PathBuf};
use phoebus_core::nvidia::NvidiaModuleFlavor;
use crate::error::{ExecError, Result};
/// What was found in the live rootfs. Written verbatim into
/// `/etc/phoebus/nvidia` so the bundled versions are inspectable on the medium.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LiveNvidiaPayload {
pub kernel_version: String,
pub driver_version: String,
pub flavor: String,
pub modules: Vec<String>,
pub userspace: Vec<String>,
pub firmware: Vec<String>,
}
impl LiveNvidiaPayload {
/// The `/etc/phoebus/nvidia` record.
pub fn record(&self) -> String {
let mut o = String::new();
o.push_str("# NVIDIA payload bundled in the Phoebus live medium.\n");
o.push_str("# Generated at build time; proves the ISO carries a driver\n");
o.push_str("# matching the live kernel instead of compiling one at boot.\n");
o.push_str(&format!("kernel_version={}\n", self.kernel_version));
o.push_str(&format!("driver_version={}\n", self.driver_version));
o.push_str(&format!("flavor={}\n", self.flavor));
for module in &self.modules {
o.push_str(&format!("module={module}\n"));
}
for lib in &self.userspace {
o.push_str(&format!("userspace={lib}\n"));
}
for fw in &self.firmware {
o.push_str(&format!("firmware={fw}\n"));
}
o
}
pub fn render(&self) -> String {
format!(
"NVIDIA live payload OK: driver {} ({}) for kernel {}; modules: {}; \
{} userspace file(s); {} firmware file(s)",
self.driver_version,
self.flavor,
self.kernel_version,
self.modules.join(", "),
self.userspace.len(),
self.firmware.len()
)
}
}
fn fail(message: String) -> ExecError {
ExecError::operation("live", "verify nvidia payload", message)
}
/// The one kernel directory that contains `modules.dep`.
///
/// Debian is merged-usr: `/lib` is a symlink to `usr/lib`, so both module roots
/// describe the same kernel. Versions are deduplicated so a merged-usr rootfs
/// is not mistaken for a multi-kernel image.
fn kernel_version(rootfs: &Path) -> Result<String> {
let mut candidates: std::collections::BTreeMap<String, PathBuf> =
std::collections::BTreeMap::new();
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = rootfs.join(modules_root);
let Ok(entries) = std::fs::read_dir(&dir) else {
continue;
};
for entry in entries.flatten() {
let path = entry.path();
if !path.is_dir() || !path.join("modules.dep").exists() {
continue;
}
// Prefer a kernel that the live medium actually ships a vmlinuz for,
// so a stale build-only module tree cannot satisfy the check.
let version = entry.file_name().to_string_lossy().to_string();
if rootfs.join(format!("boot/vmlinuz-{version}")).exists() {
candidates.entry(version).or_insert(path);
}
}
}
match candidates.len() {
0 => Err(fail(
"no kernel with modules.dep and a matching /boot/vmlinuz was found".into(),
)),
1 => Ok(candidates.into_keys().next().unwrap_or_default()),
_ => Err(fail(format!(
"the live rootfs ships multiple kernels ({}); exactly one is expected",
candidates
.keys()
.map(String::as_str)
.collect::<Vec<_>>()
.join(", ")
))),
}
}
fn walk(root: &Path, out: &mut Vec<String>) {
if let Ok(entries) = std::fs::read_dir(root) {
for entry in entries.flatten() {
let path = entry.path();
// `DirEntry::file_type` does not follow symlinks, so an absolute
// symlink inside the rootfs can never make us walk the host.
match entry.file_type() {
Ok(ft) if ft.is_dir() => walk(&path, out),
Ok(_) => {
if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
out.push(name.to_string());
}
}
Err(_) => {}
}
}
}
}
/// Read a rootfs-relative file, resolving symlinks **within** the rootfs.
fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
let mut current = rootfs.join(rel.trim_start_matches('/'));
for _ in 0..16 {
match std::fs::symlink_metadata(&current) {
Err(_) => return None,
Ok(meta) if meta.file_type().is_symlink() => {
let target = std::fs::read_link(&current).ok()?;
current = if target.is_absolute() {
rootfs.join(target.strip_prefix("/").unwrap_or(&target))
} else {
current.parent().unwrap_or(rootfs).join(target)
};
}
Ok(_) => return std::fs::read_to_string(&current).ok(),
}
}
None
}
/// Whether `rel` (relative to the rootfs) resolves to a file, following
/// symlinks **within** the rootfs. Absolute symlinks are meaningless outside it,
/// so they are resolved against the rootfs, never the host.
fn exists_in_rootfs(rootfs: &Path, rel: &str) -> bool {
let mut current = rootfs.join(rel.trim_start_matches('/'));
for _ in 0..16 {
match std::fs::symlink_metadata(&current) {
Err(_) => return false,
Ok(meta) if meta.file_type().is_symlink() => {
let Ok(target) = std::fs::read_link(&current) else {
return false;
};
if target.is_absolute() {
current = rootfs.join(target.strip_prefix("/").unwrap_or(&target));
} else {
current = current.parent().unwrap_or(rootfs).join(target);
}
}
Ok(meta) => return meta.is_file(),
}
}
false
}
/// All file names under `root`, for a bounded, rootfs-relative search.
fn names_under(root: &Path) -> Vec<String> {
let mut out = Vec::new();
walk(root, &mut out);
out
}
/// The logical NVIDIA module and the on-disk names that may provide it. Debian's
/// `nvidia-kernel-dkms` renames the DKMS output to `nvidia-current`,
/// `nvidia-current-modeset`, `nvidia-current-drm` and `nvidia-current-uvm`;
/// Gentoo and NVIDIA's own builds use the upstream names.
fn module_candidates(module: &str) -> Vec<&'static str> {
match module {
"nvidia" => vec!["nvidia", "nvidia-current"],
"nvidia_modeset" => vec!["nvidia_modeset", "nvidia-current-modeset"],
"nvidia_uvm" => vec!["nvidia_uvm", "nvidia-current-uvm"],
"nvidia_drm" => vec!["nvidia_drm", "nvidia-current-drm"],
_ => vec![],
}
}
fn name_matches(file: &str, module: &str) -> bool {
file == format!("{module}.ko") || file.starts_with(&format!("{module}.ko."))
}
/// The mounted-module name actually found on disk.
fn find_module(names: &[String], module: &str) -> Option<String> {
for candidate in module_candidates(module) {
if names.iter().any(|n| name_matches(n, candidate)) {
return Some(format!("{candidate}.ko"));
}
}
None
}
/// Verify that `rootfs` bundles a complete NVIDIA payload for its live kernel.
///
/// Any missing or mismatched component is a hard error: the build fails rather
/// than shipping an image that cannot accelerate the GPU it advertises.
pub fn verify_live_nvidia(
rootfs: &Path,
driver_version: &str,
flavor: NvidiaModuleFlavor,
) -> Result<LiveNvidiaPayload> {
if !rootfs.is_dir() {
return Err(fail(format!(
"live rootfs {} does not exist",
rootfs.display()
)));
}
let kernel = kernel_version(rootfs)?;
// Kernel modules built for exactly this kernel.
let mut module_names = Vec::new();
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = rootfs.join(modules_root).join(&kernel);
if dir.is_dir() {
module_names.extend(names_under(&dir));
}
}
if module_names.is_empty() {
return Err(fail(format!(
"no modules found for kernel {kernel}; the driver was not built for the live kernel"
)));
}
let required = ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"];
let mut modules = Vec::new();
let mut missing = Vec::new();
for module in required {
match find_module(&module_names, module) {
Some(name) => modules.push(name),
None => missing.push(module),
}
}
if !missing.is_empty() {
return Err(fail(format!(
"kernel {kernel} is missing NVIDIA module(s): {}; expected a {flavor:?} build",
missing.join(", ")
)));
}
// Userspace: GLVND/GLX libraries, the management tool, and the Wayland/GBM
// EGL external-platform integration.
let lib_names = names_under(&rootfs.join("usr/lib"));
let mut userspace = Vec::new();
let mut missing_lib = Vec::new();
if let Some(name) = find_prefix(&lib_names, "libnvidia-glcore.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-glcore.so");
}
if let Some(name) = find_prefix(&lib_names, "libGLX_nvidia.so") {
userspace.push(name);
} else {
missing_lib.push("libGLX_nvidia.so");
}
if let Some(name) = find_prefix(&lib_names, "libnvidia-egl-gbm.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-egl-gbm.so");
}
if let Some(name) = find_prefix(&lib_names, "libnvidia-egl-wayland.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-egl-wayland.so");
}
if !missing_lib.is_empty() {
return Err(fail(format!(
"userspace NVIDIA libraries are missing: {}",
missing_lib.join(", ")
)));
}
if !exists_in_rootfs(rootfs, "usr/bin/nvidia-smi") {
return Err(fail(
"usr/bin/nvidia-smi is missing (nvidia-smi package not installed)".into(),
));
}
userspace.push("nvidia-smi".into());
// EGL external-platform manifests drive Wayland/GBM interop.
let egl_dir = rootfs.join("usr/share/egl/egl_external_platform.d");
let egl = names_under(&egl_dir);
for required_json in ["15_nvidia_gbm.json", "10_nvidia_wayland.json"] {
if !egl.iter().any(|n| n == required_json) {
return Err(fail(format!(
"EGL external-platform manifest {required_json} is missing under usr/share/egl/egl_external_platform.d"
)));
}
}
userspace.push("15_nvidia_gbm.json".into());
userspace.push("10_nvidia_wayland.json".into());
// Firmware (GSP) is mandatory for the module to initialise.
let firmware_names = names_under(&rootfs.join("usr/lib/firmware/nvidia"));
if firmware_names.is_empty() {
return Err(fail(
"no NVIDIA firmware found under usr/lib/firmware/nvidia (firmware-nvidia-gsp/graphics not installed)"
.into(),
));
}
let firmware: Vec<String> = firmware_names.into_iter().take(16).collect();
// The live-only load script and its unit must be present and gated so a
// machine without an NVIDIA GPU never records a failed unit. Nouveau must be
// blacklisted by the distro's own nvidia-kernel-common configuration.
if !exists_in_rootfs(rootfs, "usr/local/bin/phoebus-nvidia-load") {
return Err(fail(
"usr/local/bin/phoebus-nvidia-load is missing (gated driver load)".into(),
));
}
let mut has_nouveau_blacklist = false;
if let Ok(entries) = std::fs::read_dir(rootfs.join("etc/modprobe.d")) {
for entry in entries.flatten() {
let rel = format!("etc/modprobe.d/{}", entry.file_name().to_string_lossy());
if let Some(text) = read_in_rootfs(rootfs, &rel) {
if text.contains("blacklist nouveau") {
has_nouveau_blacklist = true;
}
}
}
}
if !has_nouveau_blacklist {
return Err(fail(
"no nouveau blacklist found under etc/modprobe.d; the selected branch could be preempted"
.into(),
));
}
Ok(LiveNvidiaPayload {
kernel_version: kernel,
driver_version: driver_version.to_string(),
flavor: flavor.as_str().to_string(),
modules,
userspace,
firmware,
})
}
/// Find the first name starting with `prefix`, returning a bounded label.
fn find_prefix(names: &[String], prefix: &str) -> Option<String> {
names
.iter()
.find(|n| n.starts_with(prefix))
.map(|_| prefix.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
fn touch(path: &Path) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"x").unwrap();
}
fn complete_rootfs(root: &Path) {
let kver = "6.16.7-amd64";
touch(&root.join(format!("boot/vmlinuz-{kver}")));
let modules = root.join(format!("lib/modules/{kver}"));
std::fs::create_dir_all(&modules).unwrap();
std::fs::write(modules.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&modules.join(format!("updates/dkms/{m}.ko")));
}
for lib in [
"libnvidia-glcore.so.550.163.01",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1.1.2",
"libnvidia-egl-wayland.so.1.1.21",
] {
touch(&root.join("usr/lib/x86_64-linux-gnu").join(lib));
}
touch(&root.join("usr/bin/nvidia-smi"));
touch(&root.join("usr/share/egl/egl_external_platform.d/15_nvidia_gbm.json"));
touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json"));
touch(&root.join("usr/lib/firmware/nvidia/550.163.01/gsp_ga10x.bin"));
touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
}
#[test]
fn complete_payload_is_accepted_and_recorded() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let payload =
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, "6.16.7-amd64");
assert_eq!(payload.modules.len(), 4);
let record = payload.record();
assert!(record.contains("driver_version=550.163.01"));
assert!(record.contains("flavor=proprietary"));
}
#[test]
fn missing_kernel_module_fails_the_build() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::remove_file(
dir.path()
.join("lib/modules/6.16.7-amd64/updates/dkms/nvidia_drm.ko"),
)
.unwrap();
let err = verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("nvidia_drm"), "{err}");
}
#[test]
fn missing_userspace_or_firmware_fails() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::remove_file(dir.path().join("usr/bin/nvidia-smi")).unwrap();
assert!(verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary).is_err());
let dir2 = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir2.path().join("usr/lib/firmware")).unwrap();
complete_rootfs(dir2.path());
// Remove the firmware tree.
std::fs::remove_dir_all(dir2.path().join("usr/lib/firmware/nvidia")).unwrap();
let err = verify_live_nvidia(dir2.path(), "550", NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("firmware"), "{err}");
}
#[test]
fn merged_usr_kernel_roots_are_deduplicated() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
// Debian is merged-usr: the same kernel tree is visible under both
// /lib/modules and /usr/lib/modules. That must not look like two
// kernels.
let kver = "6.16.7-amd64";
let dst = dir.path().join(format!("usr/lib/modules/{kver}"));
std::fs::create_dir_all(dst.parent().unwrap()).unwrap();
std::fs::create_dir_all(&dst).unwrap();
std::fs::write(dst.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&dst.join(format!("updates/dkms/{m}.ko")));
}
let payload =
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, kver);
}
#[test]
fn debian_renamed_modules_are_accepted_and_recorded() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let kver = "6.16.7-amd64";
let dkms = dir.path().join(format!("lib/modules/{kver}/updates/dkms"));
// Replace the upstream names with Debian's DKMS-renamed output.
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
std::fs::remove_file(dkms.join(format!("{m}.ko"))).unwrap();
}
for m in [
"nvidia-current",
"nvidia-current-modeset",
"nvidia-current-uvm",
"nvidia-current-drm",
] {
touch(&dkms.join(format!("{m}.ko.xz")));
}
let payload =
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert!(payload
.modules
.contains(&"nvidia-current-drm.ko".to_string()));
assert!(payload.modules.contains(&"nvidia-current.ko".to_string()));
}
#[test]
fn missing_kernel_is_reported() {
let dir = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir.path().join("lib/modules/6.16.7-amd64")).unwrap();
std::fs::write(dir.path().join("lib/modules/6.16.7-amd64/modules.dep"), b"").unwrap();
let err = verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("vmlinuz"), "{err}");
}
}

View file

@ -31,11 +31,21 @@ impl Level {
}
}
pub struct Logger {
use std::sync::Arc;
pub type LogListener = Arc<dyn Fn(&str) + Send + Sync>;
struct LoggerInner {
path: PathBuf,
file: Mutex<Option<File>>,
echo: bool,
redactor: Redactor,
listeners: Mutex<Vec<LogListener>>,
}
#[derive(Clone)]
pub struct Logger {
inner: Arc<LoggerInner>,
}
impl Logger {
@ -52,37 +62,57 @@ impl Logger {
.open(&path)
.ok();
Self {
inner: Arc::new(LoggerInner {
path,
file: Mutex::new(file),
echo,
redactor,
listeners: Mutex::new(Vec::new()),
}),
}
}
pub fn path(&self) -> &Path {
&self.path
&self.inner.path
}
pub fn redactor(&self) -> &Redactor {
&self.redactor
&self.inner.redactor
}
pub fn register_secret(&self, secret: &phoebus_core::SecretString) {
self.redactor.register(secret);
self.inner.redactor.register(secret);
}
pub fn add_listener(&self, listener: LogListener) {
if let Ok(mut listeners) = self.inner.listeners.lock() {
listeners.push(listener);
}
}
pub fn clear_listeners(&self) {
if let Ok(mut listeners) = self.inner.listeners.lock() {
listeners.clear();
}
}
fn write_line(&self, level: Level, message: &str) {
let message = self.redactor.redact(message);
let message = self.inner.redactor.redact(message);
let line = format!("{} [{}] {}\n", timestamp(), level.as_str(), message);
if let Ok(mut guard) = self.file.lock() {
if let Ok(mut guard) = self.inner.file.lock() {
if let Some(file) = guard.as_mut() {
let _ = file.write_all(line.as_bytes());
let _ = file.flush();
}
}
if self.echo {
if self.inner.echo {
let _ = std::io::stderr().write_all(line.as_bytes());
}
if let Ok(listeners) = self.inner.listeners.lock() {
for listener in listeners.iter() {
listener(&line);
}
}
}
pub fn debug(&self, message: impl AsRef<str>) {
@ -101,6 +131,26 @@ impl Logger {
self.write_line(Level::Info, &format!("--- {name} ---"));
}
/// Log the start of a command before running it.
pub fn command_start(
&self,
stage: &str,
operation: &str,
program: &str,
args: &[String],
stdin_hidden: bool,
) {
let mut line = format!("[{stage}] {operation} :: {program}");
for arg in args {
line.push(' ');
line.push_str(&shell_quote(arg));
}
if stdin_hidden {
line.push_str(" (stdin hidden)");
}
self.write_line(Level::Info, &line);
}
/// Log a command with its exit status and duration (all redacted).
pub fn command(
&self,
@ -127,14 +177,13 @@ impl Logger {
self.write_line(Level::Info, &line);
}
/// Append raw command output (stdout/stderr) to the log, redacted.
pub fn output(&self, bytes: &[u8]) {
if bytes.is_empty() {
/// Append streaming command output to the log in real time, redacted.
pub fn stream_output(&self, text: &str) {
if text.is_empty() {
return;
}
let text = String::from_utf8_lossy(bytes);
let redacted = self.redactor.redact(&text);
if let Ok(mut guard) = self.file.lock() {
let redacted = self.inner.redactor.redact(text);
if let Ok(mut guard) = self.inner.file.lock() {
if let Some(file) = guard.as_mut() {
let _ = file.write_all(redacted.as_bytes());
if !redacted.ends_with('\n') {
@ -143,9 +192,23 @@ impl Logger {
let _ = file.flush();
}
}
if self.echo {
if self.inner.echo {
let _ = std::io::stderr().write_all(redacted.as_bytes());
}
if let Ok(listeners) = self.inner.listeners.lock() {
for listener in listeners.iter() {
listener(&redacted);
}
}
}
/// Append raw command output (stdout/stderr) to the log, redacted.
pub fn output(&self, bytes: &[u8]) {
if bytes.is_empty() {
return;
}
let text = String::from_utf8_lossy(bytes);
self.stream_output(&text);
}
pub fn dry_run(&self, stage: &str, operation: &str, program: &str, args: &[String]) {

View file

@ -277,12 +277,21 @@ mod base64_lite {
// OpenCode protocol
// ---------------------------------------------------------------------------
/// A model offered by an OpenCode provider.
#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub struct ModelInfo {
pub id: String,
pub name: String,
#[serde(default)]
pub variants: Vec<String>,
}
/// A parsed model catalog entry. Never carries upstream credentials.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct ProviderEntry {
pub id: String,
pub name: String,
pub models: Vec<String>,
pub models: Vec<ModelInfo>,
pub connected: bool,
}
@ -308,7 +317,7 @@ impl Catalog {
pub fn has_model(&self, provider: &str, model: &str) -> bool {
self.providers
.iter()
.any(|p| p.id == provider && p.models.iter().any(|m| m == model))
.any(|p| p.id == provider && p.models.iter().any(|m| m.id == model))
}
pub fn default_model(&self, provider: &str) -> Option<&str> {
@ -316,7 +325,7 @@ impl Catalog {
.iter()
.find(|p| p.id == provider)
.and_then(|p| p.models.first())
.map(String::as_str)
.map(|m| m.id.as_str())
}
}
@ -340,6 +349,28 @@ struct RawProvider {
models: BTreeMap<String, serde_json::Value>,
}
#[derive(Debug, serde::Deserialize, Default)]
struct RawModel {
#[serde(default)]
id: String,
#[serde(default)]
name: String,
#[serde(default)]
variants: serde_json::Value,
}
fn extract_variants(val: &serde_json::Value) -> Vec<String> {
if let Some(map) = val.as_object() {
map.keys().cloned().collect()
} else if let Some(arr) = val.as_array() {
arr.iter()
.filter_map(|v| v.as_str().map(String::from))
.collect()
} else {
Vec::new()
}
}
impl ProviderCatalogBody {
fn into_catalog(self) -> Catalog {
let mut defaults = self.default;
@ -347,19 +378,48 @@ impl ProviderCatalogBody {
let mut providers: Vec<ProviderEntry> = self
.all
.into_iter()
.map(|p| ProviderEntry {
.map(|p| {
let models = p
.models
.into_iter()
.map(|(key, raw_val)| {
if let Ok(m) = serde_json::from_value::<RawModel>(raw_val) {
let id = if m.id.trim().is_empty() {
key
} else {
m.id.trim().to_string()
};
let name = if m.name.trim().is_empty() {
id.clone()
} else {
m.name.trim().to_string()
};
let mut variants = extract_variants(&m.variants);
variants.sort();
ModelInfo { id, name, variants }
} else {
ModelInfo {
id: key.clone(),
name: key,
variants: Vec::new(),
}
}
})
.collect();
ProviderEntry {
connected: connected.contains(&p.id),
id: p.id,
name: p.name,
models: p.models.into_keys().collect(),
models,
}
})
.collect();
for provider in &mut providers {
provider.models.sort_by(|a, b| a.id.cmp(&b.id));
if let Some(default) = defaults.remove(&provider.id) {
// Bubble the default model to the front so callers can pick a
// sensible default without a second request.
provider.models.sort();
if let Some(pos) = provider.models.iter().position(|m| m == &default) {
if let Some(pos) = provider.models.iter().position(|m| m.id == default) {
let model = provider.models.remove(pos);
provider.models.insert(0, model);
}
@ -485,6 +545,7 @@ pub struct OpenCodeClient<'a> {
auth: Option<SecretString>,
provider: String,
model: String,
variant: Option<String>,
timeout: Duration,
max_body: u64,
resolve: Option<(String, u16, IpAddr)>,
@ -503,6 +564,7 @@ impl<'a> OpenCodeClient<'a> {
auth: None,
provider: provider.into(),
model: model.into(),
variant: None,
timeout: Duration::from_secs(120),
max_body: 4 * 1024 * 1024,
resolve: None,
@ -514,6 +576,11 @@ impl<'a> OpenCodeClient<'a> {
self
}
pub fn with_variant(mut self, variant: impl Into<String>) -> Self {
self.variant = Some(variant.into());
self
}
pub fn with_timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
@ -609,9 +676,19 @@ impl<'a> OpenCodeClient<'a> {
system: &str,
user: &str,
) -> Result<AssistantReply, AiError> {
let mut model_val = serde_json::json!({
"providerID": self.provider,
"modelID": self.model,
});
if let Some(variant) = &self.variant {
let v = variant.trim();
if !v.is_empty() && v != "default" {
model_val["variant"] = serde_json::Value::String(v.to_string());
}
}
let body = serde_json::json!({
"system": system,
"model": { "providerID": self.provider, "modelID": self.model },
"model": model_val,
"tools": disabled_tools(),
"parts": [{ "type": "text", "text": user }],
})
@ -673,10 +750,6 @@ fn disabled_tools() -> serde_json::Value {
})
}
/// A `ModelTransport` that adapts an OpenAI-shaped chat request to the OpenCode
/// session API, so `complete_proposal`/`complete_plan` and the whole review
/// pipeline are reused unchanged. The returned body is OpenAI-shaped because
/// the shared `extract_content` consumes it.
/// Adapts the OpenAI-shaped chat request that `complete_proposal` /
/// `complete_plan` build to the OpenCode session API. It borrows the caller's
/// [`Exec`] so logging, redaction and dry-run all apply, and returns an
@ -687,6 +760,7 @@ pub struct ExecOpenCodeTransport<'a> {
base: String,
provider: String,
model: String,
variant: Option<String>,
auth: Option<SecretString>,
timeout: Duration,
max_body: u64,
@ -705,6 +779,7 @@ impl<'a> ExecOpenCodeTransport<'a> {
base: base.into(),
provider: provider.into(),
model: model.into(),
variant: None,
auth: None,
timeout: Duration::from_secs(120),
max_body: 4 * 1024 * 1024,
@ -717,6 +792,11 @@ impl<'a> ExecOpenCodeTransport<'a> {
self
}
pub fn with_variant(mut self, variant: impl Into<String>) -> Self {
self.variant = Some(variant.into());
self
}
pub fn with_resolve(mut self, resolve: Option<(String, u16, IpAddr)>) -> Self {
self.resolve = resolve;
self
@ -776,11 +856,14 @@ impl ModelTransport for ExecOpenCodeTransport<'_> {
.clone()
.or(Some((endpoint.host.clone(), endpoint.port, target.ip())));
let http = CurlHttpClient::new(self.exec);
let client = OpenCodeClient::new(&http, &self.base, &self.provider, &self.model)
let mut client = OpenCodeClient::new(&http, &self.base, &self.provider, &self.model)
.with_auth(self.auth.clone())
.with_timeout(self.timeout)
.with_max_body(self.max_body)
.with_resolve(resolve);
if let Some(variant) = &self.variant {
client = client.with_variant(variant.clone());
}
let reply = client.one_shot(&system, &user)?;
Ok(openai_reply(&reply.content))
}
@ -921,7 +1004,8 @@ mod tests {
.unwrap();
assert!(ds.connected);
// The default model is bubbled to the front.
assert_eq!(ds.models, vec!["a", "b"]);
let ids: Vec<&str> = ds.models.iter().map(|m| m.id.as_str()).collect();
assert_eq!(ids, vec!["a", "b"]);
assert!(catalog.has_model("deepseek", "a"));
assert!(!catalog.has_model("deepseek", "zzz"));
}

View file

@ -24,9 +24,13 @@ pub fn write_config(exec: &Exec, config: &InstallConfig, hardware: &HardwareRepo
)?;
root.write(
"etc/portage/package.use/phoebus",
sysgen::package_use(config),
sysgen::package_use(config, hardware),
)?;
let mut keywords = sysgen::accept_keywords_policy();
let mask = sysgen::package_mask(config, hardware);
if !mask.trim().is_empty() {
root.write("etc/portage/package.mask/phoebus", mask)?;
}
let mut keywords = sysgen::accept_keywords_policy(hardware);
if sysgen::uses_guru(config) {
// The Mango + DankMaterialShell stack lives in GURU and is `~amd64`.
// The keyword set is scoped to those packages and the GURU-only

View file

@ -107,6 +107,46 @@ fn classify_gpu(line: &str) -> GpuVendor {
}
}
/// Extract `(vendor:device, pci_address)` from an `lspci -nn` line.
///
/// The numeric vendor:device pair is the last `[vvvv:dddd]` tag; the class
/// code (`[0300]`) has no colon and is ignored. The PCI address is the first
/// whitespace-delimited field (`01:00.0`).
fn parse_lspci_identity(line: &str) -> (Option<String>, Option<String>) {
let mut pair = None;
let bytes = line.as_bytes();
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'[' {
if let Some(rel) = line[i + 1..].find(']') {
let inner = &line[i + 1..i + 1 + rel];
if let Some((vendor, device)) = inner.split_once(':') {
let device = &device[..device.len().min(4)];
if vendor.len() == 4
&& device.len() == 4
&& vendor.chars().all(|c| c.is_ascii_hexdigit())
&& device.chars().all(|c| c.is_ascii_hexdigit())
{
pair = Some(format!(
"{}:{}",
vendor.to_ascii_lowercase(),
device.to_ascii_lowercase()
));
}
}
i += 1 + rel;
}
}
i += 1;
}
let address = line
.split_whitespace()
.next()
.filter(|t| t.contains(':') && t.contains('.'))
.map(str::to_string);
(pair, address)
}
fn lspci_filter(runner: &dyn ProcessRunner, pattern: &str) -> Vec<String> {
let out = capture(runner, "lspci", &["-nn"]);
out.lines()
@ -128,9 +168,14 @@ pub fn probe_hardware(runner: &dyn ProcessRunner) -> HardwareReport {
);
let gpus = gpu_lines
.iter()
.map(|l| GpuInfo {
.map(|l| {
let (pci_id, pci_address) = parse_lspci_identity(l);
GpuInfo {
vendor: classify_gpu(l),
description: l.clone(),
pci_id,
pci_address,
}
})
.collect();
@ -494,4 +539,22 @@ mod tests {
assert_eq!(disk_kind("dm-0", "/dev/dm-0"), DiskKind::DeviceMapper);
assert_eq!(disk_kind("vda", "/dev/vda"), DiskKind::Physical);
}
#[test]
fn lspci_identity_extracts_the_vendor_device_pair() {
let nvidia = "01:00.0 VGA compatible controller [0300]: NVIDIA Corporation GA104 [GeForce RTX 3070] [10de:2482] (rev a1)";
let (pair, address) = parse_lspci_identity(nvidia);
assert_eq!(pair.as_deref(), Some("10de:2482"));
assert_eq!(address.as_deref(), Some("01:00.0"));
assert_eq!(classify_gpu(nvidia), GpuVendor::Nvidia);
let intel = "00:02.0 VGA compatible controller [0300]: Intel Corporation Device [8086:9a60] (rev 01)";
assert_eq!(parse_lspci_identity(intel).0.as_deref(), Some("8086:9a60"));
// A line without a numeric pair must not fabricate one.
assert_eq!(
parse_lspci_identity("00:00.0 Host bridge: Intel"),
(None, Some("00:00.0".into()))
);
}
}

View file

@ -199,7 +199,7 @@ fn write_response(
fn test_exec() -> Exec {
let dir = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(dir.join("opencode.log"), Redactor::new(), false);
Exec::new(Box::new(RealRunner), logger, false, dir.clone(), dir)
Exec::new(Box::new(RealRunner::new()), logger, false, dir.clone(), dir)
}
fn base(port: u16) -> String {

View file

@ -69,7 +69,7 @@ fn exec() -> Exec {
phoebus_core::Redactor::new(),
false,
);
Exec::new(Box::new(RealRunner), logger, false, dir.clone(), dir)
Exec::new(Box::new(RealRunner::new()), logger, false, dir.clone(), dir)
}
#[test]

View file

@ -163,7 +163,7 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
}
let logger = Logger::open(state_dir.join("sys.log"), Redactor::new(), false);
let exec = Exec::new(
Box::new(RealRunner),
Box::new(RealRunner::new()),
logger,
false,
cli.root.clone(),

View file

@ -21,7 +21,6 @@ use phoebus_ai::provider::{ModelTransport, ProviderKind, SystemFacts};
use phoebus_core::{AiBackend, InstallConfig, InstallStep, SecretString};
use phoebus_executor::ai::CurlTransport;
use phoebus_executor::auth::{authorize, Confirmation};
use phoebus_executor::opencode_client::ExecOpenCodeTransport;
use phoebus_executor::{Exec, Result as ExecResult};
use serde::Deserialize;
@ -95,13 +94,13 @@ impl Confirmation for BridgeConfirm {
/// Writes progress events for the real backend stages and records the coarse
/// disk-change phase so a failure can be explained accurately.
struct JsonObserver<'a> {
out: &'a mut dyn Write,
struct JsonObserver {
tx: std::sync::mpsc::Sender<Value>,
id: u64,
phase: std::rc::Rc<std::cell::Cell<DiskPhase>>,
}
impl JsonObserver<'_> {
impl JsonObserver {
fn emit(&mut self, step: InstallStep, status: &str, error: Option<&str>) {
let (category, label) = step_meta(step);
let event = json!({
@ -114,11 +113,11 @@ impl JsonObserver<'_> {
"status": status,
"error": error,
});
let _ = write_json(self.out, &event);
let _ = self.tx.send(event);
}
}
impl InstallObserver for JsonObserver<'_> {
impl InstallObserver for JsonObserver {
fn stage_started(&mut self, step: InstallStep) {
if step == InstallStep::StoragePrepare {
self.phase.set(DiskPhase::InStorage);
@ -151,6 +150,7 @@ fn step_meta(step: InstallStep) -> (&'static str, &'static str) {
InstallStep::PortageConfigure => ("download", "Configuring and syncing Portage"),
InstallStep::PackagesBase => ("compile", "Installing base packages"),
InstallStep::KernelInstall => ("compile", "Building and installing the kernel"),
InstallStep::NvidiaDrivers => ("compile", "Installing the NVIDIA driver"),
InstallStep::BootInstall => ("configure", "Installing the boot loader"),
InstallStep::UsersConfigure => ("configure", "Creating your account"),
InstallStep::ServicesConfigure => ("configure", "Enabling system services"),
@ -227,7 +227,7 @@ impl Bridge {
}
/// Parse and dispatch one request line, writing events/responses to `out`.
pub fn handle_line(&mut self, line: &str, out: &mut dyn Write) -> io::Result<()> {
pub fn handle_line(&mut self, line: &str, out: &mut (dyn Write + Send)) -> io::Result<()> {
let line = line.trim();
if line.is_empty() {
return Ok(());
@ -253,7 +253,7 @@ impl Bridge {
self.dispatch(request, out)
}
fn dispatch(&mut self, request: Request, out: &mut dyn Write) -> io::Result<()> {
fn dispatch(&mut self, request: Request, out: &mut (dyn Write + Send)) -> io::Result<()> {
let id = request.id;
let op = request.op.clone();
let result = match request.op.as_str() {
@ -420,12 +420,30 @@ impl Bridge {
|p| json!({ "id": p.id, "name": p.name, "connected": p.connected }),
)
.collect();
let models = catalog
let models: Vec<Value> = catalog
.providers
.iter()
.find(|p| p.id == provider)
.or_else(|| catalog.providers.iter().find(|p| !p.models.is_empty()))
.map(|p| p.models.clone())
.map(|p| {
p.models
.iter()
.map(|m| {
let label = if m.name != m.id {
format!("{} ({})", m.name, m.id)
} else {
m.name.clone()
};
json!({
"id": m.id,
"name": m.name,
"label": label,
"value": m.id,
"variants": m.variants,
})
})
.collect()
})
.unwrap_or_default();
Ok(json!({
"backend": "opencode",
@ -455,7 +473,18 @@ impl Bridge {
let http = CurlHttpClient::new(&self.installer.exec);
match http.request(&request) {
Ok(response) if response.is_success() => {
let models = parse_model_ids(&response.body);
let models: Vec<Value> = parse_model_ids(&response.body)
.into_iter()
.map(|id| {
json!({
"id": id,
"name": id,
"label": id,
"value": id,
"variants": ["default"],
})
})
.collect();
Ok(json!({
"backend": "direct",
"providers": [ { "id": provider.as_str(), "name": provider.as_str(), "connected": true } ],
@ -695,7 +724,7 @@ impl Bridge {
let redactor = self.installer.exec.redactor();
let (kind, endpoint, model, label) = match backend {
AiBackend::OpenCode => {
let (server, provider, model) = opencode_parts(&self.installer.config)?;
let (server, provider, model, _) = opencode_parts(&self.installer.config)?;
(ProviderKind::Local, server, model, provider)
}
AiBackend::Direct => {
@ -723,10 +752,11 @@ impl Bridge {
.map_err(|e| format!("could not build the test request: {e}"))?;
let response = match backend {
AiBackend::OpenCode => {
let (server, provider, model) = opencode_parts(&self.installer.config)?;
let transport =
ExecOpenCodeTransport::new(&self.installer.exec, server, provider, model)
.with_auth(self.opencode_password.clone());
let transport = opencode_transport(
&self.installer.exec,
&self.installer.config,
self.opencode_password.clone(),
)?;
transport.send(kind, &endpoint, &body)
}
AiBackend::Direct => {
@ -781,7 +811,12 @@ impl Bridge {
Ok(json!({ "approved": true, "plan_digest": digest }))
}
fn start_install(&mut self, id: u64, request: &Request, out: &mut dyn Write) -> io::Result<()> {
fn start_install(
&mut self,
id: u64,
request: &Request,
out: &mut (dyn Write + Send),
) -> io::Result<()> {
let result = self.run_install(id, request, out);
match result {
Ok(data) => write_json(
@ -799,7 +834,7 @@ impl Bridge {
&mut self,
id: u64,
request: &Request,
out: &mut dyn Write,
out: &mut (dyn Write + Send),
) -> Result<Value, String> {
if self.installing {
return Err("an installation is already in progress".into());
@ -864,8 +899,23 @@ impl Bridge {
let auth = authorize(&confirm, &preview, "Start the installation now?")
.map_err(|e| self.installer.exec.redactor().redact(&e.to_string()))?;
let (tx, rx) = std::sync::mpsc::channel::<Value>();
let tx_log = tx.clone();
let log_listener = std::sync::Arc::new(move |chunk: &str| {
for line in chunk.lines() {
let line = line.trim();
if !line.is_empty() {
let _ = tx_log.send(json!({
"event": "log",
"line": line,
}));
}
}
});
self.installer.exec.logger.add_listener(log_listener);
let mut observer = JsonObserver {
out,
tx: tx.clone(),
id,
phase: self.phase.clone(),
};
@ -875,13 +925,29 @@ impl Bridge {
self.approved_digest = None;
self.validated_ai = None;
self.installing = true;
let outcome = self.installer.install_observed(
let outcome = std::thread::scope(|s| {
s.spawn(move || {
while let Ok(event) = rx.recv() {
let _ = write_json(out, &event);
}
});
let res = self.installer.install_observed(
&auth,
self.luks.as_ref(),
self.user_password.as_ref(),
self.root_password.as_ref(),
&mut observer,
);
// Drop the observer before the scope joins: its `tx` clone is the
// last sender, and the writer thread only exits when every sender
// is gone. Keeping it alive past the closure deadlocks the join.
drop(observer);
self.installer.exec.logger.clear_listeners();
drop(tx);
res
});
self.installing = false;
match outcome {
@ -1400,11 +1466,12 @@ fn config_digest(config: &InstallConfig) -> String {
format!("{:x}", hasher.finalize())
}
/// The OpenCode server URL, provider id and model id, validated for presence.
fn opencode_parts(config: &InstallConfig) -> Result<(String, String, String), String> {
/// The OpenCode server URL, provider id, model id and variant, validated for presence.
fn opencode_parts(config: &InstallConfig) -> Result<(String, String, String, String), String> {
let server = config.ai.opencode_server.trim().to_string();
let provider = config.ai.opencode_provider.trim().to_string();
let model = config.ai.opencode_model.trim().to_string();
let variant = config.ai.opencode_variant().to_string();
if server.is_empty() {
return Err("OpenCode requires a server URL".into());
}
@ -1417,7 +1484,7 @@ fn opencode_parts(config: &InstallConfig) -> Result<(String, String, String), St
// Fail fast on an unsafe endpoint, before any request is attempted.
phoebus_executor::opencode_server::Endpoint::parse(&server)
.map_err(|e| format!("invalid OpenCode endpoint: {e}"))?;
Ok((server, provider, model))
Ok((server, provider, model, variant))
}
/// Time zones offered by the live system, from the zoneinfo database.
@ -1598,13 +1665,15 @@ fn opencode_transport<'a>(
config: &InstallConfig,
password: Option<SecretString>,
) -> Result<phoebus_executor::opencode_client::ExecOpenCodeTransport<'a>, String> {
let (server, provider, model) = opencode_parts(config)?;
Ok(
phoebus_executor::opencode_client::ExecOpenCodeTransport::new(
let (server, provider, model, variant) = opencode_parts(config)?;
let mut transport = phoebus_executor::opencode_client::ExecOpenCodeTransport::new(
exec, server, provider, model,
)
.with_auth(password),
)
.with_auth(password);
if !variant.is_empty() && variant != "default" {
transport = transport.with_variant(variant);
}
Ok(transport)
}
#[allow(clippy::too_many_arguments)]
@ -1660,7 +1729,7 @@ fn review_opencode(
facts: SystemFacts,
transport: &dyn ModelTransport,
) -> Result<Value, String> {
let (server, provider_id, model) = opencode_parts(config)?;
let (server, provider_id, model, _variant) = opencode_parts(config)?;
finish_review(
config,
redactor,
@ -1690,6 +1759,7 @@ fn ai_digest(config: &InstallConfig) -> String {
ai.opencode_server.as_str(),
ai.opencode_provider.as_str(),
ai.opencode_model.as_str(),
ai.opencode_variant.as_str(),
] {
hasher.update(field.as_bytes());
hasher.update([0u8]);
@ -1790,8 +1860,12 @@ pub fn run_stdio() -> io::Result<()> {
phoebus_core::Redactor::new(),
false,
);
let logger_clone = logger.clone();
let runner = phoebus_executor::RealRunner::with_sink(std::sync::Arc::new(move |text: &str| {
logger_clone.stream_output(text);
}));
let exec = Exec::new(
Box::new(phoebus_executor::RealRunner),
Box::new(runner),
logger,
config.runtime.dry_run,
config.storage.install_root.clone(),
@ -1800,8 +1874,7 @@ pub fn run_stdio() -> io::Result<()> {
let mut bridge = Bridge::new(config, exec);
let stdin = io::stdin();
let stdout = io::stdout();
let mut out = stdout.lock();
let mut out = io::stdout();
for line in stdin.lock().lines() {
let line = line?;
bridge.handle_line(&line, &mut out)?;

View file

@ -116,6 +116,24 @@ struct Cli {
#[arg(long, value_name = "NAME", hide = true)]
emit_asset: Option<String>,
/// Verify that an assembled live rootfs bundles a complete NVIDIA payload
/// (kernel modules for its kernel, userspace, Wayland/EGL/GBM integration
/// and firmware), write the version record to /etc/phoebus/nvidia, and exit.
/// Fails (nonzero) on any missing or mismatched component. Used by the live
/// ISO build, including cached-rootfs builds.
#[arg(long, value_name = "ROOTFS", hide = true)]
verify_live_nvidia: Option<PathBuf>,
/// The NVIDIA driver version bundled in the live image (recorded by
/// `--verify-live-nvidia`).
#[arg(long, value_name = "VERSION", hide = true)]
nvidia_version: Option<String>,
/// The NVIDIA kernel-module flavor bundled in the live image:
/// `proprietary` (default) or `open`.
#[arg(long, value_name = "FLAVOR", hide = true)]
nvidia_flavor: Option<String>,
/// Speak the typed JSON protocol used by the graphical installer frontend
/// (stdin/stdout). Not intended for direct interactive use.
#[arg(long, hide = true)]
@ -154,6 +172,46 @@ struct Cli {
ai_backend: Option<String>,
}
/// Verify the live rootfs's bundled NVIDIA payload and write its record. This
/// is a build-time gate: a missing module, library or firmware file makes the
/// live ISO build fail rather than shipping an image that cannot accelerate the
/// GPU it advertises. It is independent of any cached-rootfs path.
fn verify_live_nvidia_command(cli: &Cli, rootfs: &std::path::Path) -> ExitCode {
use phoebus_core::NvidiaModuleFlavor;
let version = cli.nvidia_version.clone().unwrap_or_default();
if version.trim().is_empty() {
eprintln!("--verify-live-nvidia requires --nvidia-version");
return ExitCode::FAILURE;
}
let flavor = match cli.nvidia_flavor.as_deref().unwrap_or("proprietary") {
"open" => NvidiaModuleFlavor::Open,
"proprietary" => NvidiaModuleFlavor::Proprietary,
other => {
eprintln!("unknown --nvidia-flavor `{other}` (expected `proprietary` or `open`)");
return ExitCode::FAILURE;
}
};
match phoebus_executor::live_nvidia::verify_live_nvidia(rootfs, &version, flavor) {
Ok(payload) => {
let dir = rootfs.join("etc/phoebus");
if let Err(e) = std::fs::create_dir_all(&dir) {
eprintln!("cannot create {}: {e}", dir.display());
return ExitCode::FAILURE;
}
if let Err(e) = std::fs::write(dir.join("nvidia"), payload.record()) {
eprintln!("cannot write the NVIDIA record: {e}");
return ExitCode::FAILURE;
}
println!("{}", payload.render());
ExitCode::SUCCESS
}
Err(e) => {
eprintln!("NVIDIA live payload verification failed: {e}");
ExitCode::FAILURE
}
}
}
struct TerminalConfirm;
impl Confirmation for TerminalConfirm {
@ -193,7 +251,7 @@ fn opencode_exec() -> Exec {
let dir = std::env::temp_dir().join("phoebus-opencode-cli");
let _ = std::fs::create_dir_all(&dir);
let logger = Logger::open(dir.join("opencode.log"), Redactor::new(), false);
Exec::new(Box::new(RealRunner), logger, false, dir.clone(), dir)
Exec::new(Box::new(RealRunner::new()), logger, false, dir.clone(), dir)
}
/// Probe an OpenCode server (`validate_inference = false`) or obtain and
@ -487,6 +545,10 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
};
}
if let Some(rootfs) = &cli.verify_live_nvidia {
return Ok(verify_live_nvidia_command(&cli, rootfs));
}
let mut config = if let Some(path) = &cli.config {
InstallConfig::load_from_path(path)?
} else {
@ -566,8 +628,12 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
PathBuf::from(&config.storage.install_root)
};
let logger_clone = logger.clone();
let runner = RealRunner::with_sink(std::sync::Arc::new(move |text: &str| {
logger_clone.stream_output(text);
}));
let exec = Exec::new(
Box::new(RealRunner),
Box::new(runner),
logger,
config.runtime.dry_run,
root,

View file

@ -234,6 +234,7 @@ impl Installer {
PortageConfigure => self.portage_configure(),
PackagesBase => self.packages_base(),
KernelInstall => self.kernel_install(),
NvidiaDrivers => self.nvidia_drivers(),
BootInstall => self.boot_install(),
UsersConfigure => self.users_configure(user_password, root_password),
ServicesConfigure => self.services_configure(),
@ -467,7 +468,7 @@ impl Installer {
}
kernel::write_profile(&self.exec, &self.config)?;
boot::write_install_conf(&self.exec)?;
boot::write_dracut_conf(&self.exec, &self.config)?;
boot::write_dracut_conf(&self.exec, &self.config, &self.hardware)?;
let root_source = storage::root_source_ref(&self.exec, &self.config, &self.state);
kernel::write_cmdline(
&self.exec,
@ -490,6 +491,80 @@ impl Installer {
result
}
/// Install the NVIDIA accelerated driver selected from the PCI device IDs.
///
/// A no-op on machines with no supported NVIDIA GPU (nouveau fallback). The
/// initramfs generated during `KernelInstall` predates the module build, so
/// it is regenerated here to embed the modules and their firmware. A failure
/// fails the install: it must never be reported as successful NVIDIA
/// support.
fn nvidia_drivers(&self) -> Result<()> {
let plan = phoebus_core::nvidia::NvidiaPlan::for_hardware(&self.hardware);
if !plan.supported {
self.exec
.logger
.info(format!("NVIDIA: no driver installed; {}", plan.reason));
return Ok(());
}
if self.exec.dry_run {
self.exec.logger.info(format!(
"[dry-run] would install {} ({}) and regenerate the initramfs",
phoebus_core::nvidia::GENTOO_ATOM,
plan.branch
));
return Ok(());
}
self.exec.mount_chroot()?;
let result: Result<()> = (|| {
let packages = vec![phoebus_core::nvidia::GENTOO_ATOM.to_string()];
portage::emerge(
&self.exec,
std::path::Path::new(&self.exec.root),
&packages,
&self.engine,
&self.policy_ctx,
)?;
boot::generate_entries(&self.exec)?;
self.record_nvidia(&plan)?;
Ok(())
})();
self.exec.umount_chroot()?;
if result.is_ok() {
self.harvest_compile_times();
}
result
}
/// Persist the resolved driver decision in the target so post-install
/// inspection and recovery know exactly what was selected.
fn record_nvidia(&self, plan: &phoebus_core::nvidia::NvidiaPlan) -> Result<()> {
let mut text = String::new();
text.push_str("# Resolved NVIDIA accelerated driver (generated by the installer).\n");
text.push_str(&format!("branch={}\n", plan.branch));
text.push_str(&format!(
"flavor={}\n",
plan.flavor.map(|f| f.as_str()).unwrap_or("none")
));
text.push_str(&format!(
"generation={}\n",
plan.generation.map(|g| g.as_str()).unwrap_or("none")
));
text.push_str("package=x11-drivers/nvidia-drivers\n");
for device in &plan.devices {
text.push_str(&format!(
"device={} {}\n",
device.pci_id,
device.generation.map(|g| g.as_str()).unwrap_or("unknown")
));
}
text.push_str(&format!("reason={}\n", plan.reason));
self.exec.target().write("etc/phoebus/nvidia", text)?;
self.exec
.logger
.info("recorded the NVIDIA driver selection in /etc/phoebus/nvidia");
Ok(())
}
fn boot_install(&self) -> Result<()> {
if self.exec.dry_run {
self.exec

View file

@ -62,6 +62,76 @@ fn every_bash_cli_mode_has_a_rust_flag() {
}
}
#[test]
fn verify_live_nvidia_accepts_a_complete_payload_and_rejects_an_incomplete_one() {
fn touch(path: &std::path::Path) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"x").unwrap();
}
fn complete(root: &std::path::Path) {
let kver = "6.16.7-amd64";
touch(&root.join(format!("boot/vmlinuz-{kver}")));
let modules = root.join(format!("lib/modules/{kver}"));
std::fs::create_dir_all(&modules).unwrap();
std::fs::write(modules.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&modules.join(format!("updates/dkms/{m}.ko")));
}
for lib in [
"libnvidia-glcore.so.550",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1",
"libnvidia-egl-wayland.so.1",
] {
touch(&root.join("usr/lib/x86_64-linux-gnu").join(lib));
}
touch(&root.join("usr/bin/nvidia-smi"));
touch(&root.join("usr/share/egl/egl_external_platform.d/15_nvidia_gbm.json"));
touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json"));
touch(&root.join("usr/lib/firmware/nvidia/550.163.01/gsp.bin"));
touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
}
let run = |root: &std::path::Path| {
Command::new(env!("CARGO_BIN_EXE_phoebus-installer"))
.arg("--verify-live-nvidia")
.arg(root)
.args([
"--nvidia-version",
"550.163.01",
"--nvidia-flavor",
"proprietary",
])
.output()
.expect("run --verify-live-nvidia")
};
let dir = tempfile::tempdir().unwrap();
complete(dir.path());
let out = run(dir.path());
assert!(
out.status.success(),
"{}",
String::from_utf8_lossy(&out.stderr)
);
let record = std::fs::read_to_string(dir.path().join("etc/phoebus/nvidia")).unwrap();
assert!(record.contains("driver_version=550.163.01"));
assert!(record.contains("kernel_version=6.16.7-amd64"));
let broken = tempfile::tempdir().unwrap();
complete(broken.path());
std::fs::remove_file(broken.path().join("usr/bin/nvidia-smi")).unwrap();
let out = run(broken.path());
assert!(
!out.status.success(),
"a missing component must fail the gate"
);
assert_eq!(out.status.code(), Some(1));
}
#[test]
fn relocated_opencode_manifest_is_pinned_and_complete() {
let path = manifest_path();

View file

@ -22,6 +22,50 @@ fn read(rel: &str) -> String {
std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display()))
}
#[test]
fn live_build_bundles_and_verifies_the_nvidia_payload() {
let list = read("installer/live/live-packages.list");
for required in [
"nvidia-driver",
"nvidia-kernel-dkms",
"firmware-nvidia-gsp",
"firmware-nvidia-graphics",
"libnvidia-egl-gbm1",
"libnvidia-egl-wayland1",
"linux-headers-amd64",
"dkms",
] {
assert!(
list.lines().any(|l| l.trim() == required),
"live package list is missing {required}"
);
}
let build = read("installer/live/build.sh");
// The signed non-free components are enabled for the NVIDIA packages.
assert!(build.contains("main,contrib,non-free,non-free-firmware"));
// The payload is verified on every build, including a cached rootfs, and a
// missing/mismatched component fails the build.
assert!(build.contains("--verify-live-nvidia"));
assert!(build.contains("--nvidia-version"));
assert!(build.contains("etc/phoebus/nvidia"));
// Module build happens for the exact live kernel in the hook.
let hook = read("installer/live/livefs-hook.sh");
assert!(hook.contains("dkms autoinstall"));
assert!(hook.contains("nvidia_drm"));
// The live kernel is pinned to Debian stable, where the 550 driver builds;
// testing's 7.2 kernel removed strncpy and breaks nvidia-kernel-dkms.
assert!(build.contains("trixie"));
assert!(build.contains("linux-kbuild-"));
assert!(build.contains("--setup-hook"));
// Nouveau blacklisting/module options come from nvidia-kernel-common; the
// unconditional modules-load entry is removed in favour of the gated unit.
assert!(build.contains("nvidia-kernel-common"));
assert!(build.contains("modules-load.d/nvidia.conf"));
// A documented fail-safe entry disables NVIDIA for that boot.
assert!(build.contains("nomodeset"));
assert!(build.contains("modprobe.blacklist=nvidia"));
}
#[test]
fn live_package_list_carries_the_desktop_stack() {
let list = read("installer/live/live-packages.list");

View file

@ -87,6 +87,58 @@ launcher is missing; it never silently emits a text-only ISO.
passwordless `sudo`.
- The `phoebus-dwl` session remains selectable as a fallback.
## NVIDIA accelerated graphics
The live medium bundles NVIDIA's accelerated driver so a supported GPU boots
into Mango + DankMaterialShell accelerated without downloading or compiling
anything at boot.
- The driver comes from the signed Debian archive's `contrib`, `non-free` and
`non-free-firmware` components (enabled in `build.sh`). The `testing` suite
currently ships branch **550.163.01**; its proprietary kernel modules cover
Maxwell through Ada/Hopper. **Blackwell is not supported by this branch**; on
a Blackwell GPU the live medium falls back to the in-tree `nouveau` driver.
- The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Debian
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 removed from the package list and `build.sh`
resolves and installs the exact stable kernel, headers and kbuild packages
from `trixie` (pinned in an apt setup hook). The rest of the rootfs stays on
testing for wlroots 0.20 / scenefx 0.5 / Quickshell.
- `livefs-hook.sh` builds the DKMS modules against that exact kernel and
**fails the build** if any of the four modules is missing. Debian's
`nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
accept either that naming or the upstream names.
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`, which checks
the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the
EGL external-platform manifests, the GSP firmware, the gated load script and
the nouveau blacklist. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without
the payload. The bundled driver version, module flavor and kernel are recorded
in `/etc/phoebus/nvidia` on the medium.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of the live-only `phoebus-nvidia.service`, which runs the gated
`phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device
is present**, so systems without one keep nouveau/virtio and record no failed
unit.
- The GRUB **fail-safe graphics** entry disables modesetting
(`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the
documented recovery path when driver initialisation misbehaves. Use
`phoebus-gpu-report` for read-only diagnostics (PCI devices, loaded modules,
`nvidia_drm` modeset, `nvidia-smi`, recent kernel messages).
- The installed Gentoo target is unaffected: it uses Portage
(`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI
device IDs — open kernel modules for Turing and newer, the proprietary branch
for Maxwell/Pascal/Volta, and nouveau for older cards. See
`docs/adr/0012-nvidia-driver-policy.md`.
The NVIDIA live payload was built and verified in a minimal `mmdebstrap` rootfs
(driver 550.163.01, kernel 6.12.107+deb13-amd64, modules `nvidia-current*`).
Actual NVIDIA acceleration is **not verified** (no NVIDIA GPU on the build
host; see `docs/STATUS.md`).
## Verification
`installer/tests/vm/gui-driver.py` drives the graphical ISO in a disposable

View file

@ -104,6 +104,7 @@ assets=(
wayland-session-mango wayland-session-dwl
waybar-config waybar-style greetd-live
brand-emblem brand-wordmark brand-wallpaper brand-tokens
nvidia-load nvidia-service gpu-report
)
for name in "${assets[@]}"; do
"$release_dir/phoebus-installer" --emit-asset "$name" > "$work/assets/$name" || {
@ -132,6 +133,51 @@ fi
include_csv="$(grep -vE '^[[:space:]]*(#|$)' "$here/live-packages.list" | paste -sd, -)"
[[ -n "$include_csv" ]] || { echo "live-packages.list is empty" >&2; exit 1; }
# The live kernel is pinned to Debian **stable** (trixie), not testing. Debian
# testing's current kernel (7.2) removed the `strncpy` declaration the 550
# NVIDIA driver still uses, so `nvidia-kernel-dkms` cannot build against it.
# Stable is also the project's "stability over novelty" choice, and its 6.12 LTS
# kernel is exactly what the base live ISO already ships. The rootfs otherwise
# stays on testing for wlroots 0.20 / scenefx 0.5 / Quickshell.
say "resolve the stable live kernel"
trixie_packages() {
curl -fsS "http://deb.debian.org/debian/dists/trixie/main/binary-amd64/Packages.gz" | zcat
}
trixie_meta_dep() { # meta-package -> the exact versioned dependency atom
trixie_packages | awk -v p="$1" 'BEGIN{RS=""} $0 ~ "^Package: "p"\\n" {print; exit}' \
| awk '/^Depends:/{for(i=1;i<=NF;i++){gsub(/[(),]/,"",$i); if($i ~ /^linux-(image|headers)-[0-9]/){print $i; exit}}}'
}
kernel_image="$(trixie_meta_dep linux-image-amd64)"
kernel_headers="$(trixie_meta_dep linux-headers-amd64)"
[[ -n "$kernel_image" && -n "$kernel_headers" ]] || {
echo "could not resolve the trixie kernel packages" >&2; exit 1; }
kernel_base="$(printf '%s' "$kernel_image" | sed -E 's/^linux-image-([0-9][^-+]*).*/\1/')"
kernel_kbuild="linux-kbuild-$kernel_base"
echo "live kernel: $kernel_image ($kernel_kbuild)"
# Drop the rolling kernel metas; install the pinned stable kernel explicitly.
include_csv="$(printf '%s' "$include_csv" | tr ',' '\n' \
| grep -vE '^(linux-image-amd64|linux-headers-amd64)$' | paste -sd, -)"
include_csv="$include_csv,$kernel_image,$kernel_headers,$kernel_kbuild"
# The setup hook runs as the mapped uid, which cannot traverse a 0750 home
# directory, so it is staged into the world-traversable work directory. It adds
# the trixie suite and pins only the kernel packages to it.
setup_hook="$work/phoebus-setup.sh"
cat > "$setup_hook" <<'SETUP'
#!/bin/bash
set -euo pipefail
root="$1"
mkdir -p "$root/etc/apt/sources.list.d" "$root/etc/apt/preferences.d"
echo "deb http://deb.debian.org/debian trixie main contrib non-free non-free-firmware" \
> "$root/etc/apt/sources.list.d/trixie.list"
cat > "$root/etc/apt/preferences.d/phoebus-kernel" <<'PREFS'
Package: linux-image-* linux-headers-* linux-kbuild-*
Pin: release n=trixie
Pin-Priority: 1001
PREFS
SETUP
chmod 0755 "$setup_hook"
# The hook runs as the mapped uid, which cannot traverse a 0750 home directory,
# so it is staged into the world-traversable work directory.
hook_script="$work/livefs-hook.sh"
@ -149,8 +195,9 @@ MANGO_VERSION='$mango_version' DMS_VERSION='$dms_version' '$hook_script' \"\$1\"
--mode=unshare \
--format=tar \
--variant=standard \
--components=main \
--components=main,contrib,non-free,non-free-firmware \
--keyring="$work/apt-keys" \
--setup-hook="$setup_hook" \
--include="$include_csv" \
--customize-hook="$hook" \
"$suite" "$rootfs_tar" "$mirror"
@ -205,6 +252,37 @@ install_asset waybar-style /etc/xdg/waybar/style.css
# Live-only automatic login (never copied to an installed system).
install_asset greetd-live /etc/greetd/config.toml
# NVIDIA accelerated driver: load it before greetd/Mango, and provide
# diagnostics. The driver modules themselves are built into the rootfs by
# livefs-hook.sh; nouveau blacklisting and module options come from Debian's
# nvidia-kernel-common, which is the distro's supported configuration.
install_asset nvidia-load /usr/local/bin/phoebus-nvidia-load 0755
install_asset gpu-report /usr/local/bin/phoebus-gpu-report 0755
install_asset nvidia-service /usr/lib/systemd/system/phoebus-nvidia.service
install -d -m 0755 "$rootfs/etc/systemd/system/multi-user.target.wants"
ln -sf /usr/lib/systemd/system/phoebus-nvidia.service \
"$rootfs/etc/systemd/system/multi-user.target.wants/phoebus-nvidia.service"
# nvidia-kernel-common loads nvidia-drm unconditionally at boot. On a machine
# with no NVIDIA GPU that can leave a failed unit, so remove it and rely on the
# gated service above (which is a no-op without an NVIDIA display device).
rm -f "$rootfs/etc/modules-load.d/nvidia.conf"
# Build-time gate: the assembled rootfs (cached or fresh) MUST carry a complete
# NVIDIA payload for its exact kernel, or the build fails. This also writes
# /etc/phoebus/nvidia with the bundled driver version, module flavor and kernel.
nvidia_version="$(awk '/^Package: nvidia-driver$/{p=1} p&&/^Version:/{print $2; exit}' \
"$rootfs/var/lib/dpkg/status" 2>/dev/null)"
[[ -n "$nvidia_version" ]] || {
echo "live rootfs has no nvidia-driver package; refusing to ship without the driver" >&2
exit 1
}
"$release_dir/phoebus-installer" --verify-live-nvidia "$rootfs" \
--nvidia-version "$nvidia_version" --nvidia-flavor proprietary || {
echo "live rootfs NVIDIA payload is incomplete or mismatched" >&2
exit 1
}
echo "NVIDIA payload recorded: see /etc/phoebus/nvidia"
# Branding: shared vector assets, the app icon and the live-only marker.
install_asset brand-emblem /usr/share/phoebus/branding/emblem.svg
install_asset brand-wordmark /usr/share/phoebus/branding/wordmark.svg
@ -258,7 +336,12 @@ for check in \
etc/xdg/quickshell/phoebus-install/shell.qml \
usr/share/phoebus/branding/emblem.svg \
usr/share/phoebus/branding/wallpaper.svg \
etc/phoebus/live; do
etc/phoebus/live \
usr/local/bin/phoebus-nvidia-load \
usr/local/bin/phoebus-gpu-report \
usr/lib/systemd/system/phoebus-nvidia.service \
etc/modprobe.d/phoebus-nvidia.conf \
etc/phoebus/nvidia; do
[[ -e "$rootfs/$check" ]] || {
echo "live rootfs is missing payload: $check" >&2; exit 1; }
done
@ -344,6 +427,14 @@ t = t.replace('menuentry "Live system (amd64)"',
'menuentry "Start Phoebus OS (live medium)"')
t = t.replace('menuentry "Live system (amd64 fail-safe mode)"',
'menuentry "Phoebus OS (fail-safe graphics)"')
# The fail-safe entry is the documented fallback when NVIDIA (or any KMS)
# initialisation misbehaves: it disables modesetting and blacklists the NVIDIA
# modules for that boot, leaving the basic framebuffer in charge. The normal
# entry is unaffected. This is a recovery path, not the default.
t = t.replace(
'nosplash vga=788',
'nosplash vga=788 nomodeset '
'modprobe.blacklist=nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm')
open(p, "w").write(t)
PY
cat > "$bootcfg/theme.cfg" <<'EOF'

View file

@ -15,7 +15,11 @@ initramfs-tools
live-boot
live-config
live-config-systemd
# The kernel metas are placeholders: build.sh resolves and installs the exact
# Debian stable (trixie) 6.12 LTS kernel and headers instead, because the 550
# NVIDIA driver cannot build against testing's newer kernel.
linux-image-amd64
linux-headers-amd64
sudo
ca-certificates
curl
@ -29,6 +33,30 @@ btrfs-progs
util-linux
e2fsprogs
# --- GPU detection and the NVIDIA accelerated driver --------------------------
# The live medium bundles NVIDIA's accelerated stack so a supported GPU boots
# accelerated without downloading or compiling anything at boot. The kernel
# module is built for this image's exact (stable 6.12 LTS) kernel at build time
# (nvidia-kernel-dkms + linux-headers) and the build fails if the module,
# userspace or firmware is missing (see build.sh's --verify-live-nvidia gate).
# This is the proprietary branch from the signed Debian archive; it is the only
# branch Debian ships and it covers Maxwell through Ada/Hopper. Blackwell is not
# supported by this branch and falls back to nouveau, which is reported, never
# silently substituted. These packages come from contrib / non-free /
# non-free-firmware.
pciutils
linux-headers-amd64
dkms
nvidia-driver
nvidia-kernel-dkms
nvidia-smi
nvidia-vulkan-icd
nvidia-suspend-common
libnvidia-egl-gbm1
libnvidia-egl-wayland1
firmware-nvidia-graphics
firmware-nvidia-gsp
# --- login --------------------------------------------------------------------
greetd
tuigreet

View file

@ -82,6 +82,30 @@ if [ -d "$dmsdir/completions" ]; then
fi
rm -rf "$root/tmp/dms-full"
say "build NVIDIA kernel modules"
# The accelerated driver must be compiled for the exact kernel this image boots.
# Nothing is built or downloaded at boot; a failure here fails the build.
kernel_version="$(ls -1 "$root"/boot/vmlinuz-* 2>/dev/null | sed 's#.*/vmlinuz-##' | sort -V | tail -1)"
[ -n "$kernel_version" ] || { echo "livefs-hook: no kernel image found for NVIDIA" >&2; exit 1; }
if ! in_root dkms autoinstall -k "$kernel_version"; then
echo "livefs-hook: DKMS failed to build NVIDIA modules for $kernel_version" >&2
exit 1
fi
# Debian's nvidia-kernel-dkms renames the modules nvidia-current*; accept either
# naming so the hook does not depend on the packaging detail.
check_module() { # upstream-name debian-suffix
find "$root/lib/modules/$kernel_version" \
\( -name "$1.ko*" -o -name "nvidia-current$2.ko*" \) -print -quit 2>/dev/null | grep -q .
}
for pair in "nvidia:" "nvidia_modeset:-modeset" "nvidia_uvm:-uvm" "nvidia_drm:-drm"; do
upstream="${pair%%:*}"; suffix="${pair##*:}"
if ! check_module "$upstream" "$suffix"; then
echo "livefs-hook: $upstream.ko is missing for kernel $kernel_version" >&2
exit 1
fi
done
echo "livefs-hook: NVIDIA modules built for $kernel_version"
say "enable services"
# Regenerate the initramfs now that live-boot/live-config and the desktop
# packages are installed, so the live boot hooks are present.

View file

@ -0,0 +1,173 @@
#!/usr/bin/env python3
"""Generate phoebus-core's NVIDIA PCI device-ID -> generation table.
The table is derived from the public PCI ID database (`pci.ids`), vendor
`10de` (NVIDIA). Each entry's NVIDIA chip codename prefix (for example
`TU117`, `GA104`, `AD102`, `GB202`) determines the hardware generation. Only
display-class device IDs are ever looked up at runtime (the probe feeds the
classifier the IDs of `VGA compatible controller` / `3D controller` /
`Display controller` devices), so stray non-display entries in the database
are harmless.
Usage:
scripts/generate-nvidia-devices.py [pci.ids] > nvidia_devices.rs
With no argument the database is fetched from <https://pci-ids.ucw.cz/>.
The generated file is committed; it is never generated during a build.
"""
from __future__ import annotations
import hashlib
import re
import sys
import urllib.request
PCI_IDS_URL = "https://pci-ids.ucw.cz/v2.2/pci.ids"
# Codename prefix (first token of the PCI name) -> generation. The prefixes
# are NVIDIA's public architecture codenames (Tegra parts share the same
# families and are mapped accordingly). Ordered so the longest/most specific
# prefixes are matched first.
GENERATIONS: list[tuple[str, str]] = [
("Fermi", "GF"),
("Kepler", "GK"),
("Maxwell", "GM"),
("Pascal", "GP"),
("Volta", "GV"),
("Turing", "TU"),
("Ampere", "GA"),
("Ada", "AD"),
("Hopper", "GH"),
("Blackwell", "GB"),
]
CODENAME_RE = re.compile(r"^([A-Z]{2}\d{2,3}[A-Z]?)\b")
def fetch(url: str) -> bytes:
with urllib.request.urlopen(url, timeout=60) as resp: # noqa: S310
return resp.read()
def nvidia_devices(text: str) -> list[tuple[int, str]]:
lines = text.splitlines()
start = None
for i, line in enumerate(lines):
if re.match(r"^10de\s", line):
start = i
break
if start is None:
raise SystemExit("NVIDIA vendor (10de) not found in pci.ids")
devices: list[tuple[int, str]] = []
for line in lines[start + 1 :]:
if re.match(r"^[0-9a-fA-F]{4}\s", line):
break
m = re.match(r"^\t([0-9a-fA-F]{4})\s+(.*)", line)
if m:
devices.append((int(m.group(1), 16), m.group(2).strip()))
return devices
def generation_for(name: str) -> str | None:
m = CODENAME_RE.match(name)
if not m:
return None
codename = m.group(1)
for generation, prefix in GENERATIONS:
if codename.startswith(prefix):
return generation
return None
def main() -> int:
if len(sys.argv) > 1:
data = open(sys.argv[1], "rb").read()
source = sys.argv[1]
else:
data = fetch(PCI_IDS_URL)
source = PCI_IDS_URL
sha = hashlib.sha256(data).hexdigest()
devices = nvidia_devices(data.decode("utf-8", "replace"))
buckets: dict[str, set[int]] = {}
for device_id, name in devices:
generation = generation_for(name)
if generation:
buckets.setdefault(generation, set()).add(device_id)
# Detect an ID that would classify as two generations; the database does
# not normally contain one, and a duplicate means the codename rule is
# ambiguous and must be fixed here rather than silently resolved.
seen: dict[int, str] = {}
for generation, ids in buckets.items():
for device_id in ids:
if device_id in seen:
raise SystemExit(
f"device {device_id:#06x} classified as both "
f"{seen[device_id]} and {generation}"
)
seen[device_id] = generation
out = []
out.append("//! NVIDIA PCI device-ID classification table.")
out.append("//!")
out.append("//! GENERATED FILE - do not edit by hand. Regenerate with")
out.append("//! `scripts/generate-nvidia-devices.py`. The table is derived")
out.append("//! from the public PCI ID database (`pci.ids`, NVIDIA vendor `10de`)")
out.append("//! by mapping each device's NVIDIA chip codename to its generation.")
out.append("//!")
out.append(f"//! Source: {source}")
out.append(f"//! Source SHA-256: {sha}")
out.append("")
out.append("use super::nvidia::NvidiaGeneration;")
out.append("")
out.append("/// The PCI ID database revision this table was generated from.")
out.append(f'pub const SOURCE_SHA256: &str = "{sha}";')
out.append("")
out.append("/// Classify an NVIDIA PCI device ID (the `device` half of the")
out.append("/// `vendor:device` pair, fully qualified).")
out.append("///")
out.append("/// `None` means the database has no recognised NVIDIA chip codename for")
out.append("/// the device: it is reported as unknown and never claimed as supported.")
out.append("pub fn generation_for_device(device_id: u16) -> Option<NvidiaGeneration> {")
out.append(" use NvidiaGeneration::*;")
out.append(" match device_id {")
for generation, _ in GENERATIONS:
ids = sorted(buckets.get(generation, set()))
if not ids:
continue
joined = " | ".join(f"0x{i:04x}" for i in ids)
out.append(f" {joined} => Some({generation}),")
out.append(" _ => None,")
out.append(" }")
out.append("}")
out.append("")
out.append("#[cfg(test)]")
out.append("mod tests {")
out.append(" use super::*;")
out.append("")
out.append(" #[test]")
out.append(" fn representative_devices_classify() {")
out.append(" assert_eq!(generation_for_device(0x1380), Some(NvidiaGeneration::Maxwell));")
out.append(" assert_eq!(generation_for_device(0x1b81), Some(NvidiaGeneration::Pascal));")
out.append(" assert_eq!(generation_for_device(0x1d81), Some(NvidiaGeneration::Volta));")
out.append(" assert_eq!(generation_for_device(0x1e04), Some(NvidiaGeneration::Turing));")
out.append(" assert_eq!(generation_for_device(0x2482), Some(NvidiaGeneration::Ampere));")
out.append(" assert_eq!(generation_for_device(0x2684), Some(NvidiaGeneration::Ada));")
out.append(" assert_eq!(generation_for_device(0x2330), Some(NvidiaGeneration::Hopper));")
out.append(" assert_eq!(generation_for_device(0x2b85), Some(NvidiaGeneration::Blackwell));")
out.append(" assert_eq!(generation_for_device(0x0fc0), Some(NvidiaGeneration::Kepler));")
out.append(" }")
out.append("")
out.append(" #[test]")
out.append(" fn unknown_device_is_not_classified() {")
out.append(" assert_eq!(generation_for_device(0x0000), None);")
out.append(" }")
out.append("}")
sys.stdout.write("\n".join(out) + "\n")
return 0
if __name__ == "__main__":
raise SystemExit(main())