From d001a02fdd1891b74aac2c6a07a9915270f266e4 Mon Sep 17 00:00:00 2001 From: Rick Peters Date: Thu, 1 Oct 2026 13:58:06 +0200 Subject: [PATCH] docs: TODO-nvidia.md: state and open work of the NVIDIA fix, for the next session --- .no-release-yet | 1 + TODO-nvidia.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 TODO-nvidia.md diff --git a/.no-release-yet b/.no-release-yet index efd5564..b7dafe9 100644 --- a/.no-release-yet +++ b/.no-release-yet @@ -1,3 +1,4 @@ This branch is not ready to be released: do not merge it into the release branch. When the feature is complete and tested, ask the user whether it may be released; on a yes, delete this file, then open the pull request into the release branch. +Open work and how to pick it up: TODO-nvidia.md. diff --git a/TODO-nvidia.md b/TODO-nvidia.md new file mode 100644 index 0000000..5e298fa --- /dev/null +++ b/TODO-nvidia.md @@ -0,0 +1,61 @@ +# 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).