From ed2df925d5bc5573be050664343aa370c37694d9 Mon Sep 17 00:00:00 2001
From: Travis Staton <hello@travisstaton.com>
Date: Sat, 11 Mar 2023 13:14:07 -0500
Subject: [PATCH] add config.txt docs

---
 README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

diff --git a/README.md b/README.md
index e1a9cbf..3e30cc2 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,130 @@ partition.
 As noted, the `config.txt` file is generated by the NixOS
 configuration and automatically updated on system activation. 
 
+The relevant nixos option is
+`hardware.raspberry-pi.config`. Configuration is partitioned into
+three sections:
+
+1. Base device tree parameters `base-dt-params`
+2. Device tree overlays `dt-overlays`
+3. Firmware options `options`
+
+Other than that, the format follows pretty closely to the config.txt
+format. For example:
+
+```nix
+hardware.raspberry-pi.config = {
+  cm4 = {
+    options = {
+      otg_mode = {
+        enable = true;
+        value = true;
+      };
+    };
+  };
+  pi4 = {
+    options = {
+      arm_boost = {
+        enable = true;
+        value = true;
+      };
+    };
+    dt-overlays = {
+      vc4-kms-v3d = {
+        enable = true;
+        params = { cma-512 = { enable = true; }; };
+      };
+    };
+  };
+  all = {
+    options = {
+      # The firmware will start our u-boot binary rather than a
+      # linux kernel.
+      kernel = {
+        enable = true;
+        value = "u-boot-rpi-arm64.bin";
+      };
+      arm_64bit = {
+        enable = true;
+        value = true;
+      };
+      enable_uart = {
+        enable = true;
+        value = true;
+      };
+      avoid_warnings = {
+        enable = true;
+        value = true;
+      };
+      camera_auto_detect = {
+        enable = true;
+        value = true;
+      };
+      display_auto_detect = {
+        enable = true;
+        value = true;
+      };
+      disable_overscan = {
+        enable = true;
+        value = true;
+      };
+    };
+    dt-overlays = {
+      vc4-kms-v3d = {
+        enable = true;
+        params = { };
+      };
+    };
+    base-dt-params = {
+      krnbt = {
+        enable = true;
+        value = "on";
+      };
+      spi = {
+        enable = true;
+        value = "on";
+      };
+    };
+  };
+};
+```
+
+generates the following config.txt:
+
+```
+# This is a generated file. Do not edit!
+[all]
+arm_64bit=1
+avoid_warnings=1
+camera_auto_detect=1
+disable_overscan=1
+display_auto_detect=1
+enable_uart=1
+kernel=u-boot-rpi-arm64.bin
+dtparam=krnbt=on
+dtparam=spi=on
+dtoverlay=vc4-kms-v3d
+
+dtoverlay=
+
+[cm4]
+otg_mode=1
+
+[pi4]
+arm_boost=1
+dtoverlay=vc4-kms-v3d
+dtparam=cma-512
+dtoverlay=
+```
+
+If you want to preview the generated `config.txt`, you can find
+it at the path `config.hardware.raspberry-pi.config-output`. For
+example, if you had the above configuration then you could build the
+`config.txt` file with:
+
+```
+nix build '.#nixosConfigurations.rpi-example.config.hardware.raspberry-pi.config-output'
+```
 
 ## Firmware partition implementation notes