commit 7e13eda4907d62e61e462e4ce7c7c12ea8d63c6d
parent 3a2f074199e0ec88af33a245dee8bce5866d47c5
Author: Daniel Barlow <dan@telent.net>
Date: Thu, 28 Sep 2023 12:17:30 +0100
add hardware device descriptions to doc
most of the text is recycled and follows no particular format
Diffstat:
9 files changed, 114 insertions(+), 6 deletions(-)
diff --git a/ci.nix b/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 = ''
diff --git a/devices/gl-ar750/default.nix b/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
- - "ath79" soc family
- https://www.gl-inet.com/products/gl-ar750/
+ - 128MB DDR2 RAM
+ - 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
@@ -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, ... }:
diff --git a/devices/gl-mt300a/default.nix b/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, ...}:
diff --git a/devices/gl-mt300n-v2/default.nix b/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;
diff --git a/devices/qemu-aarch64/default.nix b/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 = {
diff --git a/devices/qemu/default.nix b/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 = {
diff --git a/doc/development.rst b/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
==========
diff --git a/doc/hardware.nix b/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}
+
+''
diff --git a/doc/index.rst b/doc/index.rst
@@ -11,6 +11,7 @@ Liminix
admin
development
modules
+ hardware
Indices and tables
