---
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.