nixos/modules/services/hardware/display.md

   1 # Customizing display configuration {#module-hardware-display}
   2
   3 This section describes how to customize display configuration using:
   4 - kernel modes
   5 - EDID files
   6
   7 Example situations it can help you with:
   8 - display controllers (external hardware) not advertising EDID at all,
   9 - misbehaving graphics drivers,
  10 - loading custom display configuration before the Display Manager is running,
  11
  12 ## Forcing display modes {#module-hardware-display-modes}
  13
  14 In case of very wrong monitor controller and/or video driver combination you can
  15 [force the display to be enabled](https://mjmwired.net/kernel/Documentation/fb/modedb.txt#41)
  16 and skip some driver-side checks by adding `video=<OUTPUT>:e` to `boot.kernelParams`.
  17 This is exactly the case with [`amdgpu` drivers](https://gitlab.freedesktop.org/drm/amd/-/issues/615#note_1987392)
  18
  19 ```nix
  20 {
  21   # force enabled output to skip `amdgpu` checks
  22   hardware.display.outputs."DP-1".mode = "e";
  23   # completely disable output no matter what is connected to it
  24   hardware.display.outputs."VGA-2".mode = "d";
  25
  26   /* equals
  27   boot.kernelParams = [ "video=DP-1:e" "video=VGA-2:d" ];
  28   */
  29 }
  30 ```
  31
  32 ## Crafting custom EDID files {#module-hardware-display-edid-custom}
  33
  34 To make custom EDID binaries discoverable you should first create a derivation storing them at
  35 `$out/lib/firmware/edid/` and secondly add that derivation to `hardware.display.edid.packages` NixOS option:
  36
  37 ```nix
  38 {
  39   hardware.display.edid.packages = [
  40     (pkgs.runCommand "edid-custom" {} ''
  41        mkdir -p $out/lib/firmware/edid
  42        base64 -d > "$out/lib/firmware/edid/custom1.bin" <<'EOF'
  43        <insert your base64 encoded EDID file here `base64 < /sys/class/drm/card0-.../edid`>
  44        EOF
  45        base64 -d > "$out/lib/firmware/edid/custom2.bin" <<'EOF'
  46        <insert your base64 encoded EDID file here `base64 < /sys/class/drm/card1-.../edid`>
  47        EOF
  48     '')
  49   ];
  50 }
  51 ```
  52
  53 There are 2 options significantly easing preparation of EDID files:
  54 - `hardware.display.edid.linuxhw`
  55 - `hardware.display.edid.modelines`
  56
  57 ## Assigning EDID files to displays {#module-hardware-display-edid-assign}
  58
  59 To assign available custom EDID binaries to your monitor (video output) use `hardware.display.outputs."<NAME>".edid` option.
  60 Under the hood it adds `drm.edid_firmware` entry to `boot.kernelParams` NixOS option for each configured output:
  61
  62 ```nix
  63 {
  64   hardware.display.outputs."VGA-1".edid = "custom1.bin";
  65   hardware.display.outputs."VGA-2".edid = "custom2.bin";
  66   /* equals:
  67   boot.kernelParams = [ "drm.edid_firmware=VGA-1:edid/custom1.bin,VGA-2:edid/custom2.bin" ];
  68   */
  69 }
  70 ```
  71
  72 ## Pulling files from linuxhw/EDID database {#module-hardware-display-edid-linuxhw}
  73
  74 `hardware.display.edid.linuxhw` utilizes `pkgs.linuxhw-edid-fetcher` to extract EDID files
  75 from https://github.com/linuxhw/EDID based on simple string/regexp search identifying exact entries:
  76
  77 ```nix
  78 {
  79   hardware.display.edid.linuxhw."PG278Q_2014" = [ "PG278Q" "2014" ];
  80
  81   /* equals:
  82   hardware.display.edid.packages = [
  83     (pkgs.linuxhw-edid-fetcher.override {
  84       displays = {
  85         "PG278Q_2014" = [ "PG278Q" "2014" ];
  86       };
  87     })
  88   ];
  89   */
  90 }
  91 ```
  92
  93
  94 ## Using XFree86 Modeline definitions {#module-hardware-display-edid-modelines}
  95
  96 `hardware.display.edid.modelines` utilizes `pkgs.edid-generator` package allowing you to
  97 conveniently use [`XFree86 Modeline`](https://en.wikipedia.org/wiki/XFree86_Modeline) entries as EDID binaries:
  98
  99 ```nix
 100 {
 101   hardware.display.edid.modelines."PG278Q_60" = "    241.50   2560 2608 2640 2720   1440 1443 1448 1481   -hsync +vsync";
 102   hardware.display.edid.modelines."PG278Q_120" = "   497.75   2560 2608 2640 2720   1440 1443 1448 1525   +hsync -vsync";
 103
 104   /* equals:
 105   hardware.display.edid.packages = [
 106     (pkgs.edid-generator.overrideAttrs {
 107       clean = true;
 108       modelines = ''
 109         Modeline "PG278Q_60"      241.50   2560 2608 2640 2720   1440 1443 1448 1481   -hsync +vsync
 110         Modeline "PG278Q_120"     497.75   2560 2608 2640 2720   1440 1443 1448 1525   +hsync -vsync
 111       '';
 112     })
 113   ];
 114   */
 115 }
 116 ```
 117
 118 ## Complete example for Asus PG278Q {#module-hardware-display-pg278q}
 119
 120 And finally this is a complete working example for a 2014 (first) batch of [Asus PG278Q monitor with `amdgpu` drivers](https://gitlab.freedesktop.org/drm/amd/-/issues/615#note_1987392):
 121
 122 ```nix
 123 {
 124   hardware.display.edid.modelines."PG278Q_60" = "   241.50   2560 2608 2640 2720   1440 1443 1448 1481   -hsync +vsync";
 125   hardware.display.edid.modelines."PG278Q_120" = "  497.75   2560 2608 2640 2720   1440 1443 1448 1525   +hsync -vsync";
 126
 127   hardware.display.outputs."DP-1".edid = "PG278Q_60.bin";
 128   hardware.display.outputs."DP-1".mode = "e";
 129 }
 130 ```