From a9760d239c8d962baf1a671a5003522696448f2d Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Thu, 9 Nov 2023 22:43:50 +0000
Subject: [PATCH] basic doc for flashimage installer

---
 ci.nix                 |  7 ++++++-
 modules/flashimage.nix | 27 +++++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/ci.nix b/ci.nix
index 649ef0f..d1a0e4f 100644
--- a/ci.nix
+++ b/ci.nix
@@ -39,6 +39,11 @@ let
                   imports = [ ./modules/all-modules.nix ];
                 };
               }).outputs.optionsJson;
+            installers = map (f: "system.outputs.${f}") [
+              "vmroot"
+              "flashimage"
+            ];
+            inherit (pkgs.lib) concatStringsSep;
         in pkgs.stdenv.mkDerivation {
           name = "liminix-doc";
           nativeBuildInputs = with pkgs; [
@@ -47,7 +52,7 @@ let
           src = ./.;
           buildPhase = ''
             cat ${json} | fennel --correlate doc/parse-options.fnl > doc/modules-generated.rst
-            cat ${json} | fennel --correlate doc/parse-options-outputs.fnl system.outputs.vmroot  > doc/installers-generated.rst
+            cat ${json} | fennel --correlate doc/parse-options-outputs.fnl ${concatStringsSep " " installers}  > doc/installers-generated.rst
             cp ${(import ./doc/hardware.nix)} doc/hardware.rst
             make -C doc html
           '';
diff --git a/modules/flashimage.nix b/modules/flashimage.nix
index a27d499..73967d7 100644
--- a/modules/flashimage.nix
+++ b/modules/flashimage.nix
@@ -28,8 +28,31 @@ in {
     flashimage = mkOption {
       type = types.package;
       description = ''
-        Flashable image for the target device, and the script to
-        install it
+        flashimage
+        **********
+
+        This creates an image called :file:`firmware.bin` suitable for
+        squashfs or jffs2 systems. It can be flashed from U-Boot (if
+        you have a serial console connection), or on some devices from
+        the vendor firmware, or from a Liminix kexecboot system.
+
+        If you are flashing from U-Boot, the file
+        :file:`flash.scr` is a sequence of commands
+        which you can paste at the U-Boot prompt to
+        to transfer the firmware file from a TFTP server and
+        write it to flash. **Please read the script before
+        running it: flash operations carry the potential to
+        brick your device**
+
+        .. NOTE::
+
+           TTL serial connections typically have no form of flow
+           control and so don't always like having massive chunks of
+           text pasted into them - and U-Boot may drop characters
+           while it's busy. So don't necessarily expect to copy-paste
+           the whole of :file:`flash.scr` into a terminal emulator and
+           have it work just like that. You may need to paste each
+           line one at a time, or even retype it.
       '';
     };
   };