From a9760d239c8d962baf1a671a5003522696448f2d Mon Sep 17 00:00:00 2001 From: Daniel Barlow 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. ''; }; };