ja
d9392447f9
- 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
121 lines
5.8 KiB
Markdown
121 lines
5.8 KiB
Markdown
---
|
|
description: >-
|
|
Decision to dual-install linux618 (LTS) + linux70 (stable) kernels and
|
|
migrate NVIDIA from the pinned 575xx branch to the 580xx branch (NFB)
|
|
to prepare the workstation for Hyprland/Wayland.
|
|
tags:
|
|
- adr
|
|
- kernel
|
|
- nvidia
|
|
- hyprland
|
|
- wayland
|
|
last_updated: '2026-06-17'
|
|
---
|
|
|
|
# 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:
|
|
|
|
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, 580.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 `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
|
|
1. **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.
|
|
2. **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`.
|
|
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.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.
|