infrastructure/mw-pfeddersheim-workstation

Files

T

ja d9392447f9 doxify: inject DOX framework into AGENTS.md and update system config docs

- Inject all 10 DOX sections into root AGENTS.md (Core Contract, Read Before
  Editing, Update After Editing, Hierarchy, Child Doc Shape, Style, Closeout,
  User Preferences, Child DOX Index)
- Update ADR 0002: linux612->linux618, 575xx->580xx NVIDIA migration
- Update setup.md: kernel/driver refs to current linux618 + 580xx
- Update stack.md, hardware-inventory.md: NVIDIA note 595.71->580xx
- Update manual-overrides.md: add br_vm_internal bridge deletion entry
- Update workstation-health.md: add Recent Cleanup section
- Update README.md: current software versions, expand roles list
- Add docs/neovim-cheatsheet.md
- Bump last_updated to 2026-06-17 on all modified docs

2026-06-17 14:13:34 +02:00

5.8 KiB

Raw Blame History

description, tags, last_updated

description

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

Status

Accepted (2026-05-18) — Updated (2026-06-17)

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:

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, 580.x, and 595.x). Without it, flickering and missed vblanks are very common on Pascal+multi-monitor.
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 580xx modules (or vice versa) breaks the driver at the next kernel boot.

The starting point at the time of this ADR (2026-05-18):

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`

Current state (2026-06-17):

Item	Version
Kernel packages	`linux618`, `linux70`
NVIDIA driver branch	`580xx` (NVIDIA Fast Branch)
NVIDIA kernel module pkg	`linux618-nvidia-580xx`, `linux70-nvidia-580xx`
NVIDIA userspace packages	`nvidia-580xx-utils`, `lib32-nvidia-580xx-utils`, `opencl-nvidia-580xx`, `nvidia-580xx-settings`
Legacy packages removed	`*-nvidia-575xx` family (see `nvidia_packages_to_remove`)

Decision

Run two kernels side by side.
- Keep linux618 (LTS 6.18.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.
Migrate NVIDIA from the 575xx branch to 580xx (NVIDIA Fast Branch) 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, and the entire *-nvidia-575xx family.
- Install: linux618-nvidia-580xx, linux70-nvidia-580xx, nvidia-580xx-utils, lib32-nvidia-580xx-utils, opencl-nvidia-580xx, nvidia-580xx-settings.
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.
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.18 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.
580xx over 595.71. The NVIDIA Fast Branch (580xx) provides newer driver improvements while maintaining backward compatibility. Manjaro builds linux70-nvidia against nvidia-580xx-utils, so the 575xx branch is not an option for the new kernel. Pascal (GP107) is fully supported by 580.x, which ships 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-580xx. 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 linux618-nvidia-580xx and matching userspace are installed; legacy *-nvidia-575xx packages are removed.
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/driver pin bumps are one-line changes in ansible/vars/main.yml (kernel_packages / nvidia_kernel_modules / nvidia_userspace_packages 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.
ansible/vars/main.yml (current kernel and NVIDIA package pins).
ADR 1: docs/adr/0001-use-ansible-for-configuration.md — anchors the "Ansible-first" guardrail this decision follows.

5.8 KiB Raw Blame History