steamify-cachyos/TODO-nvidia.md

TODO: NVIDIA fix for gaming mode (branch feature/nvidia-gaming-fix)

Delete this file together with .no-release-yet when the feature is released. Written 2026-10-01 so a new session can pick this up.

Problem

A PC with an NVIDIA RTX 5080 (Blackwell, open kernel modules) shows a corrupted image when gaming mode (gamescope) starts. Cause not confirmed. Steamify had no NVIDIA handling at all. Likely: nvidia-drm.modeset=1 / nvidia-drm.fbdev=1 missing, or a gamescope/driver mismatch.

What is built (all on this branch, pushed)

• lib/nvidia.sh: part of the SteamOS conversion (gaming_enable / gaming_disable). With an NVIDIA GPU + driver it adds nvidia-drm.modeset=1 nvidia-drm.fbdev=1 to the kernel command line (Limine, systemd-boot, GRUB; backup first) and, only when every installed kernel has nvidia_drm, /etc/mkinitcpio.conf.d/90-steamify-nvidia.conf. Rebuilds initramfs + boot entries, verifies the config and the generated entries have the parameters (error otherwise). Undone on disable. Description: TECHNICAL.md.
• FEATURE_VERSION[gaming]=2.9.7 so installs that already have the conversion re-apply it.
• Test hooks NVIDIA_DRM_DIR, NVIDIA_MODULES_DIR, NVIDIA_LIMINE_CONF, NVIDIA_SDBOOT_DIR, NVIDIA_GRUB_CFG: only set by tests; defaults are the real paths.

Tested

• bash tests/nvidia-test.sh: 22 checks against a fake RTX 5080 beside an iGPU, a stub modinfo, temp boot loader files. All pass.
• Real VMs (QEMU/KVM, Limine, systemd-boot, GRUB): enable, reboot, kernel command line has the parameters; disable, reboot, original command line. All pass. Found and fixed: Limine pasted an appended += line as text into the cmdline; a kernel without the NVIDIA modules made limine-mkinitcpio skip its boot entry.

In progress (2026-10-01)

• Kernel changes: the early-load drop-in is now kept right by a pacman hook (patches/steamify-nvidia-initramfs.{sh,hook}, installed by nvidia_enable). Unit-tested (29 checks). Not yet VM-tested with a real pacman transaction: hook order (85- after 71-dkms-install, before the mkinitcpio/limine hooks: check the real hook names in /usr/share/libalpm/hooks), a kernel reinstall with and without modules.

Still to do

1. On the NVIDIA PC (only place the real fix can be judged), from this checkout: bash tests/nvidia-hardware-test.sh check (before), ... apply (asks sudo), reboot, ... check (after: nvidia_drm modeset/fbdev = Y), boot gaming mode, then ... visual (was the picture clean?). Everything goes to ~/steamify-nvidia-report.txt: paste it into the session.
2. If the parameters apply but the picture is still corrupted: look at the report's gamescope/NVIDIA log lines and the versions (nvidia-open, nvidia-utils, gamescope, gamescope-session-cachyos); the cause is then probably a gamescope/driver mismatch for Blackwell, not this fix.
3. Not covered by any test: the early-load drop-in on a machine that has the modules (the VMs have none), and a boot loader other than the three.
4. Changelog: fill in the commit hashes of this feature's lines (next commit, per AGENTS.md).
5. When complete and tested: ask the user whether it may be released. On a yes delete .no-release-yet and this file, open the PR into release/2.9.7 (local branch only so far, one commit chore: Version 2.9.7; push it then) and merge it. The user merges release/2.9.7 into main.

Working rules for this repo (see AGENTS.md and ../steamify-cachyos-dev/AGENTS.md)

• Never work on main or a release/* branch; no Co-Authored-By / "Generated with Claude" lines in commits or PRs. No git identity on the dev laptop: use git -c user.name="Rick Peters" -c user.email="rickpeters@upriser.nl" commit.
• Don't push release/2.9.7 before the PR (a push can start a dev ISO build).

If the VM tests need repeating (dev laptop, Ubuntu)

• scripts/vminstall.sh (steamify-cachyos-dev) with VM_BOOTLOADER=limine|systemd-boot|grub, CI=1, a short VM_DIR (~/vms/...: socket paths over 108 bytes fail) and VM_SSH_KEY.
• This session's shell lacked the kvm group: run QEMU steps as sg kvm -c "...".
• /tmp/vminstall-iso.lock belongs to another user and there is no bsdtar: use a copy of vminstall.sh with another lock path and a bsdtar shim (Python pycdlib in a venv).
• Delete everything afterwards (~/vms incl. pkg-cache, the 3 GB ISO, keys).