improve doc for outputs and hardware

Changed my mind about "installer" as a first-class concept, at least
in the current implementation. Not every documented output is an
installer

devices/belkin-rt3200/default.nix

@@ -6,17 +6,31 @@
     This device is based on a 64 bit Mediatek MT7622 ARM platform,
     and is "work in progress" in Liminix.
 
-    The factory flash image contains ECC errors that make it incompatible
+    .. note:: The factory flash image contains ECC errors that make it
-    with Liminix: you need to use the `OpenWrt UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to rewrite the partition layout before
+              incompatible with Liminix: you need to use the `OpenWrt
-    you can flash Liminix onto it (or even use it with "tftpboot",
+              UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to
-    if you want the wireless to work).
+              rewrite the partition layout before you can flash
+              Liminix onto it (or even use it with
+              :ref:`system-outputs-tftpboot`, if you want the wireless
+              to work).
+
+    Hardware summary
+    ================
 
     - MediaTek MT7622BV (1350MHz)
     - 128MB NAND flash
     - 512MB	RAM
     - b/g/n wireless using MediaTek MT7622BV (MT7615E driver)
     - a/n/ac/ax wireless using  MediaTek MT7915E
-  '';
+
+
+    Installation
+    ============
+
+    Installation is currently a manual process (you need a :ref:`serial <serial>` conection and
+    TFTP) following the instructions at :ref:`system-outputs-ubimage`
+
+'';
 
   system = {
     crossSystem = {

devices/gl-ar750/default.nix

@@ -1,4 +1,4 @@
-rec {
+{
   system = {
     crossSystem = {
       config = "mips-unknown-linux-musl";
@@ -13,6 +13,9 @@ rec {
     GL.iNet GL-AR750
     ****************
 
+    Hardware summary
+    ================
+
     The GL-AR750 "Creta" travel router features:
 
      - QCA9531 @650Mhz SoC
@@ -22,28 +25,32 @@ rec {
      - 16MB NOR Flash
      - supported in OpenWrt by the "ath79" SoC family
 
-    As with many GL.iNet devices, the stock vendor firmware
-    is a fork of OpenWrt, meaning that the plain binary
-    ``firmware.bin`` that Liminix builds can be flashed using the
-    vendor web UI and the U-Boot emergency "unbrick" routine
-
     The GL-AR750 has two distinct sets of wifi hardware. The 2.4GHz
     radio is part of the QCA9531 SoC, i.e. it's on the same silicon as
     the CPU, the Ethernet, the USB etc. The device is connected to the
-    host via AHB, the "Advanced High-Performance Bus" and it is
+    host via `AHB <https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture>`_ and it is
-    supported in Linux using the ath9k driver. The 5GHz support, on the
+    supported in Linux using the ath9k driver. 5GHz wifi
-    other hand, is provided by a QCA9887 PCIe (PCI embedded) WLAN chip:
+    is provided by a QCA9887 PCIe (PCI embedded) WLAN chip,
-    I haven't looked closely at the router innards to see if this is
-    actually physically a separate board that could be unplugged, but
-    as far as Linux is concerned it behaves as one. This is
     supported by the ath10k driver.
 
+    Installation
+    ============
+
+    As with many GL.iNet devices, the stock vendor firmware
+    is a fork of OpenWrt, meaning that the binary created by
+    :ref:`system-outputs-flashimage` can be flashed using the
+    vendor web UI or the U-Boot emergency "unbrick" routine.
+
+    For flashing from an existing Liminix system (we believe that) it
+    is necessary to first boot into a :ref:`system-outputs-kexecboot`
+    system, otherwise you'll be overwriting flash partitions while
+    they're in use - and that might not end well.
+
     Vendor web page: https://www.gl-inet.com/products/gl-ar750/
 
     OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-ar750
 
   '';
-  installer = "flashimage";
 
   module = {pkgs, config, ... }:
     let
@@ -95,7 +102,7 @@ rec {
         FEATURE_DD_IBS_OBS = "y"; # ath10k_cal_data needs skip_bytes,fullblock
       };
       hardware = {
-        defaultOutput = installer;
+        defaultOutput = "flashimage";
         loadAddress = "0x80060000";
         entryPoint  = "0x80060000";
         flash = {
@@ -145,9 +152,14 @@ rec {
           url = "https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.15.71.tar.gz";
           hash = "sha256-yhO2cXIeIgUxkSZf/4aAsF11uxyh+UUZu6D1h92vCD8=";
         };
+
+        # Mainline linux 5.19 doesn't have device-tree support for
+        # this device or even for the SoC, so we use the extensive
+        # OpenWrt kernel patches
         extraPatchPhase = ''
           ${openwrt.applyPatches.ath79}
         '';
+
         config = {
           ATH79 = "y";
           PCI = "y";

devices/gl-mt300a/default.nix

@@ -25,6 +25,17 @@
     - assuming we want to use the wireless - we need to build MTD
     support into the kernel even if we're using TFTP root.
 
+    Installation
+    ============
+
+    The stock vendor firmware is a fork of OpenWrt, meaning that the
+    binary created by :ref:`system-outputs-flashimage` can be flashed
+    using the vendor web UI or the U-Boot emergency "unbrick" routine.
+
+    For flashing from an existing Liminix system (we think) it
+    is necessary to first boot into a :ref:`system-outputs-kexecboot`
+    system, otherwise you'll be overwriting flash partitions while
+    they're in use - and that might not end well.
 
     Vendor web page: https://www.gl-inet.com/products/gl-mt300a/
 

devices/gl-mt300n-v2/default.nix

@@ -13,10 +13,22 @@
     GL.iNet GL-MT300N-v2
     ********************
 
-    The GL-MT300N-v2 "Mango" is is very similar to the MT300A, but is
+    The GL-MT300N-v2 "Mango" is is very similar to the :ref:`MT300A <GL.iNet GL-MT300A>, but is
-    based on MT7628 instead of MT7620.  It's also marginally cheaper
+    based on the MT7628 chipset instead of MT7620.  It's also marginally cheaper
-    and comes in a yellow case not a blue one.  It's different again
+    and comes in a yellow case not a blue one.  Be sure your device is
-    to the v1, which has only half the RAM.
+    v2 not v1, which is a different animal and has only half as much RAM.
+
+    Installation
+    ============
+
+    The stock vendor firmware is a fork of OpenWrt, meaning that the
+    binary created by :ref:`system-outputs-flashimage` can be flashed
+    using the vendor web UI or the U-Boot emergency "unbrick" routine.
+
+    For flashing from an existing Liminix system (we think) it
+    is necessary to first boot into a :ref:`system-outputs-kexecboot`
+    system, otherwise you'll be overwriting flash partitions while
+    they're in use - and that might not end well.
 
     Vendor web page: https://www.gl-inet.com/products/gl-mt300n-v2/
 

doc/hardware.nix

@@ -16,7 +16,7 @@ let
             :ref:`system-outputs-${d.installer}`
           ''
           else "";
-    in (d'.description + installer))
+    in d'.description)
     devices;
 in
 writeText "hwdoc" ''

doc/index.rst

@@ -12,7 +12,7 @@ Liminix
    development
    modules
    hardware
-   installers
+   outputs
 
 
 Indices and tables

doc/outputs.rst

@@ -1,12 +1,12 @@
 Outputs
 #######
 
-Liminix *outputs* are artefacts that can be installed or run somehow
+Liminix *outputs* are artefacts that can be installed somehow on a
-on a target device, or "installers" which run on a target device
+target device, or "installers" which run on the target device to
-to perform the installation.
+perform the installation.
 
 There are different outputs because different target devices need
-different artefacts or have different ways to get that artefact
+different artefacts, or have different ways to get that artefact
 installed. The options available for a particular device are described in
 the section for that device.
 

doc/parse-options-outputs.fnl

@@ -2,10 +2,18 @@
 
 ;; (local { : view } (require :fennel))
 
-(local outputs (collect [k v (ipairs arg)]
+(fn output? [option]
-                 (values v true)))
+  (match option.loc
+    ["system" "outputs" & _] true
+    _ false))
 
-(each [_ option (ipairs (yaml.load (io.read "*a")))]
+(fn sorted-options [options]
-  (when (. outputs option.name)
+  (table.sort
+   options
+   (fn [a b] (< a.name b.name)))
+  options)
+
+(each [_ option (ipairs (sorted-options (yaml.load (io.read "*a"))))]
+  (when (and (output? option) (not option.internal))
     (print (.. ".. _" (string.gsub option.name "%." "-") ":") "\n")
     (print option.description)))

modules/outputs.nix

@@ -17,26 +17,42 @@ in
   ];
   options = {
     system.outputs = {
+      # the convention here is to mark an output as "internal" if
+      # it's not a complete system (kernel plus userland, or installer)
+      # but only part of one.
       kernel = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          kernel
+          ******
+
           Kernel vmlinux file (usually ELF)
         '';
       };
       dtb = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          dtb
+          ***
+
           Compiled device tree (FDT) for the target device
         '';
       };
       uimage = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
+          uimage
+          ******
+
           Combined kernel and FDT in uImage (U-Boot compatible) format
         '';
       };
       manifest = mkOption {
         type = types.package;
+        internal  = true;
         description = ''
           Debugging aid. JSON rendition of config.filesystem, on
           which can run "nix-store -q --tree" on it and find
@@ -45,10 +61,10 @@ in
       };
       rootfs = mkOption {
         type = types.package;
+        internal = true;
         description = ''
           root filesystem (squashfs or jffs2) image
         '';
-        internal = true;
       };
     };
   };

modules/outputs/ubimage.nix

@@ -20,18 +20,17 @@ in {
 ubimage
 *******
 
-First-time installation of a UBIFS Liminix system presently can only
+This output provides a UBIFS filesystem image and a small U-Boot script
-be done from the U-Boot command line (or from a ramdisk-based recovery
+to make the manual installation process very slightly simpler. You will
-system: see "kexecboot" but we don't have detailed instructions for
+need a serial connection and a network connection to a TFTP server
-this process yet).
+containing the filesystem image it creates.
 
-These steps were tested on a Belkin RT3200 (also known as Linksys
+.. warning:: These steps were tested on a Belkin RT3200 (also known as
-E8450).  Other devices may be set up differently, so use them as
+             Linksys E8450).  Other devices may be set up differently,
-inspiration and don't just paste them blindly. Consult the Liminix
+             so use them as inspiration and don't just paste them
-manual for how to connect a serial cable to your device and get into
+             blindly.
-U-Boot
 
-1) determine which MTD device is being used for UBI and the partition name:
+1) determine which MTD device is being used for UBI, and the partition name:
 
 .. code-block:: console
 

modules/tftpboot.nix

@@ -17,11 +17,27 @@ in {
     tftpboot = mkOption {
       type = types.package;
       description = ''
-        Directory containing files needed for TFTP booting
+        tftpboot
+        ********
+
+        This output is intended for developing on a new device.
+        It assumes you have a serial connection and a
+        network connection to the device and that your
+        build machine is running a TFTP server.
+
+        The output is a directory containing kernel and
+        root filesystem image, and a script :file:`boot.scr` of U-Boot
+        commands that will load the images into memory and
+        run them directly,
+        instead of first writing them to flash. This saves
+        time and erase cycles.
+
+        It uses the Linux `phram <https://github.com/torvalds/linux/blob/master/drivers/mtd/devices/phram.c>`_ driver to emulate a flash device using a segment of physical RAM.
       '';
     };
     boot-scr = mkOption {
       type = types.package;
+      internal = true;
       description = ''
         U-Boot commands to load and boot a kernel and rootfs over TFTP.
         Copy-paste into the device boot monitor