e81529c1bb
Self-gated System › Fingerprint when fprintd is on PATH: enroll, list, verify, delete-all (terminal), and Use for login writing settings.fingerprint.pam (hardware.nix default from theme-state). Close #55. Verified: V1 (HM menu rebuild). V3 pending: real-reader enroll (HARDWARE-QUEUE).
397 lines
16 KiB
Markdown
397 lines
16 KiB
Markdown
# Hardware support
|
||
|
||
How Nomarchy enables CPUs, GPUs, laptops, firmware, and peripherals — and
|
||
what to do when your machine is not in the happy path.
|
||
|
||
> **Queue:** [`agent/BACKLOG.md`](../agent/BACKLOG.md) (PROPOSED › Hardware
|
||
> product). Product framing: [`VISION.md`](VISION.md) § A. Design history:
|
||
> [`ROADMAP.md`](ROADMAP.md). Docs map: [`README.md`](README.md).
|
||
> Migration: [`MIGRATION.md`](MIGRATION.md).
|
||
|
||
## 1. Architecture (three layers)
|
||
|
||
Nomarchy does **not** reimplement [nixos-hardware](https://github.com/NixOS/nixos-hardware).
|
||
It stacks:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ A. Always-on desktop floor │
|
||
│ modules/nixos/default.nix + power.nix + audio/BT │
|
||
│ redistributable firmware · fwupd · NM · PipeWire · PPD · ddcci │
|
||
└───────────────────────────────┬─────────────────────────────────────┘
|
||
│
|
||
┌───────────────────────────────▼─────────────────────────────────────┐
|
||
│ B. nixos-hardware profiles (via mkFlake hardwareProfile) │
|
||
│ common-cpu-* · common-gpu-* · common-pc(-laptop|-ssd) · model │
|
||
│ microcode · GPU media · fstrim · vendor/model quirks │
|
||
└───────────────────────────────┬─────────────────────────────────────┘
|
||
│
|
||
┌───────────────────────────────▼─────────────────────────────────────┐
|
||
│ C. nomarchy.hardware.* (modules/nixos/hardware.nix) │
|
||
│ gap above commons: GuC · amd-pstate · VA-API env · fprintd · │
|
||
│ IR-webcam hide · ROCm/NPU/latestKernel · I2C/DDC/CI │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| Layer | Who turns it on | Where it lives |
|
||
|-------|-----------------|----------------|
|
||
| **A** | Distro defaults (`mkDefault`) | Any machine importing `nomarchy.nixosModules.nomarchy` |
|
||
| **B** | Installer DMI/`lspci` → `hardwareProfile = [ … ]` | Downstream `flake.nix` (`mkFlake`) |
|
||
| **C** | Installer probes → `system.nix`, or hand-edit | Downstream `system.nix` |
|
||
|
||
`hardware-configuration.nix` (from `nixos-generate-config`) still owns
|
||
initrd modules, filesystems, and the usual generate-config flags. The
|
||
installer writes a real one; the template ships a placeholder you must
|
||
replace.
|
||
|
||
Unknown `hardwareProfile` names **fail at eval** with Levenshtein
|
||
suggestions (`lib.nix`) — never silently ignored.
|
||
|
||
## 2. What works without thinking about it
|
||
|
||
These ship on every Nomarchy system unless you override them:
|
||
|
||
| Capability | Default | Notes |
|
||
|------------|---------|--------|
|
||
| Wi‑Fi / BT firmware blobs | `hardware.enableRedistributableFirmware` | iwlwifi, ath, rtw, brcm, SOF, … |
|
||
| NetworkManager | on | Wi‑Fi UI: System › Network |
|
||
| PipeWire + WirePlumber | on | |
|
||
| Bluetooth + blueman | on | System › Bluetooth |
|
||
| power-profiles-daemon | on | Menu + Waybar; TLP via `nomarchy.system.power.backend = "tlp"` |
|
||
| External monitor brightness | `nomarchy.hardware.i2c.ddcci` **on** | DDC/CI → backlight devices |
|
||
| Firmware updates (LVFS) | `services.fwupd.enable` | **Never auto-flashes** — see §4 |
|
||
| SMART / UPower / pcscd (FIDO) | on | |
|
||
| earlyoom | on | Process-level OOM, not cgroup kill of the whole session |
|
||
|
||
**Not** default-on (need detect or uncomment): fprintd, GuC/HuC,
|
||
amd-pstate, ROCm, NPU, thermald, charge limit, snapper (installer enables
|
||
snapper), `latestKernel`.
|
||
|
||
## 3. Install path (best experience)
|
||
|
||
`nomarchy-install` sources `pkgs/nomarchy-install/hardware-db.sh` and:
|
||
|
||
1. Probes CPU vendor, GPUs (`lspci`), battery, SSD, fingerprint USB VIDs,
|
||
RGB+IR webcam names, NPU PCI class.
|
||
2. Looks up DMI `sys_vendor` × `product_name` in a ~60-entry model table
|
||
(Framework, Dell XPS/Latitude, ThinkPad, Surface, ASUS ROG, Apple T2,
|
||
System76).
|
||
3. Emits `MODULE …` lines → `hardwareProfile` list in `flake.nix`.
|
||
4. Emits `NOMARCHY hardware.*=…` → active + commented blocks in
|
||
`system.nix`.
|
||
5. Asks you to confirm profiles (or pick manually from the full
|
||
nixos-hardware attr list baked into the ISO). Override with
|
||
`NOMARCHY_HW=auto|none|"mod1 mod2"`.
|
||
|
||
**Live ISO** is intentionally *generic* (no model profile): broad GPU
|
||
modules as *available*, redistributable firmware on, no baked
|
||
`nomarchy.hardware.*`. Tuning happens at install time.
|
||
|
||
Out of scope for the installer today: aarch64 (Pi, Snapdragon X), Steam
|
||
Deck (Jovian), Apple Silicon (T2 Intel Macs only in the DB).
|
||
|
||
## 4. Firmware updates (deep dive)
|
||
|
||
### What we ship
|
||
|
||
```nix
|
||
# modules/nixos/default.nix
|
||
services.fwupd.enable = lib.mkDefault true;
|
||
```
|
||
|
||
fwupd talks to the [LVFS](https://fwupd.org/): UEFI capsule (BIOS), some
|
||
SSDs, docks, Thunderbolt controllers, peripherals. It **only refreshes
|
||
metadata** on its own. Applying an update is always an explicit user
|
||
action.
|
||
|
||
### What you do today (CLI)
|
||
|
||
```sh
|
||
# After first boot (and occasionally later):
|
||
fwupdmgr refresh # optional; daemon often has metadata
|
||
fwupdmgr get-devices # what LVFS can see
|
||
fwupdmgr get-updates # pending
|
||
fwupdmgr update # apply (may need reboot / battery / AC)
|
||
```
|
||
|
||
Disable on VMs/headless: `services.fwupd.enable = false;` in `system.nix`.
|
||
|
||
### Why this is under-discovered
|
||
|
||
| Present | Missing |
|
||
|---------|---------|
|
||
| Daemon + package | First-boot / MOTD hint |
|
||
| README one-liner | Doctor check (“updates available”) |
|
||
| **System ▸ Firmware menu** (`nomarchy-menu firmware`) | Waybar / updates panel integration |
|
||
|
||
**System ▸ Firmware** (shipped): a self-gated System-submenu row (present
|
||
whenever `fwupdmgr` is on PATH, i.e. `services.fwupd.enable`, default-on)
|
||
that opens a terminal and runs `fwupdmgr refresh` → `get-updates` →
|
||
confirm → `fwupdmgr update`. It never auto-flashes — `fwupdmgr update`
|
||
confirms each device and prompts for the reboot a capsule needs; pillar 1
|
||
(rock-stable) forbids silent BIOS writes.
|
||
|
||
**Still queued:** a post-install / MOTD one-liner when `fwupd` is active,
|
||
a Doctor “updates available” check, and Waybar/updates-panel integration.
|
||
|
||
### Thunderbolt
|
||
|
||
Firmware for TB devices may appear via LVFS. There is **no** first-class
|
||
`services.hardware.bolt` / security-level UI in Nomarchy — use plain
|
||
NixOS options if you need bolt.
|
||
|
||
### Microcode / kernel firmware
|
||
|
||
- **CPU microcode:** from nixos-hardware `common-cpu-*` and
|
||
`nixos-generate-config` once redistributable firmware is on — not a
|
||
separate `nomarchy.*` toggle.
|
||
- **GPU GuC/HuC (Intel i915):** `nomarchy.hardware.intel.guc` →
|
||
`i915.enable_guc=3`. Installer turns this **off** when the bound driver
|
||
is `xe` (GuC is default there; the param is ignored).
|
||
- **`hardware.enableAllFirmware`:** not set. Oddball non-redistributable
|
||
Wi‑Fi still needs a manual NixOS fix (or a broader policy decision).
|
||
|
||
## 5. Fingerprint (deep dive)
|
||
|
||
### Detect → enable
|
||
|
||
Installer scans USB vendor IDs common to libfprint (Goodix, Synaptics,
|
||
Elan, …) via `lsusb` or `/sys/bus/usb/.../idVendor`. On hit:
|
||
|
||
```nix
|
||
nomarchy.hardware.fingerprint.enable = true; # services.fprintd
|
||
# nomarchy.hardware.fingerprint.pam = true; # login + sudo (opt-in)
|
||
```
|
||
|
||
### Enroll (menu or CLI)
|
||
|
||
**Shipped #55:** System › Fingerprint (self-gated when `fprintd-list` is
|
||
on PATH) — Enroll / List / Verify / Delete all, plus **Use for login**
|
||
which writes `settings.fingerprint.pam` and applies on the next
|
||
`sys-rebuild` (option default follows theme-state.json).
|
||
|
||
```sh
|
||
# CLI still works:
|
||
fprintd-enroll
|
||
fprintd-list "$USER"
|
||
# or: System › Fingerprint › Use for login (on) → sys-rebuild
|
||
```
|
||
|
||
PAM stays opt-in on purpose: password-only remains the cautious default
|
||
until a finger is enrolled. Full enroll on a real reader is V3/hardware.
|
||
|
||
### Doctor
|
||
|
||
`nomarchy-doctor` reports fprintd unit + enroll status when present.
|
||
|
||
## 6. NVIDIA (deep dive)
|
||
|
||
### What happens at install
|
||
|
||
```
|
||
lspci → NVIDIA ⇒ MODULE common-gpu-nvidia
|
||
```
|
||
|
||
That is the **entire** Nomarchy surface. Unfree packages are allowed
|
||
(`allowUnfree = true` in the module and in `mkFlake`), so the proprietary
|
||
path from nixos-hardware can evaluate.
|
||
|
||
There is **no** `nomarchy.hardware.nvidia.*` for:
|
||
|
||
- hybrid / PRIME (Intel+NVIDIA, AMD+NVIDIA)
|
||
- open vs closed kernel module
|
||
- power management / udev / suspend quirks
|
||
- CUDA / container toolkit packages
|
||
|
||
### What a hybrid laptop user must do today
|
||
|
||
1. Confirm `common-gpu-nvidia` (and often `common-gpu-intel` or
|
||
`common-gpu-amd`) are in `hardwareProfile`.
|
||
2. Read the relevant nixos-hardware module and [NixOS NVIDIA wiki](https://wiki.nixos.org/wiki/Nvidia).
|
||
3. Add plain NixOS options in `system.nix`, for example (illustrative —
|
||
hardware-specific):
|
||
|
||
```nix
|
||
# Example only — verify against your generation and nixos-hardware module.
|
||
# hardware.nvidia.prime = { ... };
|
||
# hardware.nvidia.powerManagement.enable = true;
|
||
# hardware.nvidia.open = false; # or true for open modules on newer cards
|
||
```
|
||
|
||
4. Rebuild the system. Home Manager does not own the driver.
|
||
|
||
### Live ISO note
|
||
|
||
The ISO lists `nouveau` among *available* initrd modules and does **not**
|
||
force-load every GPU driver (avoids multi-driver panics). Proprietary
|
||
NVIDIA on the live session is not the product focus; installed systems
|
||
use the profile.
|
||
|
||
**Product direction (shipped #59):** when `common-gpu-nvidia` is in
|
||
`hardwareProfile`, the installer emits a **commented** `system.nix` block
|
||
with PRIME / power / open-module pointers (same pattern as ROCm / NPU
|
||
comments). A full `nomarchy.hardware.nvidia.*` stack stays optional and
|
||
needs a maintainer + hardware-queue coverage.
|
||
|
||
## 7. Day-2: “my laptop is mostly fine, make it fully fine”
|
||
|
||
| Goal | How | Rebuild? |
|
||
|------|-----|----------|
|
||
| Power profile (perf/balanced/saver) | System menu / Waybar | No (PPD D-Bus) |
|
||
| Charge limit 80% | Menu / `settings.power.batteryChargeLimit` | System (sysfs apply is separate backlog) |
|
||
| Thermald (Intel) | Installer on for Intel laptops; else `power.thermal.enable` | System |
|
||
| Fingerprint enroll | `fprintd-enroll` | No |
|
||
| Fingerprint login | `fingerprint.pam = true` | System |
|
||
| ROCm / Intel compute | Uncomment opt-ins in `system.nix` | System (large) |
|
||
| NPU driver | Uncomment `npu` (+ often `latestKernel`) | System; userspace BYO |
|
||
| Newer kernel for brand-new silicon | `nomarchy.hardware.latestKernel = true` | System |
|
||
| Hide IR “dark camera” | Installer or `camera.hideIrSensor` | System |
|
||
| Firmware | `fwupdmgr update` | Reboot if capsule requires |
|
||
| Model quirks missing | Set better `hardwareProfile` (see §8) | System |
|
||
| OpenRGB / printing / Steam | `nomarchy.services.*` | System |
|
||
|
||
Theme switches never touch drivers (Home Manager only).
|
||
|
||
## 8. Unsupported or unlisted machines
|
||
|
||
### Still good floor
|
||
|
||
Even with **no** DMI hit you usually get:
|
||
|
||
- `common-cpu-{intel,amd}`
|
||
- `common-gpu-{intel,amd,nvidia}` as applicable
|
||
- `common-pc` or `common-pc-laptop` + optional `common-pc-ssd`
|
||
- `nomarchy.hardware.intel` or `.amd` when vendor matches
|
||
- Layer A (firmware, audio, BT, PPD, fwupd)
|
||
|
||
You **lose** model-specific EC/suspend/keyboard/audio quirks that only
|
||
exist in a named nixos-hardware module.
|
||
|
||
### Pick a profile after install
|
||
|
||
1. List candidates:
|
||
|
||
```sh
|
||
nix eval github:NixOS/nixos-hardware#nixosModules \
|
||
--apply builtins.attrNames
|
||
# or: the ISO ships hardware-modules.txt for the same list
|
||
```
|
||
|
||
2. Set in your flake (installer already uses a list):
|
||
|
||
```nix
|
||
hardwareProfile = [
|
||
"common-cpu-amd"
|
||
"common-gpu-amd"
|
||
"common-pc-laptop"
|
||
"common-pc-ssd"
|
||
"lenovo-thinkpad-t14-amd-gen3" # if it matches
|
||
];
|
||
```
|
||
|
||
3. `sudo nixos-rebuild switch --flake ~/.nomarchy#default`
|
||
|
||
### Template / migration (no installer)
|
||
|
||
See [MIGRATION.md](MIGRATION.md): reuse `hardware-configuration.nix`, set
|
||
`hardwareProfile`, uncomment `nomarchy.hardware` / power in `system.nix`.
|
||
Post-install re-probe (**shipped #58**):
|
||
|
||
```sh
|
||
nomarchy-detect-hw # human report + suggested snippets
|
||
nomarchy-detect-hw --raw # MODULE / NOMARCHY / DETAIL protocol lines
|
||
```
|
||
|
||
Prints suggested `hardwareProfile` and `system.nix` lines; **does not**
|
||
rewrite the flake. Paste after review, then `sudo nixos-rebuild switch`.
|
||
|
||
## 9. Adding your model to the distro
|
||
|
||
For contributors (and power users who will PR):
|
||
|
||
1. On the machine:
|
||
|
||
```sh
|
||
cat /sys/class/dmi/id/sys_vendor
|
||
cat /sys/class/dmi/id/product_name
|
||
```
|
||
|
||
2. Find a matching attr in
|
||
[nixos-hardware](https://github.com/NixOS/nixos-hardware) (or add one
|
||
upstream first).
|
||
|
||
3. Append to `pkgs/nomarchy-install/hardware-db.sh` in `HARDWARE_DB`:
|
||
|
||
```bash
|
||
"VendorRegex|Product regex|nixos-hardware-module-name"
|
||
```
|
||
|
||
First match wins — put specific lines above broad fallbacks.
|
||
|
||
4. Verify the name exists in the **pinned** nixos-hardware input
|
||
(`mkFlake` will throw if not). A CI check that every DB name ∈
|
||
`nixosModules` is queued so lock bumps cannot silently break installs.
|
||
|
||
5. Optional: note on-hardware QA steps in `agent/HARDWARE-QUEUE.md`.
|
||
|
||
## 10. Doctor and hardware health (current vs target)
|
||
|
||
**Today** (`nomarchy-doctor`): failed units, disk space, theme-state
|
||
validity/git, generation age, snapper timer. **No** Wi‑Fi, GPU, fwupd,
|
||
or fingerprint checks.
|
||
|
||
**Target checks** (queued, all read-only, each failure prints one fix
|
||
command — same doctor contract):
|
||
|
||
| Check | Pass condition | Suggested fix line |
|
||
|-------|----------------|--------------------|
|
||
| NetworkManager | device connected or wifi radio on | open System › Network |
|
||
| Audio sink | default sink exists | System › Audio |
|
||
| GPU accel | `glxinfo`/`vainfo` smoke (if installed) | check `hardwareProfile` / drivers |
|
||
| Fingerprint | if USB VID matched / fprintd unit | `fprintd-enroll` or enable option |
|
||
| fwupd | daemon active; optional “updates pending” warn | `fwupdmgr get-updates` |
|
||
| Battery threshold | if laptop + limit set, sysfs writable | power docs |
|
||
|
||
## 11. Option quick reference
|
||
|
||
Full tables: [README § options](../README.md). Hardware-shaped surface:
|
||
|
||
| Option | Role |
|
||
|--------|------|
|
||
| `mkFlake.hardwareProfile` | nixos-hardware name or list |
|
||
| `nomarchy.hardware.intel.enable` / `.guc` / `.computeRuntime` | Intel gap layer |
|
||
| `nomarchy.hardware.amd.enable` / `.pstate` / `.vaapi` / `.rocm.*` | AMD gap layer |
|
||
| `nomarchy.hardware.fingerprint.enable` / `.pam` | fprintd + PAM |
|
||
| `nomarchy.hardware.npu.enable` | in-kernel NPU only |
|
||
| `nomarchy.hardware.latestKernel` | `linuxPackages_latest` |
|
||
| `nomarchy.hardware.camera.hideIrSensor` / `.irMatch` | dual-sensor webcams |
|
||
| `nomarchy.hardware.i2c.enable` / `.ddcci` | I2C + external backlight |
|
||
| `nomarchy.system.power.*` | PPD/TLP, laptop, thermald, charge limit |
|
||
| `nomarchy.system.bluetooth.enable` | BT stack |
|
||
| `services.fwupd.enable` | LVFS (native NixOS, default on) |
|
||
|
||
## 12. Ease summary
|
||
|
||
| Situation | Effort |
|
||
|-----------|--------|
|
||
| Known model in DB (Framework, many ThinkPads, …) | Low — install and go |
|
||
| Unknown modern Intel/AMD laptop | Low–medium — commons cover a lot |
|
||
| Firmware updates | Medium — CLI only until product work lands |
|
||
| Fingerprint for login | Medium — enroll CLI + PAM uncomment |
|
||
| Hybrid NVIDIA | High — plain NixOS/wiki territory |
|
||
| ROCm / NPU userspace | High — opt-in + expert |
|
||
| Contribute a new DMI line | Medium for someone who can PR |
|
||
|
||
## 13. Related files
|
||
|
||
| Path | Role |
|
||
|------|------|
|
||
| `modules/nixos/hardware.nix` | `nomarchy.hardware.*` |
|
||
| `modules/nixos/power.nix` | PPD/TLP, charge limit, thermald |
|
||
| `modules/nixos/default.nix` | firmware, fwupd, ddcci default |
|
||
| `pkgs/nomarchy-install/hardware-db.sh` | DMI DB + probes |
|
||
| `pkgs/nomarchy-install/nomarchy-install.sh` | writes flake + system.nix |
|
||
| `lib.nix` | `hardwareProfile` resolution |
|
||
| `templates/downstream/system.nix` | commented opt-ins |
|
||
| `agent/HARDWARE-QUEUE.md` | on-machine V3 checks |
|