---
description: >-
  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.
tags:
  - adr
  - kernel
  - nvidia
  - hyprland
  - wayland
last_updated: '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.