mw-pfeddersheim-workstation/docs/adr/0002-kernel-and-nvidia-strategy.md

description, tags, last_updated

description	tags	last_updated
Decision to dual-install linux612 (LTS) + linux70 (stable) kernels and migrate NVIDIA from the pinned 575xx branch to the mainline 595.71 branch to prepare the workstation for Hyprland/Wayland.	adr kernel nvidia hyprland wayland	2026-05-18

ADR 2: Kernel and NVIDIA Driver Strategy for Hyprland/Wayland

Status

Accepted (2026-05-18)

Context

The workstation runs Manjaro Linux on AMD Ryzen 7 2700X with an NVIDIA GeForce GTX 1050 Ti (Pascal, GP107) driving three monitors. The next infrastructure plan switches the desktop from KDE/X11 to Hyprland on Wayland. Two preconditions must hold before that switch is safe:

1. DRM/atomic and NVIDIA explicit-sync support — Hyprland on NVIDIA relies on driver-level explicit sync (introduced in 555.x and matured through 575.x and 595.x). Without it, flickering and missed vblanks are very common on Pascal+multi-monitor.
2. Matching kernel modules — Manjaro ships pre-built *-nvidia modules pinned to a single nvidia-utils version. Mixing 575xx userspace with a kernel that only has 595.71 modules (or vice versa) breaks the driver at the next kernel boot.

The starting point at the time of this ADR:

Item	Version
Running kernel	linux612 6.12.77-1
NVIDIA driver	575.64.05-3 (575xx branch)
NVIDIA kernel module pkg	linux612-nvidia-575xx 575.64.05-31
linux70 available in repo	7.0.3-1
linux70-nvidia available	595.71.05-0.1
linux612-nvidia (mainline)	595.71.05-2

Decision

1. Run two kernels side by side.
   • Keep linux612 (LTS 6.12.x) installed as the fallback boot entry.
   • Install linux70 (stable 7.0.x) and select it as the daily-driver kernel via GRUB at the next reboot.
2. Migrate NVIDIA from the 575xx branch to mainline 595.71 in one atomic pacman transaction so both kernels have matching modules:
   • Remove: linux612-nvidia-575xx, nvidia-575xx-utils, lib32-nvidia-575xx-utils, nvidia-575xx-settings.
   • Install: linux612-nvidia, linux70-nvidia, nvidia-utils, lib32-nvidia-utils, opencl-nvidia, nvidia-settings.
3. Do not change GRUB_DEFAULT programmatically. The user picks linux70 from the GRUB menu on first boot. If linux70 misbehaves, the next reboot is one menu selection away from the proven LTS path.
4. Encapsulate everything in an idempotent Ansible role (ansible/roles/system-upgrade/) that runs before common, dev-tools and maintenance. It is invoked stand-alone with --tags system-upgrade and is safe on every subsequent run.

Rationale

• LTS as a parachute. 6.12 is a Linux LTS series with a multi-year support window. Keeping it installed makes the migration reversible by one keystroke in GRUB.
• 7.0 as the daily driver. The 7.0 series brings the maturest DRM/atomic-modeset and NVIDIA explicit-sync paths that Hyprland on Pascal needs to avoid flicker on multi-monitor.
• Mainline 595.71 over pinned 575.64.05. Manjaro builds linux70-nvidia only against nvidia-utils=595.71.05, so the 575xx branch is not an option for the new kernel. Pascal (GP107) is fully supported by 595.x, and 595.x ships the latest explicit-sync / modesetting fixes upstream.
• Single atomic transaction. Removing the old branch and installing the new one in one pacman call (with the removal list narrowed to packages that are actually installed) keeps the GPU-driver window to roughly one second of cache I/O on a local SSD.
• Idempotent role over shell script. Matches the existing common/dev-tools/maintenance pattern, supports --check, and re-running after success is a true no-op (validated by gating every mutating task on pacman_syu.changed or nvidia_migration.changed).

Consequences

• Two kernels on / partition. Roughly +120 MB for linux70 plus ~50 MB for linux70-nvidia. The role pre-flight refuses to start if free space on / is below 5 GiB.
• mhwd profile referencing 575xx stays as-is. Only the kernel-bound linux612-nvidia-575xx and matching userspace are swapped; mhwd-nvidia-575xx stays installed so MHWD's profile listing remains consistent. A future cleanup can switch the MHWD profile to video-nvidia once linux70 is verified.
• Manual reboot required. The role never reboots the machine; it ends with a clear notice instructing the user to boot into linux70 from GRUB before applying the next (Hyprland) playbook.
• Future kernel pin bumps are one-line changes in ansible/vars/main.yml (kernel_packages / nvidia_kernel_modules lists).

References

• Hyprland NVIDIA notes (wiki.hypr.land/Nvidia): explicit sync available from driver ≥555 and required for tear-free Wayland.
• docs/tech/hardware-inventory.md (NVIDIA section).
• ansible/roles/system-upgrade/tasks/main.yml.
• ADR 1: docs/adr/0001-use-ansible-for-configuration.md — anchors the "Ansible-first" guardrail this decision follows.