commit f61e737b546ae0141dc502ddb0513bb5ca93dce0
parent 262efaabe6abe3debcb3a4520cd4d394052b6e10
Author: Daniel Barlow <dan@telent.net>
Date: Sun, 12 Nov 2023 17:15:58 +0000
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
Diffstat:
11 files changed, 135 insertions(+), 47 deletions(-)
diff --git a/devices/belkin-rt3200/default.nix b/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
- with Liminix: you need to use the `OpenWrt UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to rewrite the partition layout before
- you can flash Liminix onto it (or even use it with "tftpboot",
- if you want the wireless to work).
+ .. note:: The factory flash image contains ECC errors that make it
+ incompatible with Liminix: you need to use the `OpenWrt
+ UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to
+ 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 = {
diff --git a/devices/gl-ar750/default.nix b/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
- supported in Linux using the ath9k driver. The 5GHz support, on the
- 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 Linux is concerned it behaves as one. This is
+ host via `AHB <https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture>`_ and it is
+ supported in Linux using the ath9k driver. 5GHz wifi
+ is provided by a QCA9887 PCIe (PCI embedded) WLAN chip,
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";
diff --git a/devices/gl-mt300a/default.nix b/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/
diff --git a/devices/gl-mt300n-v2/default.nix b/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
- 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.
+ The GL-MT300N-v2 "Mango" is is very similar to the :ref:`MT300A <GL.iNet GL-MT300A>, but is
+ based on the MT7628 chipset instead of MT7620. It's also marginally cheaper
+ and comes in a yellow case not a blue one. Be sure your device is
+ 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/
diff --git a/doc/hardware.nix b/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" ''
diff --git a/doc/index.rst b/doc/index.rst
@@ -12,7 +12,7 @@ Liminix
development
modules
hardware
- installers
+ outputs
Indices and tables
diff --git a/doc/outputs.rst b/doc/outputs.rst
@@ -1,12 +1,12 @@
Outputs
#######
-Liminix *outputs* are artefacts that can be installed or run somehow
-on a target device, or "installers" which run on a target device
-to perform the installation.
+Liminix *outputs* are artefacts that can be installed somehow on a
+target device, or "installers" which run on the target device to
+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.
diff --git a/doc/parse-options-outputs.fnl b/doc/parse-options-outputs.fnl
@@ -2,10 +2,18 @@
;; (local { : view } (require :fennel))
-(local outputs (collect [k v (ipairs arg)]
- (values v true)))
+(fn output? [option]
+ (match option.loc
+ ["system" "outputs" & _] true
+ _ false))
-(each [_ option (ipairs (yaml.load (io.read "*a")))]
- (when (. outputs option.name)
+(fn sorted-options [options]
+ (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)))
diff --git a/modules/outputs.nix b/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;
};
};
};
diff --git a/modules/outputs/ubimage.nix b/modules/outputs/ubimage.nix
@@ -20,18 +20,17 @@ in {
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:
+This output provides a UBIFS filesystem image and a small U-Boot script
+to make the manual installation process very slightly simpler. You will
+need a serial connection and a network connection to a TFTP server
+containing the filesystem image it creates.
+
+.. warning:: 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.
+
+1) determine which MTD device is being used for UBI, and the partition name:
.. code-block:: console
diff --git a/modules/tftpboot.nix b/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
