add hardware device descriptions to doc

most of the text is recycled and follows no particular format

ci.nix

@@ -40,6 +40,7 @@ let
         buildPhase = ''
           cat ${(import ./doc/extract-options.nix).doc} > options.json
           cat options.json | fennel --correlate parse-options.fnl > modules-generated.rst
+          cp ${(import ./doc/hardware.nix)} hardware.rst
           make html
         '';
         installPhase = ''

devices/gl-ar750/default.nix

@@ -18,13 +18,22 @@
   };
 
   description = ''
-    GL.INet GL-AR750 "Creta" travel router
+    GL.INet GL-AR750
+    ****************
+
+    The GL-AR750 "Creta" travel router features:
+
      - QCA9531 @650Mhz SoC
      - dual band wireless: IEEE 802.11a/b/g/n/ac
      - two 10/100Mbps LAN ports and one WAN
-     - 128MB DDR2 RAM / 16MB  NOR Flash
+     - 128MB DDR2 RAM
-     - "ath79" soc family
+     - 16MB NOR Flash
-    https://www.gl-inet.com/products/gl-ar750/
+     - 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
@@ -34,8 +43,13 @@
     other hand, 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 the Linux is concerned it behaves as one. This is
+    as far as Linux is concerned it behaves as one. This is
     supported by the ath10k driver.
+
+    Vendor web page: https://www.gl-inet.com/products/gl-ar750/
+
+    OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-ar750
+
   '';
 
   module = {pkgs, config, ... }:

devices/gl-mt300a/default.nix

@@ -12,10 +12,41 @@
   };
 
   description = ''
+    GL.Inet GL-MT300A
+    ********************
+
+    The GL-MT300A is based on a MT7620 chipset.
+
+    The GL-Inet pocket router range makes nice cheap hardware for
+    playing with Liminix or similar projects. The manufacturers seem
+    open to the DIY market, and the devices have a reasonable amount
+    of RAM and are much easier to get serial connections than many
+    COTS routers.
+
+    Wire up the serial connection: this probably involves opening
+    the box, locating the serial header pins (TX, RX and GND) and
+    connecting a USB TTL converter - e.g. a PL2303 based device - to
+    it. The defunct OpenWRT wiki has a guide with some pictures. (If
+    you don't have a USB TTL converter to hand, other options are
+    available. For example, use the GPIO pins on a Raspberry Pi.)
+
+    Run a terminal emulator such as Minicom on whatever is on the
+    other end of the link. I use 115200 8N1 and find it also helps
+    to set "Line tx delay" to 1ms, "backspace sends DEL" and
+    "lineWrap on".
+
+    When you turn the router on you should be greeted with some
+    messages from U-Boot and a little bit of ASCII art, followed by
+    the instruction to hit SPACE to stop autoboot. Do this and you
+    will get a gl-mt300a> prompt.
+
+    For flashing from uboot, the firmware partition is from
+    0xbc050000 to 0xbcfd0000.
+
     WiFi on this device is provided by the rt2800soc module. It
     expects firmware to be present in the "factory" MTD partition, so
     - assuming we want to use the wireless - we need to build MTD
-    support into the kernel even if we're using TFTP root
+    support into the kernel even if we're using TFTP root.
   '';
 
   module = { pkgs, config, lib, ...}:

devices/gl-mt300n-v2/default.nix

@@ -11,6 +11,16 @@
     };
   };
 
+  description = ''
+    GL.Inet GL-MT300N-v2
+    ********************
+
+    The GL-MT300N-v2 "Mango" is is very similar to the MT300A, but is
+    based on MT7628 instead of MT7620.  It's also marginally cheaper
+    and comes in a yellow case not a blue one.  It's different again
+    to the v1, which has only half the RAM.
+  '';
+
   module = { pkgs, config, lib, ...}:
     let
       inherit (pkgs.liminix.networking) interface;

devices/qemu-aarch64/default.nix

@@ -9,6 +9,10 @@
     };
   };
 
+  # this device is described by the "qemu" device
+  description = "";
+
+
   module = {pkgs, config, ... }: {
     imports = [ ../../modules/arch/aarch64.nix ];
     kernel = {

devices/qemu/default.nix

@@ -12,6 +12,33 @@
     };
   };
 
+  description = ''
+    QEMU
+    ****
+
+    This is not a hardware device. This target produces an image for
+    QEMU, the "generic and open source machine emulator and
+    virtualizer".
+
+    Liminix can build QEMU for both MIPS (:code:`qemu` device) and Aarch64 (:code:`qemu-aarch64` device)
+
+    MIPS QEMU emulates a "Malta" board, which was an ATX form factor
+    evaluation board made by MIPS Technologies, but mostly in Liminix
+    we use paravirtualized devices (Virtio) instead of emulating
+    hardware. For Aarch64 we use the QEMU "virt" board.
+
+    Building an image for QEMU results in a :file:`result/` directory
+    containing ``run.sh`` ``vmlinux``, ``rootfs`` and possibly
+    (architecture-dependent) ``Image``. To invoke the emulator,
+    run ``run.sh``.
+
+    The configuration includes two emulated "hardware" ethernet
+    devices and the kernel :code:`mac80211_hwsim` module to
+    provide an emulated wlan device. To read more about how
+    to connect to this network, refer to :ref:`qemu-networking`
+    in the Development manual.
+
+  '';
   module = {pkgs, config, ... }: {
     imports = [ ../../modules/arch/mipseb.nix ];
     kernel = {

doc/development.rst

@@ -41,6 +41,8 @@ that directory for console and monitor.  Use :command:`connect-vm`
 (also in the ``buildEnv`` environment) to connect to either of these
 sockets, and ^O to disconnect.
 
+.. _qemu-networking:
+
 Networking
 ==========
 

doc/hardware.nix

@@ -0,0 +1,18 @@
+with import <nixpkgs> {} ;
+
+let
+  devices =
+    builtins.readDir ../devices;
+  texts = lib.mapAttrsToList (n: t:
+    let d = import  ../devices/${n}/default.nix;
+        d' = { description = "no description for ${n}"; } // d;
+    in d'.description )
+    devices;
+in
+writeText "hwdoc" ''
+  Supported hardware
+  ##################
+
+  ${lib.concatStringsSep "\n\n" texts}
+
+''

doc/index.rst

@@ -11,6 +11,7 @@ Liminix
    admin
    development
    modules
+   hardware
 
 
 Indices and tables