more doc

modules/outputs/flashimage.nix

@@ -0,0 +1,117 @@
+{
+  config
+, pkgs
+, lib
+, ...
+}:
+let
+  inherit (lib) mkOption types concatStringsSep;
+  inherit (config.boot) tftp;
+in {
+  options.system.outputs = {
+    firmware = mkOption {
+      type = types.package;
+      internal = true;          # component of flashimage
+      description = ''
+        Binary image (combining kernel, FDT, rootfs, initramfs
+        if needed, etc) for the target device.
+      '';
+    };
+    flash-scr = mkOption {
+      type = types.package;
+      internal = true;          # component of flashimage
+      description = ''
+        Copy-pastable U-Boot commands to TFTP download the
+        image and write it to flash
+      '';
+    };
+    flashimage = mkOption {
+      type = types.package;
+      description = ''
+        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.
+      '';
+    };
+  };
+
+  config = {
+    kernel = {
+      config = {
+        MTD_SPLIT_UIMAGE_FW = "y";
+      } // lib.optionalAttrs (pkgs.stdenv.isMips) {
+        # https://stackoverflow.com/questions/26466470/can-the-logical-erase-block-size-of-an-mtd-device-be-increased
+        MTD_SPI_NOR_USE_4K_SECTORS = "n";
+      };
+    };
+
+    programs.busybox.applets = [
+      "flashcp"
+    ];
+
+    system.outputs = {
+      firmware =
+        let
+          o = config.system.outputs;
+          bs = config.hardware.flash.eraseBlockSize;
+        in pkgs.runCommand "firmware" {} ''
+          dd if=${o.uimage} of=$out bs=${bs} conv=sync
+          dd if=${o.rootfs} of=$out bs=${bs} conv=sync,nocreat,notrunc oflag=append
+        '';
+      flashimage =
+        let o = config.system.outputs; in
+        # could use trivial-builders.linkFarmFromDrvs here?
+        pkgs.runCommand "flashimage" {} ''
+          mkdir $out
+          cd $out
+          ln -s ${o.firmware} firmware.bin
+          ln -s ${o.rootfs} rootfs
+          ln -s ${o.kernel} vmlinux
+          ln -s ${o.manifest} manifest
+          ln -s ${o.kernel.headers} build
+          ln -s ${o.uimage} uimage
+          ln -s ${o.dtb} dtb
+          ln -s ${o.flash-scr} flash.scr
+       '';
+
+      flash-scr =
+        let
+          inherit (pkgs.lib.trivial) toHexString;
+          inherit (config.hardware) flash;
+        in
+          pkgs.buildPackages.runCommand "" {} ''
+            imageSize=$(stat -L -c %s ${config.system.outputs.firmware})
+            cat > $out << EOF
+            setenv serverip ${tftp.serverip}
+            setenv ipaddr ${tftp.ipaddr}
+            tftp 0x$(printf %x ${tftp.loadAddress}) result/firmware.bin
+            erase 0x$(printf %x ${flash.address}) +${flash.size}
+            cp.b 0x$(printf %x ${tftp.loadAddress}) 0x$(printf %x ${flash.address}) \''${filesize}
+            echo command line was ${builtins.toJSON (concatStringsSep " " config.boot.commandLine)}
+            EOF
+          '';
+    };
+  };
+}

modules/outputs/ubimage.nix

@@ -0,0 +1,127 @@
+{
+  config
+, pkgs
+, lib
+, ...
+}:
+let
+  inherit (lib) mkIf mkEnableOption mkOption types concatStringsSep;
+  cfg = config.boot.tftp;
+  instructions = pkgs.writeText "env.scr" ''
+    setenv serverip ${cfg.serverip}
+    setenv ipaddr ${cfg.ipaddr}
+    setenv loadaddr ${cfg.loadAddress}
+'';
+in {
+  options.system.outputs = {
+    ubimage = mkOption {
+      type = types.package;
+      description = ''
+ubimage
+*******
+
+First-time installation of a UBIFS Liminix system presently can only
+be done from the U-Boot command line (or from a ramdisk-based recovery
+system: see "kexecboot" but we don't have detailed instructions for
+this process yet).
+
+These steps were tested on a Belkin RT3200 (also known as Linksys
+E8450).  Other devices may be set up differently, so use them as
+inspiration and don't just paste them blindly. Consult the Liminix
+manual for how to connect a serial cable to your device and get into
+U-Boot
+
+1) determine which MTD device is being used for UBI and the partition name:
+
+.. code-block:: console
+
+    uboot>  ubi part
+    Device 0: ubi0, MTD partition ubi
+
+In this case the important value is ``ubi0``
+
+2) list the available volumes and create a new one on which to install Liminix
+
+.. code-block:: console
+
+    uboot> ubi info l
+    [ copious output scrolls past ]
+
+Expect there to be existing volumes and for some or all of them to be
+important. Unless you know what you're doing, don't remove anything
+whose name suggests it's related to uboot, or any kind of backup or
+recovery partition. To see how much space is free:
+
+.. code-block:: console
+
+    uboot> ubi info
+    [ ... ]
+    UBI: available PEBs:             823
+
+Now we can make our new root volume
+
+.. code-block:: console
+
+    uboot> ubi create liminix -
+
+3) transfer the root filesystem from the build system and write it
+to the new volume. Paste the environment variable settings from
+:file:`result/env.scr` into U-Boot, then run
+
+.. code-block:: console
+
+    uboot> tftpboot ''${loadaddr} result/rootfs
+    uboot> ubi write ''${loadaddr} liminix $filesize
+
+Now we have the root filesystem installed on the device. You
+can even mount it and poke around using ``ubifsmount ubi0:liminix;
+ubifsls  /``
+
+4) optional: before you configure the device to boot into Liminix
+automatically, you can try booting it by hand to see if it works:
+
+.. code-block:: console
+
+    uboot> ubifsmount ubi0:liminix
+    uboot> ubifsload ''${loadaddr} boot/uimage
+    uboot> bootm ''${loadaddr}
+
+Once you've done this and you're happy with it, reset the device to
+U-Boot. You don't need to recreate the volume but you do need to
+repeat step 3.
+
+5) Instructions for configuring autoboot are likely to be very
+device-dependent. On the Linksys E8450/Belkin RT3200, the environment
+variable `boot_production` governs what happens on a normal boot, so
+you could do
+
+.. code-block:: console
+
+    uboot> setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix; ubifsload ''${loadaddr} boot/uimage; bootm ''${loadaddr}'
+
+On other devices, some detective work may be needed. Try running
+`printenv` and look for likely commands, try looking at the existing
+boot process, maybe even try looking for documentation for that device.
+
+6) Now you can reboot the device into Liminix
+
+.. code-block:: console
+
+    uboot> reset
+      '';
+    };
+  };
+
+  config = mkIf (config.rootfsType == "ubifs") {
+    system.outputs = {
+      ubimage =
+        let o = config.system.outputs; in
+        pkgs.runCommand "ubimage" {} ''
+          mkdir $out
+          cd $out
+          ln -s ${o.rootfs} rootfs
+          ln -s ${instructions} env.scr
+       '';
+    };
+  };
+}