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.

## 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).