fix(nvidia): install the driver before forcing it into the initramfs

The installer wrote dracut force_drivers naming nvidia modules during the
first kernel build, before the driver package existed, so the initial
kernel/initramfs build could not resolve them. Only the NVIDIA install
stage installs the driver and regenerates the initramfs.

- dracut_conf() no longer emits the NVIDIA fragment; the modprobe policy
  is still written before the kernel.
- write_nvidia_dracut_conf() writes it in the NVIDIA stage, after emerge
  and before kernel-install add-all.
- verify_nvidia_modules() proves the driver actually built modules for a
  kernel and fails the install otherwise; it returns the resolved version
  from var/db/pkg so the record carries the real version, kernel and
  module names rather than a 'current' label.
- The update path verifies the rebuilt modules before reporting success;
  previous kernels and module trees are left in place.
This commit is contained in:
Phoebus 2026-09-23 06:13:14 -07:00
parent 33b0b1df77
commit 12f264a0e9
4 changed files with 268 additions and 23 deletions

View file

@ -461,7 +461,13 @@ pub fn install_conf() -> String {
o o
} }
pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String { /// The generic dracut configuration.
///
/// It deliberately does **not** force the NVIDIA modules: `force_drivers`
/// naming a module that does not exist yet makes the first kernel build fail.
/// The NVIDIA fragment is written by the NVIDIA install stage, after the
/// driver's modules exist, and the initramfs is regenerated there.
pub fn dracut_conf(config: &InstallConfig) -> String {
let mut o = String::new(); let mut o = String::new();
o.push_str(&format!( o.push_str(&format!(
"# {} dracut configuration\n", "# {} dracut configuration\n",
@ -471,14 +477,16 @@ pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String
o.push_str("hostonly=\"no\"\n"); o.push_str("hostonly=\"no\"\n");
o.push_str("compress=\"zstd\"\n"); o.push_str("compress=\"zstd\"\n");
o.push_str("add_dracutmodules+=\" crypt btrfs \"\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 o
} }
/// The NVIDIA dracut fragment that forces the DRM/modeset modules (and their
/// firmware) into the initramfs, so the compositor never starts against a
/// modeset-less GPU. Only meaningful once the modules are installed.
pub fn nvidia_dracut_conf(hardware: &HardwareReport) -> Option<String> {
crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf()
}
pub fn kernel_profile_config(config: &InstallConfig) -> String { pub fn kernel_profile_config(config: &InstallConfig) -> String {
let profile = config.kernel.profile.as_str(); let profile = config.kernel.profile.as_str();
let mut o = String::new(); let mut o = String::new();
@ -1976,9 +1984,12 @@ mod tests {
assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open")); assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open"));
assert!(package_mask(&cfg, &hw).trim().is_empty()); assert!(package_mask(&cfg, &hw).trim().is_empty());
assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64")); assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64"));
let dracut = dracut_conf(&cfg, &hw); // The generic initramfs must not force modules that do not exist yet;
assert!(dracut.contains("force_drivers+=")); // the NVIDIA fragment is written once the driver is installed.
assert!(dracut.contains("nvidia_drm")); assert!(!dracut_conf(&cfg).contains("force_drivers"));
let nvidia = nvidia_dracut_conf(&hw).expect("nvidia dracut fragment");
assert!(nvidia.contains("force_drivers+="));
assert!(nvidia.contains("nvidia_drm"));
} }
#[test] #[test]
@ -2002,7 +2013,8 @@ mod tests {
assert!(!package_use(&cfg, &hw).contains("nvidia-drivers")); assert!(!package_use(&cfg, &hw).contains("nvidia-drivers"));
assert!(package_mask(&cfg, &hw).is_empty()); assert!(package_mask(&cfg, &hw).is_empty());
assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers")); assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers"));
assert!(!dracut_conf(&cfg, &hw).contains("nvidia")); assert!(nvidia_dracut_conf(&hw).is_none());
assert!(!dracut_conf(&cfg).contains("nvidia"));
} }
#[test] #[test]

View file

@ -512,6 +512,13 @@ pub fn execute(
"kernel-install", "kernel-install",
&["add-all".into()], &["add-all".into()],
)?; )?;
// Do not report success unless the rebuilt modules exist for a
// kernel; an update that installed a kernel but no matching
// NVIDIA modules must fail loudly, not silently boot degraded.
crate::boot::verify_nvidia_modules(root)?;
// The previous kernels and their module trees are left in
// place, so a failed update still has a bootable, coherent
// generation to fall back to.
} }
"system update complete".to_string() "system update complete".to_string()
} }
@ -686,6 +693,13 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
std::fs::create_dir_all(exec.root.join("etc/phoebus")).unwrap(); 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::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").unwrap();
std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap(); std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap();
// The rebuilt modules exist for the activated kernel.
let modules = exec.root.join("lib/modules/6.18.48");
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"] {
std::fs::write(modules.join(format!("{m}.ko")), b"x").unwrap();
}
let auth = auth(); let auth = auth();
execute( execute(
&exec, &exec,
@ -709,6 +723,25 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
); );
} }
#[test]
fn an_nvidia_update_that_produced_no_modules_fails() {
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();
let err = execute(
&exec,
&SystemAction::UpdateSystem,
Some(&auth),
Path::new(&exec.root),
)
.unwrap_err()
.to_string();
assert!(err.contains("NVIDIA"), "{err}");
}
#[test] #[test]
fn protective_snapshot_id_is_preserved_in_the_outcome() { fn protective_snapshot_id_is_preserved_in_the_outcome() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();

View file

@ -29,11 +29,14 @@ pub fn write_dracut_conf(
) -> Result<()> { ) -> Result<()> {
exec.target().write( exec.target().write(
"etc/dracut.conf.d/10-phoebus.conf", "etc/dracut.conf.d/10-phoebus.conf",
sysgen::dracut_conf(config, hardware), sysgen::dracut_conf(config),
)?; )?;
exec.logger.info("wrote /etc/dracut.conf.d/10-phoebus.conf"); exec.logger.info("wrote /etc/dracut.conf.d/10-phoebus.conf");
// NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be // NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be
// in place before the kernel is built and its initramfs generated. // in place before the kernel is built and its initramfs generated. The
// NVIDIA *dracut* fragment is intentionally not written here: the modules
// do not exist until the NVIDIA stage installs them, and `force_drivers`
// referencing a missing module makes the first kernel build fail.
if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() { if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() {
exec.target() exec.target()
.write("etc/modprobe.d/phoebus-nvidia.conf", conf)?; .write("etc/modprobe.d/phoebus-nvidia.conf", conf)?;
@ -43,6 +46,146 @@ pub fn write_dracut_conf(
Ok(()) Ok(())
} }
/// Write the NVIDIA `force_drivers` fragment. Called by the NVIDIA install
/// stage **after** the driver's kernel modules exist, so the final initramfs
/// (generated immediately afterwards) embeds them without naming a missing
/// module.
pub fn write_nvidia_dracut_conf(exec: &Exec, hardware: &HardwareReport) -> Result<()> {
if let Some(conf) = sysgen::nvidia_dracut_conf(hardware) {
exec.target()
.write("etc/dracut.conf.d/20-phoebus-nvidia.conf", conf)?;
exec.logger
.info("wrote /etc/dracut.conf.d/20-phoebus-nvidia.conf (force_drivers)");
}
Ok(())
}
/// The installed NVIDIA modules found for one kernel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InstalledNvidia {
/// The resolved driver package version from `var/db/pkg`, when present.
pub version: String,
/// The kernel the modules were built for.
pub kernel: String,
/// The on-disk module file names.
pub modules: Vec<String>,
}
/// The module stems that may satisfy a logical NVIDIA module. Debian's
/// `nvidia-kernel-dkms` renames them `nvidia-current*`; Gentoo and upstream use
/// the plain names.
fn nvidia_module_stems(module: &str) -> &'static [&'static str] {
match module {
"nvidia" => &["nvidia", "nvidia-current"],
"nvidia_modeset" => &["nvidia_modeset", "nvidia-current-modeset"],
"nvidia_uvm" => &["nvidia_uvm", "nvidia-current-uvm"],
"nvidia_drm" => &["nvidia_drm", "nvidia-current-drm"],
_ => &[],
}
}
/// Find a module file anywhere under `dir`, without following symlinks.
fn find_module_file(dir: &Path, module: &str) -> Option<String> {
let stems = nvidia_module_stems(module);
for entry in std::fs::read_dir(dir).ok()?.flatten() {
let path = entry.path();
if entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
if let Some(found) = find_module_file(&path, module) {
return Some(found);
}
} else if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
if stems.iter().any(|stem| {
name == format!("{stem}.ko") || name.starts_with(&format!("{stem}.ko."))
}) {
return Some(name.to_string());
}
}
}
None
}
/// The resolved `x11-drivers/nvidia-drivers` version from the target package
/// database, or an empty string when it cannot be determined.
fn installed_driver_version(root: &Path) -> String {
let dir = root.join("var/db/pkg/x11-drivers");
let Ok(entries) = std::fs::read_dir(&dir) else {
return String::new();
};
let mut best: Option<String> = None;
for entry in entries.flatten() {
let name = entry.file_name().to_string_lossy().to_string();
if let Some(version) = name.strip_prefix("nvidia-drivers-") {
let version = version.to_string();
if best.as_ref().map(|b| version > *b).unwrap_or(true) {
best = Some(version);
}
}
}
best.unwrap_or_default()
}
/// Verify that the NVIDIA driver actually built modules for a kernel in the
/// target.
///
/// A driver package that emerged but produced no loadable modules for any
/// kernel must make the install fail; it must never be recorded as successful
/// NVIDIA support. Returns the newest coherent kernel found.
pub fn verify_nvidia_modules(root: &Path) -> Result<InstalledNvidia> {
let required = ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"];
let mut checked: Vec<String> = Vec::new();
let mut newest: Option<InstalledNvidia> = None;
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = root.join(modules_root);
let Ok(entries) = std::fs::read_dir(&dir) else {
continue;
};
let mut kernels: Vec<String> = entries
.flatten()
.filter(|e| e.path().join("modules.dep").is_file())
.map(|e| e.file_name().to_string_lossy().to_string())
.collect();
kernels.sort_by(|a, b| {
phoebus_core::boot::version_key(a).cmp(&phoebus_core::boot::version_key(b))
});
for kernel in kernels {
checked.push(kernel.clone());
let kernel_dir = dir.join(&kernel);
let mut modules = Vec::new();
let mut complete = true;
for module in required {
match find_module_file(&kernel_dir, module) {
Some(name) => modules.push(name),
None => {
complete = false;
break;
}
}
}
if complete {
newest = Some(InstalledNvidia {
version: installed_driver_version(root),
kernel,
modules,
});
}
}
}
newest.ok_or_else(|| {
ExecError::operation(
"nvidia_drivers",
"verify installed modules",
format!(
"the NVIDIA driver produced no complete module set for any kernel{}",
if checked.is_empty() {
String::new()
} else {
format!(" (checked {})", checked.join(", "))
}
),
)
})
}
pub fn esp_path(exec: &Exec, config: &InstallConfig) -> std::path::PathBuf { pub fn esp_path(exec: &Exec, config: &InstallConfig) -> std::path::PathBuf {
exec.root exec.root
.join(config.storage.efi_mount.trim_start_matches('/')) .join(config.storage.efi_mount.trim_start_matches('/'))
@ -336,7 +479,7 @@ mod tests {
} }
#[test] #[test]
fn nvidia_hardware_writes_modprobe_and_dracut_before_the_kernel_build() { fn nvidia_modprobe_policy_precedes_the_kernel_but_force_drivers_follow_the_driver() {
use phoebus_core::hardware::{GpuInfo, GpuVendor}; use phoebus_core::hardware::{GpuInfo, GpuVendor};
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();
let exec = make_exec(runner); let exec = make_exec(runner);
@ -348,16 +491,48 @@ mod tests {
pci_id: Some("10de:2482".into()), pci_id: Some("10de:2482".into()),
pci_address: Some("0000:01:00.0".into()), pci_address: Some("0000:01:00.0".into()),
}); });
// First kernel build: the modprobe policy is present, but the initramfs
// is not told to force modules that do not exist yet.
write_dracut_conf(&exec, &cfg, &hw).unwrap(); write_dracut_conf(&exec, &cfg, &hw).unwrap();
let dracut = let dracut =
std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/10-phoebus.conf")).unwrap(); std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/10-phoebus.conf")).unwrap();
assert!(dracut.contains("force_drivers+=")); assert!(!dracut.contains("force_drivers"));
assert!(dracut.contains("nvidia_drm"));
let modprobe = let modprobe =
std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap(); std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap();
assert!(modprobe.contains("blacklist nouveau")); assert!(modprobe.contains("blacklist nouveau"));
assert!(modprobe.contains("options nvidia_drm modeset=1")); assert!(modprobe.contains("options nvidia_drm modeset=1"));
// NVIDIA stage: the fragment is written only now, before the final
// initramfs is regenerated.
write_nvidia_dracut_conf(&exec, &hw).unwrap();
let fragment =
std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/20-phoebus-nvidia.conf"))
.unwrap();
assert!(fragment.contains("force_drivers+="));
assert!(fragment.contains("nvidia_drm"));
}
#[test]
fn nvidia_module_verification_requires_a_complete_kernel_set() {
use std::fs;
let dir = tempfile::tempdir().unwrap();
let root = dir.path();
let modules = root.join("lib/modules/6.18.48");
fs::create_dir_all(&modules).unwrap();
fs::write(modules.join("modules.dep"), b"").unwrap();
// One module is not a driver.
fs::write(modules.join("nvidia.ko"), b"x").unwrap();
assert!(verify_nvidia_modules(root).is_err());
for m in ["nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
fs::write(modules.join(format!("{m}.ko")), b"x").unwrap();
}
let pkg = root.join("var/db/pkg/x11-drivers/nvidia-drivers-580.65.06");
fs::create_dir_all(&pkg).unwrap();
let installed = verify_nvidia_modules(root).unwrap();
assert_eq!(installed.kernel, "6.18.48");
assert_eq!(installed.version, "580.65.06");
assert_eq!(installed.modules.len(), 4);
} }
#[test] #[test]

View file

@ -524,8 +524,13 @@ impl Installer {
&self.engine, &self.engine,
&self.policy_ctx, &self.policy_ctx,
)?; )?;
// The modules exist now: force them into the initramfs, prove they
// were actually built for the selected kernel, then regenerate the
// boot image. A driver that produced no modules fails the install.
boot::write_nvidia_dracut_conf(&self.exec, &self.hardware)?;
let installed = boot::verify_nvidia_modules(&self.exec.root)?;
boot::generate_entries(&self.exec)?; boot::generate_entries(&self.exec)?;
self.record_nvidia(&plan)?; self.record_nvidia(&plan, &installed)?;
Ok(()) Ok(())
})(); })();
self.exec.umount_chroot()?; self.exec.umount_chroot()?;
@ -535,11 +540,25 @@ impl Installer {
result result
} }
/// Persist the resolved driver decision in the target so post-install /// Persist the resolved driver decision and the *actual* installed version
/// inspection and recovery know exactly what was selected. /// in the target, so post-install inspection and recovery know exactly what
fn record_nvidia(&self, plan: &phoebus_core::nvidia::NvidiaPlan) -> Result<()> { /// was selected rather than only a "current" label.
fn record_nvidia(
&self,
plan: &phoebus_core::nvidia::NvidiaPlan,
installed: &boot::InstalledNvidia,
) -> Result<()> {
let mut text = String::new(); let mut text = String::new();
text.push_str("# Resolved NVIDIA accelerated driver (generated by the installer).\n"); text.push_str("# Resolved NVIDIA accelerated driver (generated by the installer).\n");
text.push_str(&format!(
"version={}\n",
if installed.version.is_empty() {
"unknown"
} else {
&installed.version
}
));
text.push_str(&format!("kernel={}\n", installed.kernel));
text.push_str(&format!("branch={}\n", plan.branch)); text.push_str(&format!("branch={}\n", plan.branch));
text.push_str(&format!( text.push_str(&format!(
"flavor={}\n", "flavor={}\n",
@ -550,6 +569,9 @@ impl Installer {
plan.generation.map(|g| g.as_str()).unwrap_or("none") plan.generation.map(|g| g.as_str()).unwrap_or("none")
)); ));
text.push_str("package=x11-drivers/nvidia-drivers\n"); text.push_str("package=x11-drivers/nvidia-drivers\n");
for module in &installed.modules {
text.push_str(&format!("module={module}\n"));
}
for device in &plan.devices { for device in &plan.devices {
text.push_str(&format!( text.push_str(&format!(
"device={} {}\n", "device={} {}\n",
@ -559,9 +581,12 @@ impl Installer {
} }
text.push_str(&format!("reason={}\n", plan.reason)); text.push_str(&format!("reason={}\n", plan.reason));
self.exec.target().write("etc/phoebus/nvidia", text)?; self.exec.target().write("etc/phoebus/nvidia", text)?;
self.exec self.exec.logger.info(format!(
.logger "recorded the NVIDIA driver selection in /etc/phoebus/nvidia (version {}, kernel {}, modules: {})",
.info("recorded the NVIDIA driver selection in /etc/phoebus/nvidia"); if installed.version.is_empty() { "unknown" } else { &installed.version },
installed.kernel,
installed.modules.join(", ")
));
Ok(()) Ok(())
} }