infrastructure/mw-pfeddersheim-workstation
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
ja
2026-06-17 14:13:34 +02:00
parent de24990208
commit d9392447f9
9 changed files with 203 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/0002-kernel-and-nvidia-strategy.md
+36 -24
View File
@@ -1,7 +1,7 @@
---
description: >-
Decision to dual-install linux612 (LTS) + linux70 (stable) kernels and
migrate NVIDIA from the pinned 575xx branch to the mainline 595.71 branch
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
@@ -9,13 +9,13 @@ tags:
- nvidia
- hyprland
- wayland
last_updated: '2026-05-18'
last_updated: '2026-06-17'
---
# ADR 2: Kernel and NVIDIA Driver Strategy for Hyprland/Wayland
## Status
Accepted (2026-05-18)
Accepted (2026-05-18) — Updated (2026-06-17)
## Context
The workstation runs Manjaro Linux on AMD Ryzen 7 2700X with an NVIDIA
@@ -25,14 +25,14 @@ 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
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 `595.71` modules (or vice
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:
The starting point at the time of this ADR (2026-05-18):
| Item | Version |
|---------------------------|------------------------|
@@ -43,17 +43,29 @@ The starting point at the time of this ADR:
| `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 `linux612` (LTS 6.12.x) installed as the *fallback* boot entry.
- 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 mainline `595.71`** in
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`.
- Install: `linux612-nvidia`, `linux70-nvidia`, `nvidia-utils`,
`lib32-nvidia-utils`, `opencl-nvidia`, `nvidia-settings`.
`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.
@@ -63,17 +75,18 @@ The starting point at the time of this ADR:
`--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
- **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.
- **Mainline 595.71 over pinned 575.64.05.** Manjaro builds
`linux70-nvidia` only against `nvidia-utils=595.71.05`, so the 575xx
- **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 595.x, and 595.x ships the latest explicit-sync /
modesetting fixes upstream.
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
@@ -85,24 +98,23 @@ The starting point at the time of this ADR:
## Consequences
- **Two kernels on `/` partition.** Roughly +120 MB for `linux70` plus
~50 MB for `linux70-nvidia`. The role pre-flight refuses to start if
~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 `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.
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 pin bumps are one-line changes** in
- **Future kernel/driver pin bumps are one-line changes** in
`ansible/vars/main.yml` (`kernel_packages` /
`nvidia_kernel_modules` lists).
`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.