steamify-cachyos/TODO-nvidia.md

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

Delete this file, NVIDIA-RESEARCH.md and .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.

Kernel changes (done, VM-tested 2026-10-01, Limine)

The early-load drop-in is kept right by a pacman hook (patches/steamify-nvidia-initramfs.{sh,hook}, installed by nvidia_enable, /etc/pacman.d/hooks/85-steamify-nvidia-initramfs.hook). Real pacman transactions in a Limine VM: the hook runs between "Updating module dependencies" and "Updating linux initcpios" (real hook names there: 60-*-remove, 80-limine-efi-deploy, 90-limine-mkinitcpio-remove-post, 90-mkinitcpio-install; DKMS would be 71-): the drop-in is present while every kernel has the modules, removed when the LTS kernel loses them, back when they return; initramfs nvidia files 1 -> 5 -> 1 -> 5 -> 1 (1 = baseline, 4 modules added); no ERROR/skipping in any rebuild; cmdline kept the parameters after a reboot; disable removes hook, script and drop-in. Found on the way: an empty hook/script was installed when patch_file failed (now an error). Only tested with fake modules (renamed copies of a small module), on Limine; systemd-boot and GRUB use the same hook but were not run with pacman transactions.

Opt-out toggle (new request, 2026-10-01: not built yet)

When a compatible NVIDIA card is listed there should be a menu option, on by default (opt-out), named "NVIDIA compatibility", as a sub-option of the SteamOS conversion, directly under "Boot into" (boot). Today the fix runs unconditionally inside gaming_enable/gaming_disable.

• New component nvidia in lib/menu.sh: COMPONENTS right after boot, PARENT[nvidia]=gaming, LABEL, FEATURE_VERSION[nvidia], component_available -> nvidia_available (= nvidia_present); not in NO_PRESELECT (ticked by default, feature_new ticks it for installs that already have the conversion). nvidia_status from the system (hook + parameters present), nvidia_enable/nvidia_disable = the code now called from gaming_enable/gaming_disable (remove those calls). Check toggle_component dependencies, feature_record_unticked, the plan texts ("This will: ...").
• The app: ui/qml/Texts.qml item texts, AppState.qml, the screen rows, lib/backend.sh if it lists ids; --defaults [--options <ids>] (the Steam Machine ISO's installer pages: it names the ids) and --skip.
• README rows/screenshot rule (a release that adds a menu row retakes assets/screenshot-menu.png), TECHNICAL.md, CHANGELOG, tests/nvidia-test.sh (status/enable/disable through the component), VM menu test in steamify-cachyos-dev (share/vmtest/menu, TESTPLAN.md row).
• What "compatible" means: see the research below. The parameters themselves apply to any card whose driver provides nvidia_drm (what nvidia_present tests); whether gamescope works on a card is a separate question.

Older cards and other research

The user hopes the fix also works for GPUs older than RTX 2000. Full notes with sources: NVIDIA-RESEARCH.md. Short version: open kernel modules need Turing+, Maxwell/Pascal/Volta need the proprietary driver (580 legacy branch); nvidia-drm.modeset/fbdev exist in both, so the fix applies to any card with nvidia_drm, but nothing found says gamescope works better or worse there (a GTX 1050 Ti has a known gamescope>3.16.16 start problem on HDMI, not ours). Cannot be promised: needs a test on a real older card. Design for the toggle: on by default for any card with nvidia_drm, the label says what it does, tests/nvidia-hardware-test.sh reports GPU and driver so results can be compared.

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 with the REAL NVIDIA modules (the VMs only have renamed fake ones), and systemd-boot/GRUB with a pacman transaction (only Limine was run).
4. Changelog: fill in the commit hashes of this feature's lines (next commit, per AGENTS.md).
5. Build the opt-out toggle (section above) before release.
6. 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).