nixpkgs/nixos/modules/services/hardware/display.nix

{
  config,
  lib,
  pkgs,
  ...
}:
let
  cfg = config.hardware.display;
in
{
  meta.doc = ./display.md;
  meta.maintainers = with lib.maintainers; [
    nazarewk
  ];

  options = {
    hardware.display.edid.enable = lib.mkOption {
      type = with lib.types; bool;
      default = cfg.edid.packages != null;
      defaultText = lib.literalExpression "config.hardware.display.edid.packages != null";
      description = ''
        Enables handling of EDID files
      '';
    };

    hardware.display.edid.packages = lib.mkOption {
      type = with lib.types; listOf package;
      default = [ ];
      description = ''
        List of packages containing EDID binary files at `$out/lib/firmware/edid`.
        Such files will be available for use in `drm.edid_firmware` kernel
        parameter as `edid/<filename>`.

        You can craft one directly here or use sibling options `linuxhw` and `modelines`.
      '';
      example = lib.literalExpression ''
        [
          (pkgs.runCommand "edid-custom" {} '''
            mkdir -p "$out/lib/firmware/edid"
            base64 -d > "$out/lib/firmware/edid/custom1.bin" <<'EOF'
            <insert your base64 encoded EDID file here `base64 < /sys/class/drm/card0-.../edid`>
            EOF
          ''')
        ]
      '';
      apply =
        list:
        if list == [ ] then
          null
        else
          (pkgs.buildEnv {
            name = "firmware-edid";
            paths = list;
            pathsToLink = [ "/lib/firmware/edid" ];
            ignoreCollisions = true;
          })
          // {
            compressFirmware = false;
          };
    };

    hardware.display.edid.linuxhw = lib.mkOption {
      type = with lib.types; attrsOf (listOf str);
      default = { };
      description = ''
        Exposes EDID files from users-sourced database at https://github.com/linuxhw/EDID

        Attribute names will be mapped to EDID filenames `<NAME>.bin`.

        Attribute values are lists of `awk` regexp patterns that (together) must match
        exactly one line in either of:
        - [AnalogDisplay.md](https://raw.githubusercontent.com/linuxhw/EDID/master/AnalogDisplay.md)
        - [DigitalDisplay.md](https://raw.githubusercontent.com/linuxhw/EDID/master/DigitalDisplay.md)

        There is no universal way of locating your device config, but here are some practical tips:
        1. locate your device:
          - find your model number (second column)
          - locate manufacturer (first column) and go through the list manually
        2. narrow down results using other columns until there is only one left:
          - `Name` column
          - production date (`Made` column)
          - resolution `Res`
          - screen diagonal (`Inch` column)
          - as a last resort use `ID` from the last column
      '';
      example = lib.literalExpression ''
        {
          PG278Q_2014 = [ "PG278Q" "2014" ];
        }
      '';
      apply =
        displays:
        if displays == { } then null else pkgs.linuxhw-edid-fetcher.override { inherit displays; };
    };

    hardware.display.edid.modelines = lib.mkOption {
      type = with lib.types; attrsOf str;
      default = { };
      description = ''
        Attribute set of XFree86 Modelines automatically converted
        and exposed as `edid/<name>.bin` files in initrd.
        See for more information:
        - https://en.wikipedia.org/wiki/XFree86_Modeline
      '';
      example = lib.literalExpression ''
        {
          "PG278Q_60" = "    241.50   2560 2608 2640 2720   1440 1443 1448 1481   -hsync +vsync";
          "PG278Q_120" = "   497.75   2560 2608 2640 2720   1440 1443 1448 1525   +hsync -vsync";
          "U2711_60" = "     241.50   2560 2600 2632 2720   1440 1443 1448 1481   -hsync +vsync";
        }
      '';
      apply =
        modelines:
        if modelines == { } then
          null
        else
          pkgs.edid-generator.overrideAttrs {
            clean = true;
            passthru.config = modelines;
            modelines = lib.trivial.pipe modelines [
              (lib.mapAttrsToList (
                name: value:
                lib.throwIfNot (
                  builtins.stringLength name <= 12
                ) "Modeline name must be 12 characters or less" ''Modeline "${name}" ${value}''
              ))
              (builtins.map (line: "${line}\n"))
              (lib.strings.concatStringsSep "")
            ];
          };
    };

    hardware.display.outputs = lib.mkOption {
      type = lib.types.attrsOf (
        lib.types.submodule ({
          options = {
            edid = lib.mkOption {
              type = with lib.types; nullOr str;
              default = null;
              description = ''
                An EDID filename to be used for configured display, as in `edid/<filename>`.
                See for more information:
                - `hardware.display.edid.packages`
                - https://wiki.archlinux.org/title/Kernel_mode_setting#Forcing_modes_and_EDID
              '';
            };
            mode = lib.mkOption {
              type = with lib.types; nullOr str;
              default = null;
              description = ''
                A `video` kernel parameter (framebuffer mode) configuration for the specific output:

                    <xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]

                See for more information:
                - https://docs.kernel.org/fb/modedb.html
                - https://wiki.archlinux.org/title/Kernel_mode_setting#Forcing_modes
              '';
              example = lib.literalExpression ''
                "e"
              '';
            };
          };
        })
      );
      description = ''
        Hardware/kernel-level configuration of specific outputs.
      '';
      default = { };

      example = lib.literalExpression ''
        {
          edid.modelines."PG278Q_60" = "241.50   2560 2608 2640 2720   1440 1443 1448 1481   -hsync +vsync";
          outputs."DP-1".edid = "PG278Q_60.bin";
          outputs."DP-1".mode = "e";
        }
      '';
    };
  };

  config = lib.mkMerge [
    {
      hardware.display.edid.packages =
        lib.optional (cfg.edid.modelines != null) cfg.edid.modelines
        ++ lib.optional (cfg.edid.linuxhw != null) cfg.edid.linuxhw;

      boot.kernelParams =
        # forcing video modes
        lib.trivial.pipe cfg.outputs [
          (lib.attrsets.filterAttrs (_: spec: spec.mode != null))
          (lib.mapAttrsToList (output: spec: "video=${output}:${spec.mode}"))
        ]
        # selecting EDID for displays
        ++ lib.trivial.pipe cfg.outputs [
          (lib.attrsets.filterAttrs (_: spec: spec.edid != null))
          (lib.mapAttrsToList (output: spec: "${output}:edid/${spec.edid}"))
          (builtins.concatStringsSep ",")
          (p: lib.optional (p != "") "drm.edid_firmware=${p}")
        ];
    }
    (lib.mkIf (cfg.edid.packages != null) {
      # services.udev implements hardware.firmware option
      services.udev.enable = true;
      hardware.firmware = [ cfg.edid.packages ];
    })
  ];
}