chore: .no-release-yet: this NVIDIA branch is not ready to be released

Found by running it in a VM: the appended += line became literal text on the
kernel command line, and a kernel without the modules made limine-mkinitcpio
skip its boot entry.

.no-release-yet

@@ -0,0 +1,5 @@
+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, research and the test instructions for the NVIDIA PC are NOT in this repo:
+see steamify-cachyos-dev, folder nvidia/ (github.com/theupriser/steamify-cachyos-dev).

AGENTS.md

@@ -48,6 +48,13 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
   `<id>_available` is checked via `component_available` (e.g. `machine`
   only on Fremont). Turn-on order is `COMPONENTS` order, turn-off reverse;
   `gaming` must stay first. Dependencies live in `toggle_component`.
+- **Hardware-specific fixes** that belong to a component but aren't a menu
+  row (e.g. `lib/nvidia.sh`: NVIDIA's kernel parameters and early modules
+  for gaming mode, called from `gaming_enable`/`gaming_disable`) detect the
+  hardware themselves, change only what's missing, and undo it on disable.
+  Add them to the source loop in `steamify.sh` and the table in
+  `TECHNICAL.md`. They can't be tested without the hardware: say so in the
+  changelog and keep the branch behind `.no-release-yet` until it was.
 - **Feature versions.** Set `FEATURE_VERSION[<id>]` (`lib/menu.sh`) to the new
   `VERSION` whenever what `<id>_enable` sets up changes (a new component gets
   one too): installs recorded with an older version
@@ -126,7 +133,20 @@ gamescope and the Plasma desktop. Primary target: the Valve Steam Machine
       `sudo apt install gh`, then `gh auth login`) instead of working around
       it. Only the
       release branch's pull request into `main` is the user's: never commit
-      or merge to `main`, the user merges that one.
+      or merge to `main`, the user merges that one. Never work directly on
+      `main` or a `release/*` branch either: edits, even uncommitted ones,
+      go on a `feature/`/`bugfix/` branch (create it before editing; the
+      release branch only gets the version-bump commit and merged PRs).
+      Don't push a new `release/*` branch before it's needed: a push can
+      start CI builds (a dev ISO).
+      A machine without a git identity: pass the repo's author per command
+      (`git -c user.name=... -c user.email=... commit`, taken from `git
+      log`) instead of changing the git config.
+      A `.no-release-yet` file at the root of a feature/bugfix branch means
+      it must not be merged into the release branch yet (work in progress,
+      untested on hardware). When the feature is complete, ask the user
+      whether it may be released; on a yes, delete the file, then open the
+      pull request and merge it.
       Keep a feature/bugfix branch up to date by merging (or rebasing on)
       its release branch, the release branch by merging `main` when that
       moved.

CHANGELOG.md

@@ -7,6 +7,13 @@ one per merged pull request.
 
 ## 2.9.7 - 2026-10-01
 
+- **feat: the SteamOS conversion fixes a corrupted gaming mode screen with an NVIDIA GPU: nvidia-drm.modeset=1 and fbdev=1 on the kernel command line, NVIDIA modules in the initramfs (lib/nvidia.sh)**
+- **test: tests/nvidia-test.sh runs the NVIDIA fix against a fake RTX 5080 beside an iGPU, a stub modinfo and temp copies of the Limine, systemd-boot and GRUB files (no root, VM or hardware); NVIDIA_DRM_DIR points detection at a fake sysfs tree**
+- **fix: NVIDIA fix on Limine edits the KERNEL_CMDLINE[default] line (an appended += line ended up as literal text on the kernel command line, found in a VM); the modules are only loaded early when every installed kernel has them, and a Limine boot entry without the parameters is an error**
+- **test: tests/nvidia-hardware-test.sh for a real NVIDIA PC: check (read-only state of the detection, the live nvidia_drm modeset/fbdev, versions), apply, and visual (was the gaming mode picture clean), with a report file to paste**
+- **fix: the NVIDIA modules are loaded early only while every installed kernel has them, decided again at every kernel or driver change by a pacman hook (steamify-nvidia-initramfs): a later kernel without the modules (another kernel, a failed DKMS build, a downgrade) no longer makes its initramfs and Limine boot entry fail**
+- **feat: the NVIDIA fix is only for RTX 20 series or newer, decided like the VRAM booster does (vram_nvidia_legacy_id: chwd's legacy card lists); older cards are left alone**
+
 ## 2.9.6 - 2026-09-30
 
 - **fix(ci): a dev ISO from a release branch is built with that branch's own Steamify (input steamify_ref of the ISO workflow), not the newest published release: release/2.9.6 kept producing 2.9.5 ISOs**

TECHNICAL.md

@@ -206,6 +206,34 @@ or upgraded. A newly added kernel doesn't come with its headers, so
 `ensure-kernel-headers.service` checks at every boot and installs any
 missing `-headers` package, which makes DKMS build the driver for it.
 
+## NVIDIA fix for gaming mode
+
+gamescope drives the display itself through DRM/KMS, which with NVIDIA needs
+kernel modesetting and the framebuffer driver, and the driver loaded early;
+without them gaming mode can show a corrupted image. With a supported NVIDIA GPU (RTX 20 series or newer, decided like the VRAM
+booster does: a card on chwd's legacy lists `/var/lib/chwd/ids/nvidia-*.ids`
+is older and left alone, `vram_nvidia_legacy_id`; without those lists every
+card counts) and its driver installed (`lib/nvidia.sh`), the SteamOS conversion adds
+`nvidia-drm.modeset=1 nvidia-drm.fbdev=1` to the kernel command line (Limine,
+systemd-boot or GRUB; the file is backed up first) and
+`/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf` (`MODULES+=(nvidia
+nvidia_modeset nvidia_uvm nvidia_drm)`), then rebuilds the initramfs and boot
+entries. The early-load drop-in is only there while every installed kernel has the
+NVIDIA modules (mkinitcpio fails on a missing module, and `limine-mkinitcpio`
+then skips that kernel's boot entry, parameters included). That is decided again
+at every kernel or driver change by a pacman hook
+(`/etc/pacman.d/hooks/85-steamify-nvidia-initramfs.hook`, after DKMS builds,
+before the initramfs is built) running `/usr/local/libexec/steamify-nvidia-initramfs`:
+another kernel without the modules, a failed DKMS build or a downgrade removes
+the drop-in, and it comes back once every kernel has them again.
+On Limine the parameters go into the existing `KERNEL_CMDLINE[default]="..."`
+line: an extra appended `+=` line is pasted into the command line as text.
+Only what's missing is changed; it applies after a reboot. Turning
+the conversion off removes both, the hook and its script. `tests/nvidia-test.sh` tests it against a fake GPU
+and fake boot loader files; `tests/nvidia-hardware-test.sh check|apply|visual` is for a
+real NVIDIA PC (read-only check, the real apply, and a prompt for whether the picture
+was clean), and writes `~/steamify-nvidia-report.txt`.
+
 ## HDMI-CEC
 
 The **HDMI-CEC** item (on every PC; ticked by default only on a Steam
@@ -510,6 +538,7 @@ immediately, which can turn into a loop - see
 | `lib/steam-game.sh` | Add as non-Steam game: Steamify in the Steam library (`patches/steam-shortcuts.py`) |
 | `lib/update-notifier.sh` | Update notifications: the notifier from `patches/` and its user timer |
 | `lib/first-login.sh` | `--defaults` without a session (the Steam Machine ISO's installer): the one-time first-login step that sets up single user's launcher on Plasma's new layout and opens the app |
+| `lib/nvidia.sh` | NVIDIA fix for gaming mode: kernel parameters and early modules (part of the SteamOS conversion) |
 | `lib/vram-booster.sh` | VRAM booster (`dmemcg-booster`, `plasma-foreground-booster`) |
 | `services/` | The systemd units the scripts install (`service_file`, `@KEY@` placeholders); see its README |
 | `patches/` | Module sources and patches the scripts build or apply (`patch_file`); see its README |

lib/login-manager.sh

@@ -109,6 +109,7 @@ gaming_enable() {
     esac
     create_desktop_shortcut
     steam_enable
+    nvidia_enable || return 1
     os_name_enable || return 1
 }
 
@@ -124,6 +125,7 @@ gaming_disable() {
     steam_disable
     krevert gaming
     os_name_disable
+    nvidia_disable
     ok "The PC boots to the normal login screen again (from the next boot)."
 }
 

lib/menu.sh

@@ -25,7 +25,7 @@ NO_PRESELECT=(boot cec kpin hdmi)
 # FEATURE_BASELINE.
 FEATURE_BASELINE=2.1.0
 declare -A FEATURE_VERSION=(
-    [gaming]=2.9.0 [boot]=2.1.0 [theme]=2.1.0 [glyphs]=2.1.0 [single]=2.1.0
+    [gaming]=2.9.7 [boot]=2.1.0 [theme]=2.1.0 [glyphs]=2.1.0 [single]=2.1.0
     [launcher]=2.1.0 [cec]=2.7.0 [machine]=2.9.0 [poweroff]=2.2.0 [vram]=2.3.0 [notify]=2.5.0 [steamgame]=2.5.1
     [kpin]=2.1.0 [hdmi]=2.1.0
 )

lib/nvidia.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# NVIDIA fix for gaming mode, part of the SteamOS conversion
+# (gaming_enable/gaming_disable). gamescope drives the display itself
+# through DRM/KMS; with NVIDIA that needs kernel modesetting and the
+# framebuffer driver (nvidia-drm.modeset=1 nvidia-drm.fbdev=1) and the
+# driver in the initramfs, or the screen shows a corrupted image.
+# Does nothing without a supported NVIDIA GPU (RTX 20 series or newer) that has
+# its driver installed.
+# Sourced by steamify.sh; not meant to be run on its own.
+
+NVIDIA_PARAMS="nvidia-drm.modeset=1 nvidia-drm.fbdev=1"
+NVIDIA_INITRAMFS_CONF=/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf
+# The script and pacman hook that keep the initramfs file right at every kernel change.
+NVIDIA_SCRIPT=${NVIDIA_SCRIPT:-/usr/local/libexec/steamify-nvidia-initramfs}
+NVIDIA_HOOK=${NVIDIA_HOOK:-/etc/pacman.d/hooks/85-steamify-nvidia-initramfs.hook}
+# The DRM devices in sysfs; the tests point this at a fake tree.
+NVIDIA_DRM_DIR=${NVIDIA_DRM_DIR:-/sys/class/drm}
+
+nvidia_present() {
+    # A supported NVIDIA GPU: PCI vendor 0x10de, display class, its kernel
+    # driver installed, and not older than the RTX 20 series, decided like the
+    # VRAM booster does (vram_nvidia_legacy_id: chwd's legacy card lists, every
+    # other card runs NVIDIA's open modules). Older cards are left alone.
+    local d
+    for d in "$NVIDIA_DRM_DIR"/card[0-9]*/device; do
+        [[ "$(cat "$d/vendor" 2>/dev/null)" == 0x10de ]] || continue
+        [[ "$(cat "$d/class" 2>/dev/null)" == 0x03* ]] || continue
+        vram_nvidia_legacy_id "$(cat "$d/device" 2>/dev/null)" && continue
+        modinfo nvidia_drm >/dev/null 2>&1 && return 0
+    done
+    return 1
+}
+
+nvidia_legacy_gpu() {
+    # 0 when the only NVIDIA GPU(s) are older than RTX 20 (reported, not fixed).
+    local d found=0
+    for d in "$NVIDIA_DRM_DIR"/card[0-9]*/device; do
+        [[ "$(cat "$d/vendor" 2>/dev/null)" == 0x10de && "$(cat "$d/class" 2>/dev/null)" == 0x03* ]] || continue
+        vram_nvidia_legacy_id "$(cat "$d/device" 2>/dev/null)" || return 1
+        found=1
+    done
+    [[ $found == 1 ]]
+}
+
+nvidia_boot_file() {
+    # Same boot loaders as the kernel command line elsewhere (lib/hdmi-refresh.sh).
+    hdmi_boot_file
+}
+
+nvidia_param_set() {
+    # 0 when $1 (e.g. nvidia-drm.modeset=1) is on the kernel command line or
+    # already in the boot loader's file (not booted yet).
+    local f; f="$(nvidia_boot_file)"
+    grep -qw -- "$1" /proc/cmdline 2>/dev/null ||
+        { [[ -n "$f" ]] && grep -qw -- "$1" "$f" 2>/dev/null; }
+}
+
+nvidia_params_missing() {
+    local p
+    for p in $NVIDIA_PARAMS; do nvidia_param_set "$p" || return 0; done
+    return 1
+}
+
+nvidia_initramfs_ok() {
+    [[ -f "$NVIDIA_INITRAMFS_CONF" ]] || grep -qE '^MODULES=.*nvidia_drm' /etc/mkinitcpio.conf 2>/dev/null
+}
+
+nvidia_modules_everywhere() {
+    # 0 when every installed kernel has the nvidia_drm module (the script's own check).
+    patch_file steamify-nvidia-initramfs.sh | NVIDIA_MODULES_DIR="${NVIDIA_MODULES_DIR:-/usr/lib/modules}" bash -s check
+}
+
+nvidia_hook_install() {
+    # Never installs an empty script or hook (a piped patch_file that failed
+    # still lets install succeed with no input).
+    local script hook
+    script="$(patch_file steamify-nvidia-initramfs.sh)" && [[ -n "$script" ]] &&
+        hook="$(patch_file steamify-nvidia-initramfs.hook | fill SCRIPT="$NVIDIA_SCRIPT")" && [[ -n "$hook" ]] || return 1
+    printf '%s\n' "$script" | sudo install -Dm755 /dev/stdin "$NVIDIA_SCRIPT" &&
+        printf '%s\n' "$hook" | sudo install -Dm644 /dev/stdin "$NVIDIA_HOOK"
+}
+
+nvidia_rebuild_boot() {
+    local f; f="$(nvidia_boot_file)"
+    info "Rebuilding the initramfs and boot entries..."
+    case "$f" in
+        /etc/default/limine) sudo limine-mkinitcpio ;;
+        /etc/sdboot-manage.conf) sudo /usr/bin/mkinitcpio -P && sudo sdboot-manage gen ;;
+        /etc/default/grub) sudo /usr/bin/mkinitcpio -P && sudo grub-mkconfig -o /boot/grub/grub.cfg ;;
+        *) sudo /usr/bin/mkinitcpio -P ;;
+    esac
+}
+
+nvidia_boot_has_params() {
+    # 0 when the generated boot entries carry the parameters (or can't be
+    # checked): limine.conf, systemd-boot's entries, grub.cfg.
+    local target
+    case "$1" in
+        */limine) target="${NVIDIA_LIMINE_CONF:-/boot/limine.conf}" ;;
+        */sdboot-manage.conf) target="${NVIDIA_SDBOOT_DIR:-/boot/loader/entries}" ;;
+        */grub) target="${NVIDIA_GRUB_CFG:-/boot/grub/grub.cfg}" ;;
+        *) return 0 ;;
+    esac
+    sudo test -e "$target" || return 0
+    sudo grep -rqs 'nvidia-drm.modeset=1' "$target"
+}
+
+nvidia_enable() {
+    nvidia_present || return 0
+    local f changed=0 p; f="$(nvidia_boot_file)"
+    if nvidia_params_missing; then
+        if [[ -z "$f" ]]; then
+            warn "NVIDIA GPU found, but no supported boot loader: add '$NVIDIA_PARAMS' to the kernel command line yourself."
+        else
+            info "NVIDIA GPU found: adding $NVIDIA_PARAMS to the kernel command line (fixes a corrupted screen in gaming mode)..."
+            backup_file "$f"
+            case "$f" in
+                */limine)
+                    sudo sed -i -E "s/^(KERNEL_CMDLINE\[default\]=\"[^\"]*)\"/\1 $NVIDIA_PARAMS\"/" "$f" ;;
+                */sdboot-manage.conf)
+                    sudo sed -i -E "s/^(LINUX_OPTIONS=\"[^\"]*)\"/\1 $NVIDIA_PARAMS\"/" "$f" ;;
+                */grub)
+                    sudo sed -i -E "s/^(GRUB_CMDLINE_LINUX_DEFAULT=\"[^\"]*)\"/\1 $NVIDIA_PARAMS\"/" "$f" ;;
+            esac
+            if ! grep -q "nvidia-drm.fbdev=1" "$f"; then
+                err "Couldn't add the NVIDIA parameters to $f (no kernel command line setting in it): add '$NVIDIA_PARAMS' yourself."
+                return 1
+            fi
+            changed=1
+        fi
+    fi
+    nvidia_hook_install || { err "Installing the NVIDIA initramfs hook failed."; return 1; }
+    local had=0; [[ -f "$NVIDIA_INITRAMFS_CONF" ]] && had=1
+    sudo env NVIDIA_INITRAMFS_CONF="$NVIDIA_INITRAMFS_CONF" NVIDIA_MODULES_DIR="${NVIDIA_MODULES_DIR:-/usr/lib/modules}" "$NVIDIA_SCRIPT" sync
+    if [[ -f "$NVIDIA_INITRAMFS_CONF" && $had == 0 ]]; then
+        info "Loading the NVIDIA modules early (initramfs)..."
+        changed=1
+    elif [[ ! -f "$NVIDIA_INITRAMFS_CONF" && $had == 1 ]]; then
+        warn "A kernel without the NVIDIA modules is installed: not loading them early any more (rebuilding the initramfs without them)."
+        changed=1
+    elif [[ ! -f "$NVIDIA_INITRAMFS_CONF" ]] && ! nvidia_initramfs_ok; then
+        warn "Not every installed kernel has the NVIDIA modules: not loading them early for now (the kernel parameters still apply; this is checked again at every kernel update)."
+    fi
+    if [[ $changed == 1 ]]; then
+        nvidia_rebuild_boot || { err "Rebuilding the boot entries failed."; return 1; }
+        if ! nvidia_boot_has_params "$f"; then
+            err "The boot entries don't have the NVIDIA parameters: the initramfs or boot entry build failed (see above)."
+            return 1
+        fi
+        ok "NVIDIA gaming mode fix applied; it takes effect after a reboot."
+    fi
+    return 0
+}
+
+nvidia_disable() {
+    local f changed=0; f="$(nvidia_boot_file)"
+    if [[ -n "$f" ]] && grep -q "$NVIDIA_PARAMS" "$f" 2>/dev/null; then
+        sudo sed -i "s/ \?$NVIDIA_PARAMS//" "$f"
+        changed=1
+    fi
+    [[ -f "$NVIDIA_INITRAMFS_CONF" ]] && { sudo rm -f "$NVIDIA_INITRAMFS_CONF"; changed=1; }
+    sudo rm -f "$NVIDIA_HOOK" "$NVIDIA_SCRIPT"
+    [[ $changed == 1 ]] && nvidia_rebuild_boot
+    return 0
+}

lib/vram-booster.sh

@@ -44,6 +44,13 @@ vram_nvidia() {
 # 470xx, 390xx); every other NVIDIA card runs the open kernel modules.
 VRAM_CHWD_IDS=/var/lib/chwd/ids
 
+vram_nvidia_legacy_id() {
+    # vram_nvidia_legacy_id <pci device id, with or without 0x>: 0 when chwd
+    # lists the card for a closed legacy branch, i.e. it is older than the
+    # RTX 20 series. Also what lib/nvidia.sh uses to decide if a card is supported.
+    grep -qwi "${1#0x}" "$VRAM_CHWD_IDS"/nvidia-*.ids 2>/dev/null
+}
+
 vram_nvidia_case() {
     # Why an NVIDIA card's VRAM isn't registered, so the menu can say what to
     # do: "update" (open modules older than 615), "switch <chwd profile>"
@@ -62,8 +69,7 @@ vram_nvidia_case() {
     esac
     for d in /sys/bus/pci/devices/*; do
         [[ "$(cat "$d/vendor" 2>/dev/null)" == 0x10de && "$(cat "$d/class" 2>/dev/null)" == 0x03* ]] || continue
-        id="$(cat "$d/device")"; id="${id#0x}"
-        grep -qwi "$id" "$VRAM_CHWD_IDS"/nvidia-*.ids 2>/dev/null && { echo legacy; return; }
+        vram_nvidia_legacy_id "$(cat "$d/device")" && { echo legacy; return; }
     done
     for p in 580xx 470xx 390xx; do
         pacman -Q "nvidia-$p-dkms" >/dev/null 2>&1 && { echo "switch nvidia-dkms-$p"; return; }

patches/README.md

@@ -14,4 +14,5 @@ read and reviewed on their own. `lib/*.sh` reads them with `patch_file
 | `steam-shortcuts.py` | `lib/steam-game.sh` (Add as non-Steam game) | Reads and writes Steam's binary `shortcuts.vdf` (find, add or update, remove) |
 | `steamify-notifier.py` | `lib/update-notifier.sh` (Update notifications) | The daily check: notification and tray icon when there's a new release |
 | `steamify-os-release.sh`, `steamify-os-release.hook` | `lib/login-manager.sh` (SteamOS conversion) | What Steam's System settings show besides the OS name (which stays CachyOS's): `VERSION_ID=steamos-X.Y`, `VERSION_CODENAME=steam-machine`, `VARIANT`/`VARIANT_ID` Steamify with its version, in `/etc/os-release`; the pacman hook runs it again after cachyos-hooks (`fill SCRIPT=... VERSION=... STEAMOS=...`) |
+| `steamify-nvidia-initramfs.sh`, `steamify-nvidia-initramfs.hook` | `lib/nvidia.sh` (SteamOS conversion, NVIDIA fix) | The pacman hook (before the initramfs is built, after DKMS) and its script: the NVIDIA modules go into the initramfs only while every installed kernel has them, decided again at every kernel or driver change (`fill SCRIPT=...`) |
 | `cros-ec-cec-single-port.patch` | `lib/cec.sh` (HDMI-CEC) | Makes Valve's Steam Machine CEC driver find amdgpu's HDMI port |

patches/steamify-nvidia-initramfs.hook

@@ -0,0 +1,17 @@
+# Installed by Steamify CachyOS (SteamOS conversion, NVIDIA fix): decides
+# again whether the NVIDIA modules go into the initramfs, after DKMS has built
+# its modules (71-dkms-install) and before the initramfs is built
+# (90-mkinitcpio-install); hooks run in file name order.
+[Trigger]
+Operation = Install
+Operation = Upgrade
+Operation = Remove
+Type = Path
+Target = usr/lib/modules/*/vmlinuz
+Target = usr/lib/modules/*/extramodules/nvidia*
+Target = usr/lib/modules/*/updates/*
+
+[Action]
+Description = Steamify: NVIDIA modules in the initramfs only if every kernel has them
+When = PostTransaction
+Exec = @SCRIPT@ sync

patches/steamify-nvidia-initramfs.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Installed by Steamify CachyOS (SteamOS conversion, NVIDIA fix), run by the
+# pacman hook steamify-nvidia-initramfs.hook before the initramfs is built.
+# The NVIDIA modules go into the initramfs (early KMS) only while EVERY
+# installed kernel has them: mkinitcpio fails on a module a kernel lacks, and
+# limine-mkinitcpio then skips that kernel's boot entry, kernel parameters
+# included. Decided again at every kernel or driver change, so a new kernel
+# without the modules (another kernel, a failed DKMS build, a downgrade) gets
+# a working initramfs and the file comes back once it has them.
+#   steamify-nvidia-initramfs [sync|check]
+#   sync   (default) write or remove the drop-in to match
+#   check  exit status 0 when every installed kernel has nvidia_drm
+conf="${NVIDIA_INITRAMFS_CONF:-/etc/mkinitcpio.conf.d/90-steamify-nvidia.conf}"
+mods="${NVIDIA_MODULES_DIR:-/usr/lib/modules}"
+
+everywhere() {
+    local k found=0
+    for k in "$mods"/*/; do
+        [[ -f "$k/vmlinuz" || -f "$k/pkgbase" ]] || continue   # an installed kernel, not a leftover folder
+        find "$k" -name 'nvidia-drm.ko*' -print -quit 2>/dev/null | grep -q . || return 1
+        found=1
+    done
+    [[ $found == 1 ]]
+}
+
+case "${1:-sync}" in
+    check) everywhere ;;
+    sync)
+        if everywhere; then
+            [[ -f "$conf" ]] || { mkdir -p "$(dirname "$conf")" &&
+                echo 'MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)' > "$conf"; }
+        else
+            rm -f "$conf"
+        fi ;;
+    *) echo "usage: $0 [sync|check]" >&2; exit 2 ;;
+esac

steamify.sh

@@ -19,7 +19,7 @@ VERSION=2.9.7
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-for lib in common state packages login-manager single-user steam-desktop steam-machine fremont-poweroff vram-booster hdmi-refresh cec boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut steam-game update-notifier first-login menu backend; do
+for lib in common state packages login-manager single-user steam-desktop steam-machine fremont-poweroff vram-booster hdmi-refresh nvidia cec boot-session vapor-theme steamos-extras bios desktop-shortcut wizard-shortcut steam-game update-notifier first-login menu backend; do
     # shellcheck source=/dev/null
     source "$SCRIPT_DIR/lib/$lib.sh"
 done

tests/nvidia-hardware-test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Test of the NVIDIA fix on a real PC with an NVIDIA GPU (the unit test fakes
+# one: tests/nvidia-test.sh). Run from the Steamify checkout:
+#   bash tests/nvidia-hardware-test.sh check    read-only: what is detected, what the live kernel uses, what apply would change
+#   bash tests/nvidia-hardware-test.sh apply    really applies the fix (sudo), then reboot and run check again
+#   bash tests/nvidia-hardware-test.sh visual   after trying gaming mode: was the picture clean? (asks you)
+# Every run appends to ~/steamify-nvidia-report.txt: paste that file when asking for help.
+cd "$(dirname "$0")/.." || exit 1
+REPORT="${NVIDIA_REPORT:-$HOME/steamify-nvidia-report.txt}"
+source lib/common.sh; source lib/hdmi-refresh.sh; source lib/vram-booster.sh; source lib/nvidia.sh
+mode="${1:-check}"
+fail=0
+say() { echo "$*" | tee -a "$REPORT"; }
+pass() { say "PASS $*"; }
+bad()  { say "FAIL $*"; fail=1; }
+note() { say "     $*"; }
+root_cat() { cat "$1" 2>/dev/null || sudo cat "$1" 2>/dev/null || echo "(unreadable)"; }
+
+say ""; say "===== $(date '+%F %T')  mode=$mode  kernel=$(uname -r)"
+
+report_system() {
+    say "-- GPU and software"
+    lspci -nn 2>/dev/null | grep -iE 'vga|3d|display' | while read -r l; do note "$l"; done
+    command -v nvidia-smi >/dev/null && note "driver: $(nvidia-smi --query-gpu=name,driver_version --format=csv,noheader 2>&1 | head -n 1)"
+    for p in nvidia-open nvidia-utils nvidia-dkms gamescope gamescope-session-cachyos linux-cachyos-nvidia-open; do
+        v="$(pacman -Q "$p" 2>/dev/null)" && note "$v"
+    done
+    note "boot loader file: $(nvidia_boot_file || true)"
+    note "cmdline: $(cat /proc/cmdline)"
+}
+
+check_state() {
+    say "-- Steamify's view"
+    if nvidia_present; then pass "a supported NVIDIA GPU (RTX 20 series or newer) with its driver is detected"
+    elif nvidia_legacy_gpu; then bad "the NVIDIA GPU is older than RTX 20 (on chwd's legacy lists in $VRAM_CHWD_IDS): the fix is not applied"
+    else bad "no NVIDIA GPU with its driver detected: the fix does nothing here"; fi
+    for c in /sys/class/drm/card[0-9]*/device; do
+        [[ "$(cat "$c/vendor" 2>/dev/null)" == 0x10de ]] && note "NVIDIA PCI device id $(cat "$c/device") $(vram_nvidia_legacy_id "$(cat "$c/device")" && echo '(on a chwd legacy list)' || echo '(not on a legacy list: RTX 20 or newer)')"
+    done
+    ls "$VRAM_CHWD_IDS"/nvidia-*.ids >/dev/null 2>&1 || note "no chwd legacy lists found: every NVIDIA card counts as supported"
+    local p
+    for p in $NVIDIA_PARAMS; do
+        if grep -qw -- "$p" /proc/cmdline; then pass "$p is on the running kernel's command line"
+        elif nvidia_param_set "$p"; then bad "$p is in the boot loader's file but not booted yet: reboot"
+        else bad "$p is missing (run: bash tests/nvidia-hardware-test.sh apply)"; fi
+    done
+    say "-- the live NVIDIA driver"
+    local m
+    for m in modeset fbdev; do
+        v="$(root_cat /sys/module/nvidia_drm/parameters/$m)"
+        if [[ "$v" == Y ]]; then pass "nvidia_drm $m = Y"; else bad "nvidia_drm $m = $v (want Y)"; fi
+    done
+    lsmod | grep -q '^nvidia_drm' && pass "nvidia_drm is loaded" || bad "nvidia_drm is not loaded"
+    local c found=0
+    for c in /sys/class/drm/card[0-9]*/device; do
+        [[ "$(cat "$c/vendor" 2>/dev/null)" == 0x10de ]] || continue
+        found=1; note "NVIDIA card: ${c%/device} driver=$(basename "$(readlink -f "$c/driver" 2>/dev/null)")"
+        for s in "${c%/device}"/card*-*/status; do [[ -f "$s" ]] && note "  $(basename "$(dirname "$s")"): $(cat "$s")"; done
+    done
+    [[ $found == 1 ]] || bad "no NVIDIA card in /sys/class/drm"
+    say "-- initramfs"
+    if nvidia_modules_everywhere; then note "every installed kernel has nvidia_drm: the early-load drop-in is used"
+    else note "not every installed kernel has nvidia_drm: the early-load drop-in is skipped (parameters still apply)"; fi
+    nvidia_initramfs_ok && note "NVIDIA modules are in the initramfs config" || note "NVIDIA modules are not in the initramfs config"
+    say "-- what apply would change"
+    if nvidia_params_missing; then note "adds $NVIDIA_PARAMS to $(nvidia_boot_file)"; else note "kernel parameters: nothing to change"; fi
+    if ! nvidia_initramfs_ok && nvidia_modules_everywhere; then note "writes $NVIDIA_INITRAMFS_CONF"; fi
+}
+
+case "$mode" in
+    check)
+        report_system; check_state ;;
+    apply)
+        report_system
+        say "-- applying"
+        if nvidia_enable 2>&1 | tee -a "$REPORT"; [[ ${PIPESTATUS[0]} == 0 ]]; then pass "nvidia_enable finished"
+        else bad "nvidia_enable failed (output above)"; fi
+        say "Now reboot, then run: bash tests/nvidia-hardware-test.sh check" ;;
+    visual)
+        report_system
+        say "-- try gaming mode now (log in to it or reboot into it), look at the screen, then answer"
+        read -rp "Is the gaming mode picture clean (no corruption, no flicker)? [y/n/partly] " a
+        read -rp "What did you see (one line, e.g. 'garbled colours at start, fine after login')? " what
+        say "visual result: $a: $what"
+        [[ "$a" == y ]] && pass "picture clean" || bad "picture not clean ($a)"
+        say "-- gamescope and NVIDIA lines from this boot's log"
+        { journalctl -b --no-pager 2>/dev/null || sudo journalctl -b --no-pager 2>/dev/null; } |
+            grep -iE 'gamescope|nvidia|drm|nvrm|wlserver|vulkan' | tail -n 80 | tee -a "$REPORT" | tail -n 5
+        note "(more in $REPORT)" ;;
+    *) echo "usage: $0 check|apply|visual"; exit 2 ;;
+esac
+say ""; say "Report: $REPORT"
+exit $fail

tests/nvidia-test.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Tests lib/nvidia.sh against a fake RTX 5080 (PCI 10de:2c02) beside an
+# Intel iGPU, a stub modinfo, and temp copies of the boot loader files. No
+# root, VM or NVIDIA hardware needed: bash tests/nvidia-test.sh
+cd "$(dirname "$0")/.." || exit 1
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+fail=0
+check() { if eval "$2"; then echo "ok   $1"; else echo "FAIL $1"; fail=1; fi; }
+
+SCRIPT_DIR="$PWD"; source lib/common.sh; source lib/hdmi-refresh.sh; source lib/vram-booster.sh; source lib/nvidia.sh
+sudo() { "$@"; }
+info() { :; }; ok() { :; }; warn() { :; }; err() { echo "ERR $*"; }
+backup_file() { [[ -f "$1.bak" ]] || cp "$1" "$1.bak"; }
+modinfo() { [[ "$FAKE_DRIVER" == 1 ]]; }
+REBUILDS=0; nvidia_rebuild_boot() { REBUILDS=$((REBUILDS + 1)); }
+NVIDIA_INITRAMFS_CONF="$T/90-steamify-nvidia.conf"
+mkdir -p "$T/drm/card0/device" "$T/drm/card1/device"
+echo 0x8086 > "$T/drm/card0/device/vendor"; echo 0x030000 > "$T/drm/card0/device/class"
+echo 0x10de > "$T/drm/card1/device/vendor"; echo 0x030000 > "$T/drm/card1/device/class"
+echo 0x2c02 > "$T/drm/card1/device/device"
+NVIDIA_DRM_DIR="$T/drm"
+mkdir -p "$T/mods/6.1.0-cachyos/kernel"; : > "$T/mods/6.1.0-cachyos/kernel/nvidia-drm.ko.zst"; : > "$T/mods/6.1.0-cachyos/pkgbase"
+NVIDIA_SCRIPT="$T/libexec/steamify-nvidia-initramfs"; NVIDIA_HOOK="$T/hooks/85-steamify-nvidia-initramfs.hook"
+NVIDIA_MODULES_DIR="$T/mods"
+NVIDIA_LIMINE_CONF="$T/none/limine.conf"; NVIDIA_SDBOOT_DIR="$T/none/entries"; NVIDIA_GRUB_CFG="$T/none/grub.cfg"   # not generated here: not checked
+
+mkdir -p "$T/chwd"; VRAM_CHWD_IDS="$T/chwd"
+FAKE_DRIVER=1; check "finds the NVIDIA card as card1 beside an iGPU (no legacy lists)" nvidia_present
+printf '1c03\n1b80\n' > "$T/chwd/nvidia-580.ids"   # a GTX 1060 and a GTX 1080: chwd's 580xx legacy list
+check "RTX 5080 (2c02) is not on a legacy list: supported" nvidia_present
+echo 0x1c03 > "$T/drm/card1/device/device"
+check "GTX 1060 (on chwd's legacy list, older than RTX 20): not supported" '! nvidia_present'
+check "...and reported as a legacy GPU" nvidia_legacy_gpu
+echo 0x2c02 > "$T/drm/card1/device/device"; check "RTX 5080 is not a legacy GPU" '! nvidia_legacy_gpu'
+printf '2c02\n' > "$T/chwd/nvidia-580.ids"; check "a card id that is on a legacy list is skipped, whatever it is" '! nvidia_present'
+printf '1c03\n' > "$T/chwd/nvidia-580.ids"
+FAKE_DRIVER=0; check "skips when the driver isn't installed" '! nvidia_present'
+FAKE_DRIVER=1; NVIDIA_DRM_DIR="$T/none"; check "skips without an NVIDIA GPU" '! nvidia_present'
+NVIDIA_DRM_DIR="$T/drm"
+
+for loader in limine sdboot grub; do
+    case $loader in
+        limine) F="$T/limine"; printf 'KERNEL_CMDLINE[default]="quiet splash"\n' > "$F" ;;
+        sdboot) F="$T/sdboot-manage.conf"; printf 'LINUX_OPTIONS="quiet splash"\n' > "$F" ;;
+        grub)   F="$T/grub";   printf 'GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"\n' > "$F" ;;
+    esac
+    nvidia_boot_file() { echo "$F"; }
+    rm -f "$NVIDIA_INITRAMFS_CONF"; REBUILDS=0; ORIG="$(cat "$F")"
+    nvidia_enable
+    check "$loader: parameters added" 'grep -q "nvidia-drm.modeset=1" "$F" && grep -q "nvidia-drm.fbdev=1" "$F"'
+    check "$loader: initramfs drop-in written" 'grep -q nvidia_drm "$NVIDIA_INITRAMFS_CONF"'
+    check "$loader: script and pacman hook installed" '[[ -x "$NVIDIA_SCRIPT" ]] && grep -q "^Exec = $NVIDIA_SCRIPT sync" "$NVIDIA_HOOK"'
+    check "$loader: backup made, rebuilt once" '[[ -f "$F.bak" && $REBUILDS == 1 ]]'
+    SUM="$(cat "$F")"; nvidia_enable
+    check "$loader: second run changes nothing" '[[ "$(cat "$F")" == "$SUM" && $REBUILDS == 1 ]]'
+    nvidia_disable
+    check "$loader: disable restores the file, drops the drop-in, script and hook" '[[ "$(cat "$F")" == "$ORIG" && ! -f "$NVIDIA_INITRAMFS_CONF" && ! -e "$NVIDIA_SCRIPT" && ! -e "$NVIDIA_HOOK" ]]'
+done
+
+# A missing patches/ file must be an error, never an empty script or hook.
+( SCRIPT_DIR="$T/no-patches"; NVIDIA_SCRIPT="$T/empty/script"; NVIDIA_HOOK="$T/empty/hook"; ! nvidia_hook_install 2>/dev/null && [[ ! -s "$T/empty/script" ]] ) && echo "ok   a missing patch file is an error, nothing empty installed" || { echo "FAIL a missing patch file is an error, nothing empty installed"; fail=1; }
+# The pacman hook's script decides again at every kernel change.
+syncit() { NVIDIA_INITRAMFS_CONF="$NVIDIA_INITRAMFS_CONF" NVIDIA_MODULES_DIR="$NVIDIA_MODULES_DIR" bash "$NVIDIA_SCRIPT" sync; }
+nvidia_hook_install; rm -f "$NVIDIA_INITRAMFS_CONF"
+syncit; check "hook script: every kernel has the modules -> drop-in written" '[[ -f "$NVIDIA_INITRAMFS_CONF" ]]'
+mkdir -p "$T/mods/6.6.0-lts/kernel"; : > "$T/mods/6.6.0-lts/pkgbase"
+syncit; check "hook script: a new kernel without modules -> drop-in removed" '[[ ! -f "$NVIDIA_INITRAMFS_CONF" ]]'
+: > "$T/mods/6.6.0-lts/kernel/nvidia-drm.ko.zst"
+syncit; check "hook script: the modules arrive (DKMS built) -> drop-in back" '[[ -f "$NVIDIA_INITRAMFS_CONF" ]]'
+rm -rf "$T/mods/6.6.0-lts"; mkdir -p "$T/mods/5.0.0-leftover"; : > "$T/mods/5.0.0-leftover/modules.dep"
+syncit; check "hook script: a leftover folder of a removed kernel is ignored" '[[ -f "$NVIDIA_INITRAMFS_CONF" ]]'
+rm -rf "$T/mods/5.0.0-leftover"; nvidia_disable
+# A second kernel without the NVIDIA modules: no early-load drop-in, parameters still set.
+mkdir -p "$T/mods/6.6.0-lts/kernel"; : > "$T/mods/6.6.0-lts/pkgbase"; F="$T/sdboot-manage.conf"; printf 'LINUX_OPTIONS="quiet"\n' > "$F"
+nvidia_boot_file() { echo "$F"; }; rm -f "$NVIDIA_INITRAMFS_CONF"; REBUILDS=0; nvidia_enable
+check "kernel without nvidia modules: no drop-in, parameters set" '[[ ! -f "$NVIDIA_INITRAMFS_CONF" ]] && grep -q "nvidia-drm.fbdev=1" "$F"'
+rm -rf "$T/mods/6.6.0-lts"
+# Generated boot entries without the parameters (the initramfs build failed): an error.
+printf 'linux /vmlinuz root=/dev/sda1\n' > "$T/grub.cfg"; NVIDIA_GRUB_CFG="$T/grub.cfg"
+F="$T/grub"; printf 'GRUB_CMDLINE_LINUX_DEFAULT="quiet"\n' > "$F"; nvidia_boot_file() { echo "$F"; }; rm -f "$NVIDIA_INITRAMFS_CONF"
+check "boot entries without the parameters: error" '! nvidia_enable >/dev/null'
+NVIDIA_GRUB_CFG="$T/none/grub.cfg"
+# A config file without the setting to edit: an error, not "applied".
+F="$T/sdboot-manage.conf"; printf '#LINUX_OPTIONS=""\n' > "$F"; nvidia_boot_file() { echo "$F"; }; REBUILDS=0
+check "no setting to edit: error, nothing rebuilt" '! nvidia_enable >/dev/null && [[ $REBUILDS == 0 ]]'
+FAKE_DRIVER=0; printf 'LINUX_OPTIONS="quiet"\n' > "$T/sdboot"; F="$T/sdboot"; REBUILDS=0; nvidia_enable
+check "no NVIDIA driver: nothing touched" '[[ "$(cat "$F")" == "LINUX_OPTIONS=\"quiet\"" && $REBUILDS == 0 ]]'
+exit $fail