From f61e737b546ae0141dc502ddb0513bb5ca93dce0 Mon Sep 17 00:00:00 2001 From: Daniel Barlow Date: Sun, 12 Nov 2023 17:15:58 +0000 Subject: [PATCH] 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 | 24 +++++++++++++++---- devices/gl-ar750/default.nix | 40 ++++++++++++++++++++----------- devices/gl-mt300a/default.nix | 11 +++++++++ devices/gl-mt300n-v2/default.nix | 20 ++++++++++++---- doc/hardware.nix | 2 +- doc/index.rst | 2 +- doc/outputs.rst | 8 +++---- doc/parse-options-outputs.fnl | 16 +++++++++---- modules/outputs.nix | 18 +++++++++++++- modules/outputs/ubimage.nix | 19 +++++++-------- modules/tftpboot.nix | 18 +++++++++++++- 11 files changed, 133 insertions(+), 45 deletions(-) diff --git a/devices/belkin-rt3200/default.nix b/devices/belkin-rt3200/default.nix index 0e8197e0..218bcffb 100644 --- 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 `_ 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 `_ 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 ` 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 index f997097e..c334344d 100644 --- 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 `_ 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 index 1286940a..d7965607 100644 --- 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 index 0198b6cb..21dc336e 100644 --- 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 , 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 index 495eca29..e3ef1380 100644 --- 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 index d474c34a..9632bf6f 100644 --- 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 index e0e8d302..971da157 100644 --- 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 index b61603c8..3738a407 100644 --- 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 index 5e7039d1..8e2fa512 100644 --- 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 index 82963216..3d553e24 100644 --- 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). +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. -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 +.. 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: +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 index 68e83e0c..85e70993 100644 --- 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 `_ 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