basic doc for flashimage installer

This commit is contained in:
Daniel Barlow 2023-11-09 22:43:50 +00:00
parent 5729cfb4a7
commit a9760d239c
2 changed files with 31 additions and 3 deletions

7
ci.nix
View file

@ -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
'';

View file

@ -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.
'';
};
};