# Facter Module

> [!NOTE] Only support NVIDIA proprietary drivers today but can include other drivers like AMD or Intel, CPUs and GPUs in the future if needed.

A small NixOS module that uses the hardware report generated by [nixos-facter](https://github.com/numtide/nixos-facter) to automatically select the appropriate proprietary NVIDIA driver.

The module is intended to complement the NVIDIA support already provided by Nixpkgs. It does not replace the existing NixOS NVIDIA module; it only adds automatic driver selection based on the detected PCI device IDs.

## What it does

When imported, the module:

1. Reads the NVIDIA devices from the nix-facter hardware report.
2. Extracts the PCI vendor and device IDs.
3. Matches the device ID against known NVIDIA GPU families.
4. Selects the corresponding driver package from `hardware.nvidia.package`.
5. Enables the required NVIDIA configuration.

No additional enable option is required.

For example:

```nix
{
  imports = [
    inputs.asgard.nixosModules.facter
  ];
}
```

If an NVIDIA GPU is present in the facter report, the appropriate driver is selected automatically.

## Supported driver families

The module currently maps GPUs to the following driver branches:

| Driver       | GPU families            |
| ------------ | ----------------------- |
| `stable`     | Pascal and newer        |
| `legacy_470` | Maxwell and late Kepler |
| `legacy_390` | Fermi and Kepler        |
| `legacy_340` | Tesla                   |

Unknown device IDs default to `stable`.

The device matching is based on the PCI device ID rather than the GPU name. This avoids relying on marketing names and keeps the detection independent of `lspci` output or other runtime tools.

## How it integrates with NixOS

The module uses the existing NixOS NVIDIA package set:

```nix
config.boot.kernelPackages.nvidiaPackages
```

The selected package is then assigned through:

```nix
hardware.nvidia.package
```

using `lib.mkDefault`, so it can still be overridden by the host configuration when necessary.

For example:

```nix
{
  hardware.nvidia.package =
    lib.mkForce config.boot.kernelPackages.nvidiaPackages.stable;
}
```

This is intentional. The module provides a default based on hardware detection, but does not prevent a machine from explicitly choosing a different driver.

## Facter dependency

The module expects the nix-facter report to be available through:

```nix
config.hardware.facter.report
```

and reads NVIDIA PCI devices from:

```nix
config.hardware.facter.report.hardware.pci
```

A device is considered an NVIDIA display controller when:

* the PCI vendor is `0x10de`
* the PCI class starts with `0x03`

This covers both VGA-compatible controllers and 3D controllers.

## Why this exists

Nixpkgs already provides the NVIDIA driver packages and the `hardware.nvidia` module. The missing piece is knowing which legacy branch is appropriate for a given GPU.

This module keeps that logic in one place and makes it possible for a generic NixOS hardware configuration to automatically select a compatible NVIDIA driver.

The intended workflow is:

```text
nixos-facter
      │
      ▼
hardware.facter.report
      │
      ▼
NVIDIA PCI device ID
      │
      ▼
driver family
      │
      ▼
nvidiaPackages.<family>
      │
      ▼
hardware.nvidia
```

## Overrides

Automatic detection is only a default.

If the selected driver is not appropriate for a particular system, the normal NixOS NVIDIA configuration can still be used to override it.

The module can also be disabled explicitly through:

```nix
{
  hardware.facter.detected.graphics.nvidia.enable = false;
}
```

This leaves NVIDIA configuration entirely to the host.

## Scope

This module intentionally does not:

* detect or configure non-NVIDIA GPUs
* configure NVIDIA hardware beyond the existing NixOS module
* select kernels
* configure firmware
* modify Xorg or Wayland beyond the required NVIDIA settings
* provide a custom NVIDIA driver package
* replace nixpkgs' NVIDIA support

It is just the detection and selection layer on top of what NixOS already provides.

## Status

Early development.

The supported PCI ID ranges are maintained against NVIDIA's legacy driver support information. New GPU generations should naturally fall back to `stable` until a specific legacy branch needs to be added.