From 4bdd30b58d978b48aa0063eb5ecb8124eb3e8891 Mon Sep 17 00:00:00 2001 From: Daniel Barlow Date: Thu, 18 Sep 2025 21:58:26 +0100 Subject: [PATCH] convert all the hardware docs to adoc --- devices/belkin-rt3200/default.nix | 171 ++++++++++----------- devices/gl-ar750/default.nix | 59 ++++---- devices/gl-mt300a/default.nix | 40 +++-- devices/gl-mt300n-v2/default.nix | 33 ++-- devices/openwrt-one/default.nix | 105 +++++++------ devices/qemu-aarch64/default.nix | 16 +- devices/qemu-armv7l/default.nix | 17 +-- devices/qemu/default.nix | 30 ++-- devices/tp-archer-ax23/default.nix | 27 ++-- devices/turris-omnia/default.nix | 234 +++++++++++++++-------------- devices/zyxel-nwa50ax/default.nix | 121 ++++++++------- doc.nix | 2 +- doc/hardware.nix | 5 +- doc/index.adoc | 2 +- 14 files changed, 426 insertions(+), 436 deletions(-) diff --git a/devices/belkin-rt3200/default.nix b/devices/belkin-rt3200/default.nix index 4d528fc..e135a7c 100644 --- a/devices/belkin-rt3200/default.nix +++ b/devices/belkin-rt3200/default.nix @@ -1,112 +1,107 @@ { description = '' - Belkin RT-3200 / Linksys E8450 - ****************************** - This device is based on a 64 bit Mediatek MT7622 ARM platform, - and is mostly feature-complete in Liminix but as of Dec 2024 - has seen very little actual use. +== Belkin RT-3200 / Linksys E8450 - Hardware summary - ================ +This device is based on a 64 bit Mediatek MT7622 ARM platform, and has +been powering my (Daniel's) home network since February 2025. - - 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 +=== 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 - Liminix on this device uses the UBI volume management system to - perform wear leveling on the flash. This is not set up from the - factory, so a one-time step is needed to prepare it before Liminix - can be installed. +Liminix on this device uses the UBI volume management system to perform +wear leveling on the flash. This is not set up from the factory, so a +one-time step is needed to prepare it before Liminix can be installed. +==== Preparation - Preparation - ----------- +To prepare the device for Liminix you first need to use the +https://github.com/dangowrt/owrt-ubi-installer[OpenWrt UBI Installer] +image to rewrite the flash layout. As of Jan 2025 there are two versions +of the installer available: the release version 1.0.2 and the +pre-release 1.1.3 and for Liminix you nee the pre-release. The release +version of the installer creates UBI volumes according to an older +layout that is not compatible with the Linux 6.6.67 kernel used in +Liminix. - To prepare the device for Liminix you first need to use the - `OpenWrt UBI Installer - `_ image to - rewrite the flash layout. As of Jan 2025 there are two versions - of the installer available: the release version 1.0.2 and the - pre-release 1.1.3 and for Liminix you nee the pre-relese. - The release version of the installer creates UBI volumes - according to an older layout that is not compatible with - the Linux 6.6.67 kernel used in Liminix. +You can run the installer in one of two ways: either follow the +instructions to do it through the vendor web interface, or you can drop +to U-Boot and use TFTP - You can run the installer in one of two ways: - either follow the instructions to do it through the vendor web - interface, or you can drop to U-Boot and use TFTP +[source,console] +---- +MT7622> setenv ipaddr 10.0.0.6 +MT7622> setenv serverip 10.0.0.1 +MT7622> tftpboot 0x42000000 openwrt-mediatek-mt7622-linksys_e8450-ubi-initramfs-recovery-installer.itb +MT7622> bootm 0x42000000 +---- - .. code-block:: console +This will write the new flash layout and then boot into a "recovery" +OpenWrt installation. - MT7622> setenv ipaddr 10.0.0.6 - MT7622> setenv serverip 10.0.0.1 - MT7622> tftpboot 0x42000000 openwrt-mediatek-mt7622-linksys_e8450-ubi-initramfs-recovery-installer.itb - MT7622> bootm 0x42000000 +==== Building/installing Liminix - This will write the new flash layout and then boot into a - "recovery" OpenWrt installation. +The default target for this device is `+outputs.ubimage+` which makes a +ubifs image suitable for use with `+ubiupdatevol+`. To write this to the +device we use the OpenWrt recovery system installed in the previous +step. In this configuration the device assigns itself the IP address +192.168.1.1/24 on its LAN ports and expects the connected computer to +have 192.168.1.254 - Building/installing Liminix - ---------------- +[WARNING] +==== +The [.title-ref]#ubi0_7# device in these instructions is correct as of +Dec 2024 (dangowrt/owrt-ubi-installer commit d79e7928). If you are +installing some time later, it is important to check the output from +`+ubinfo -a+` and make sure you are updating the "liminix" volume and +not some other one which had been introduced since I wrote this. +==== - The default target for this device is ``outputs.ubimage`` which - makes a ubifs image suitable for use with :command:`ubiupdatevol`. - To write this to the device we use the OpenWrt recovery system - installed in the previous step. In this configuration the - device assigns itself the IP address 192.168.1.1/24 on its LAN - ports and expects the connected computer to have 192.168.1.254 +[source,console] +---- +$ nix-build -I liminix-config=./my-configuration.nix --arg device "import ./devices/belkin-rt3200" -A outputs.default +$ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs" +$ ssh root@192.168.1.1 +root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize +root@OpenWrt:~# ubinfo -a +[...] +Volume ID: 7 (on ubi0) +Type: dynamic +Alignment: 1 +Size: 851 LEBs (108056576 bytes, 103.0 MiB) +State: OK +Name: liminix +Character device major/minor: 250:8 +root@OpenWrt:~# ubiupdatevol /dev/ubi0_7 /tmp/rootfs +---- - .. warning:: The `ubi0_7` device in these instructions is correct - as of Dec 2024 (dangowrt/owrt-ubi-installer commit - d79e7928). If you are installing some time later, it - is important to check the output from - :command:`ubinfo -a` and make sure you are updating - the "liminix" volume and not some other one which had - been introduced since I wrote this. +To make the new system bootable we also need to change some U-Boot +variables. `+boot_production+` needs to mount the filesystem and boot +the FIT image found there, and `+bootcmd+` needs to be told not to boot +the rescue image if there are records in pstore, because that interferes +with `+config.log.persistent+` - .. code-block:: console +[source,console] +---- +root@OpenWrt:~# fw_setenv orig_boot_production $(fw_printenv -n boot_production) +root@OpenWrt:~# fw_setenv orig_bootcmd $(fw_printenv -n bootcmd) +root@OpenWrt:~# fw_setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' +root@OpenWrt:~# fw_setenv bootcmd 'run boot_ubi' +---- - $ nix-build -I liminix-config=./my-configuration.nix --arg device "import ./devices/belkin-rt3200" -A outputs.default - $ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs" - $ ssh root@192.168.1.1 - root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize - root@OpenWrt:~# ubinfo -a - [...] - Volume ID: 7 (on ubi0) - Type: dynamic - Alignment: 1 - Size: 851 LEBs (108056576 bytes, 103.0 MiB) - State: OK - Name: liminix - Character device major/minor: 250:8 - root@OpenWrt:~# ubiupdatevol /dev/ubi0_7 /tmp/rootfs +For subsequent Liminix reinstalls, just run the `+ubiupdatevol+` command +again. You don't need to repeat the "Preparation" step and in fact +should seek to avoid it if possible, as it will reset the erase counters +used for write levelling. Using UBI-aware tools is therefore preferred +over any kind of "factory" wipe which will reset them. - To make the new system bootable we also need to change some U-Boot variables. - ``boot_production`` needs to mount the filesystem and boot the FIT image - found there, and :code:`bootcmd` needs to be told _not_ to boot the rescue - image if there are records in pstore, because that interferes with - ``config.log.persistent`` - - .. code-block:: console - - root@OpenWrt:~# fw_setenv orig_boot_production $(fw_printenv -n boot_production) - root@OpenWrt:~# fw_setenv orig_bootcmd $(fw_printenv -n bootcmd) - root@OpenWrt:~# fw_setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' - root@OpenWrt:~# fw_setenv bootcmd 'run boot_ubi' - - For subsequent Liminix reinstalls, just run the - :command:`ubiupdatevol` command again. You don't need to repeat - the "Preparation" step and in fact should seek to avoid it if - possible, as it will reset the erase counters used for write - levelling. Using UBI-aware tools is therefore preferred over any - kind of "factory" wipe which will reset them. ''; system = { diff --git a/devices/gl-ar750/default.nix b/devices/gl-ar750/default.nix index a7a9660..0339504 100644 --- a/devices/gl-ar750/default.nix +++ b/devices/gl-ar750/default.nix @@ -10,46 +10,43 @@ }; description = '' - GL.iNet GL-AR750 - **************** - Hardware summary - ================ +== GL.iNet GL-AR750 - The GL-AR750 "Creta" travel router features: +=== Hardware summary - - 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 - - supported in OpenWrt by the "ath79" SoC family +The GL-AR750 "Creta" travel router features: - 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 `_ 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. +* 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 +* supported in OpenWrt by the "ath79" SoC family - Installation - ============ +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 +https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture[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. - As with many GL.iNet devices, the stock vendor firmware - is a fork of OpenWrt, meaning that the binary created by - :ref:`system-outputs-mtdimage` can be flashed using the - vendor web UI or the U-Boot emergency "unbrick" routine. +=== Installation - Flashing over an existing Liminix system is not possible while - that system is running, otherwise you'll be overwriting flash - partitions while they're in use - and that might not end well. - Configure the system with :ref:`levitate` if you need to - make it upgradable. +As with many GL.iNet devices, the stock vendor firmware is a fork of +OpenWrt, meaning that the binary created by `+system-outputs-mtdimage+` +can be flashed using the vendor web UI or the U-Boot emergency "unbrick" +routine. - Vendor web page: https://www.gl-inet.com/products/gl-ar750/ +Flashing over an existing Liminix system is not possible while that +system is running, otherwise you'll be overwriting flash partitions +while they're in use - and that might not end well. Configure the system +with `+levitate+` if you need to make it upgradable. - OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-ar750 +Vendor web page: https://www.gl-inet.com/products/gl-ar750/ + +OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-ar750 ''; diff --git a/devices/gl-mt300a/default.nix b/devices/gl-mt300a/default.nix index ea3894f..a423249 100644 --- a/devices/gl-mt300a/default.nix +++ b/devices/gl-mt300a/default.nix @@ -12,35 +12,33 @@ }; description = '' - GL.iNet GL-MT300A - ***************** - The GL-MT300A is based on a MT7620 chipset. +== GL.iNet GL-MT300A - For flashing from U-Boot, the firmware partition is from - 0xbc050000 to 0xbcfd0000. +The GL-MT300A is based on a MT7620 chipset. - 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. +For flashing from U-Boot, the firmware partition is from 0xbc050000 to +0xbcfd0000. - Installation - ============ +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. - The stock vendor firmware is a fork of OpenWrt, meaning that the - binary created by :ref:`system-outputs-mtdimage` can be flashed - using the vendor web UI or the U-Boot emergency "unbrick" routine. +=== Installation - Flashing over an existing Liminix system is not possible while - that system is running, otherwise you'll be overwriting flash - partitions while they're in use - and that might not end well. - Configure the system with :ref:`levitate` if you need to - make it upgradable. +The stock vendor firmware is a fork of OpenWrt, meaning that the binary +created by `+system-outputs-mtdimage+` can be flashed using the vendor +web UI or the U-Boot emergency "unbrick" routine. - Vendor web page: https://www.gl-inet.com/products/gl-mt300a/ +Flashing over an existing Liminix system is not possible while that +system is running, otherwise you'll be overwriting flash partitions +while they're in use - and that might not end well. Configure the system +with `+levitate+` if you need to make it upgradable. - OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300a +Vendor web page: https://www.gl-inet.com/products/gl-mt300a/ + +OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300a ''; diff --git a/devices/gl-mt300n-v2/default.nix b/devices/gl-mt300n-v2/default.nix index ac16d7f..f612e34 100644 --- a/devices/gl-mt300n-v2/default.nix +++ b/devices/gl-mt300n-v2/default.nix @@ -10,30 +10,27 @@ }; description = '' - GL.iNet GL-MT300N-v2 - ******************** +== GL.iNet GL-MT300N-v2 - The GL-MT300N-v2 "Mango" is is very similar to the :ref:`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. +The GL-MT300N-v2 "Mango" is is very similar to the `+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 - ============ +=== Installation - The stock vendor firmware is a fork of OpenWrt, meaning that the - binary created by :ref:`system-outputs-mtdimage` can be flashed - using the vendor web UI or the U-Boot emergency "unbrick" routine. +The stock vendor firmware is a fork of OpenWrt, meaning that the binary +created by `+system-outputs-mtdimage+` can be flashed using the vendor +web UI or the U-Boot emergency "unbrick" routine. - Flashing over an existing Liminix system is not possible while - that system is running, otherwise you'll be overwriting flash - partitions while they're in use - and that might not end well. - Configure the system with :ref:`levitate` if you need to - make it upgradable. +Flashing over an existing Liminix system is not possible while that +system is running, otherwise you'll be overwriting flash partitions +while they're in use - and that might not end well. Configure the system +with `+levitate+` if you need to make it upgradable. - Vendor web page: https://www.gl-inet.com/products/gl-mt300n-v2/ +Vendor web page: https://www.gl-inet.com/products/gl-mt300n-v2/ - OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300n_v2 +OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-mt300n_v2 ''; diff --git a/devices/openwrt-one/default.nix b/devices/openwrt-one/default.nix index 0a80f7a..47c4f6c 100644 --- a/devices/openwrt-one/default.nix +++ b/devices/openwrt-one/default.nix @@ -1,73 +1,84 @@ { description = '' - OpenWrt One - *********** - Hardware summary - ================ +== OpenWrt One - - MediaTek MT7981B (1300MHz) - - 256MB NAND Flash - - 1024MB RAM - - WLan hardware: Mediatek MT7976C +=== Hardware summary - Status - ====== +* MediaTek MT7981B (1300MHz) +* 256MB NAND Flash +* 1024MB RAM +* WLan hardware: Mediatek MT7976C - - Only tested over TFTP so far. - - WiFi (2.4G and 5G) works. - - 2.5G ethernet port works. +=== Status - Limitations - =========== +* Only tested over TFTP so far. +* WiFi (2.4G and 5G) works. +* 2.5G ethernet port works. - - adding `he_bss_color="128"` causes `Invalid argument` for hostap - - nvme support untested - - I don't think the front LEDs work yet +=== Limitations - Installation - ============ +* adding `he_bss_color="128"` causes `Invalid argument` for hostap +* nvme support untested +* I don't think the front LEDs work yet - TODO: add instructions on how to boot directly from TFTP to memory - and how to install from TFTP to flash without going through OpenWrt. +=== Installation - The instructions below assume you can boot and SSH into OpenWrt, - for example by attaching a USB serial console to the front port, - selecting 'boot from recovery' in the U-Boot menu, and connecting - to root@192.168.1.1 via the 1G ethernet port. +TODO: add instructions on how to boot directly from TFTP to memory and +how to install from TFTP to flash without going through OpenWrt. - Boot into OpenWrt and create a 'liminix' UBI partition: +The instructions below assume you can boot and SSH into OpenWrt, for +example by attaching a USB serial console to the front port, selecting +'boot from recovery' in the U-Boot menu, and connecting to +root@192.168.1.1 via the 1G ethernet port. - root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize +Boot into OpenWrt and create a 'liminix' UBI partition: - Remember the 'Volume ID' that was created for this new partition, or - find the one labeled 'liminix' using 'ubinfo -d 0 -n 5' etc. +[source,console] +---- +root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize +---- - Build the UBI image and write it to this new partition: +Remember the 'Volume ID' that was created for this new partition, or +find the one labeled 'liminix' using 'ubinfo -d 0 -n 5' etc. - $ nix-build -I liminix-config=./my-configuration.nix --arg device "import ./devices/openwrt-one" -A outputs.default - $ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs" - $ ssh root@192.168.1.1 - root@OpenWrt:~# ubiupdatevol /dev/ubi0_X /tmp/rootfs # replace X with the volume id, if needed check with `ubinfo` +Build the UBI image and write it to this new partition: - Reboot into the U-Boot prompt and boot with: - OpenWrt One> ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' +[source,console] +---- +$ nix-build -I liminix-config=./my-configuration.nix --arg device +"import ./devices/openwrt-one" -A outputs.default +$ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs" +$ ssh root@192.168.1.1 +root@OpenWrt:~# ubiupdatevol /dev/ubi0_X /tmp/rootfs # replace X +with the volume id, if needed check with `ubinfo` +---- - If this works, reboot into OpenWrt and configure U-Boot to boot ubifs by default: +Reboot into the U-Boot prompt and boot with: - root@OpenWrt:~# fw_setenv orig_boot_production $(fw_printenv -n boot_production) - root@OpenWrt:~# fw_setenv boot_production 'led white on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' +[source,console] +---- +OpenWrt One> ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr} +---- - Troubleshooting - =============== +If this works, reboot into OpenWrt and configure U-Boot to boot ubifs by +default: - The instructions above assume you can boot and SSH into the (recovery) - OpenWrt installation. If you have broken your device to the point where that - is no longer possible, you could re-install OpenWrt, but probably you could - also install directly from U-Boot: +[source,console] +---- +root@OpenWrt:~# fw_setenv orig_boot_production $(fw_printenv -n boot_production) +root@OpenWrt:~# fw_setenv boot_production 'led white on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' +---- - https://github.com/u-boot/u-boot/blob/master/doc/README.ubi +=== Troubleshooting + +The instructions above assume you can boot and SSH into the (recovery) +OpenWrt installation. If you have broken your device to the point where +that is no longer possible, you could re-install OpenWrt, but probably +you could also install directly from U-Boot: + +https://github.com/u-boot/u-boot/blob/master/doc/README.ubi ''; system = { diff --git a/devices/qemu-aarch64/default.nix b/devices/qemu-aarch64/default.nix index 70b4840..1ed3553 100644 --- a/devices/qemu-aarch64/default.nix +++ b/devices/qemu-aarch64/default.nix @@ -10,17 +10,17 @@ }; description = '' - QEMU Aarch64 - ************ - This target produces an image for - the `QEMU "virt" platform `_ using a 64 bit CPU type. +== QEMU Aarch64 - ARM targets differ from MIPS in that the kernel format expected - by QEMU is an "Image" (raw binary file) rather than an ELF - file, but this is taken care of by :command:`run.sh`. Check the - documentation for the :ref:`qemu` target for more information. +This target produces an image for the +https://www.qemu.org/docs/master/system/arm/virt.html[QEMU "virt" +platform] using a 64 bit CPU type. +ARM targets differ from MIPS in that the kernel format expected by QEMU +is an "Image" (raw binary file) rather than an ELF file, but this is +taken care of by `+run.sh+`. Check the documentation for the `+qemu+` +target for more information. ''; # this device is described by the "qemu" device diff --git a/devices/qemu-armv7l/default.nix b/devices/qemu-armv7l/default.nix index 795c296..4265e09 100644 --- a/devices/qemu-armv7l/default.nix +++ b/devices/qemu-armv7l/default.nix @@ -11,17 +11,16 @@ # this device is described by the "qemu" device description = '' - QEMU ARM v7 - *********** +== QEMU ARM v7 - This target produces an image for - the `QEMU "virt" platform `_ using a 32 bit CPU type. +This target produces an image for the +https://www.qemu.org/docs/master/system/arm/virt.html[QEMU "virt" +platform] using a 32 bit CPU type. - ARM targets differ from MIPS in that the kernel format expected - by QEMU is an "Image" (raw binary file) rather than an ELF - file, but this is taken care of by :command:`run.sh`. Check the - documentation for the :ref:`QEMU` (MIPS) target for more information. - ''; +ARM targets differ from MIPS in that the kernel format expected by QEMU +is an "Image" (raw binary file) rather than an ELF file, but this is +taken care of by `+run.sh+`. Check the documentation for the `+QEMU+` +(MIPS) target for more information. ''; installer = "vmroot"; module = diff --git a/devices/qemu/default.nix b/devices/qemu/default.nix index b219ceb..3f10566 100644 --- a/devices/qemu/default.nix +++ b/devices/qemu/default.nix @@ -13,27 +13,23 @@ }; description = '' - QEMU MIPS - ********* +== QEMU MIPS - This target produces an image for - QEMU, the "generic and open source machine emulator and - virtualizer". +This target produces an image for QEMU, the "generic and open source +machine emulator and virtualizer". - 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. +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. - Building an image for QEMU results in a :file:`result/` directory - containing ``run.sh`` ``vmlinux``, and ``rootfs`` files. To invoke - the emulator, run ``run.sh``. +Building an image for QEMU results in a `+result/+` directory containing +`+run.sh+` `+vmlinux+`, and `+rootfs+` files. 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. +The configuration includes two emulated "hardware" ethernet devices and +the kernel `+mac80211_hwsim+` module to provide an emulated wlan device. +To read more about how to connect to this network, refer to +`+qemu-networking+` in the Development manual. ''; module = diff --git a/devices/tp-archer-ax23/default.nix b/devices/tp-archer-ax23/default.nix index 580f4c6..51d4d5a 100644 --- a/devices/tp-archer-ax23/default.nix +++ b/devices/tp-archer-ax23/default.nix @@ -1,25 +1,22 @@ { description = '' - TP-Link Archer AX23 / AX1800 Dual Band Wi-Fi 6 Router - ***************************************************** +== TP-Link Archer AX23 / AX1800 Dual Band Wi-Fi 6 Router - Hardware summary - ================ +=== Hardware summary - - MediaTek MT7621 (880MHz) - - 16MB Flash - - 128MB RAM - - WLan hardware: Mediatek MT7905, MT7975 +* MediaTek MT7621 (880MHz) +* 16MB Flash +* 128MB RAM +* WLan hardware: Mediatek MT7905, MT7975 - Limitations - =========== +=== Limitations - Status LEDs do not work yet. +Status LEDs do not work yet. - Uploading an image via tftp doesn't work yet, because the Archer uboot - version is so old it doesn't support overriding the DTB from the mboot - command. The tftpboot module doesn't support this yet, see - https://gti.telent.net/dan/liminix/pulls/5 for the WiP. +Uploading an image via tftp doesn't work yet, because the Archer uboot +version is so old it doesn't support overriding the DTB from the mboot +command. The tftpboot module doesn't support this yet, see +https://gti.telent.net/dan/liminix/pulls/5 for the WiP. ''; system = { diff --git a/devices/turris-omnia/default.nix b/devices/turris-omnia/default.nix index 2db9932..277fc7b 100644 --- a/devices/turris-omnia/default.nix +++ b/devices/turris-omnia/default.nix @@ -1,149 +1,151 @@ { description = '' - Turris Omnia - ************ +== Turris Omnia - This is a 32 bit ARMv7 MVEBU device, which is usually shipped with - TurrisOS, an OpenWrt-based system. Rather than reformatting the - builtin storage, we install Liminix on to the existing btrfs - filesystem so that the vendor snapshot/recovery system continues - to work (and provides you an easy rollback if you decide you don't - like Liminix after all). +This is a 32 bit ARMv7 MVEBU device, which is usually shipped with +TurrisOS, an OpenWrt-based system. Rather than reformatting the builtin +storage, we install Liminix on to the existing btrfs filesystem so that +the vendor snapshot/recovery system continues to work (and provides you +an easy rollback if you decide you don't like Liminix after all). - The install process has two stages, and is intended that you - should not need to open the device and add a serial console - (although it may be handy for visibility, and in case anything - goes wrong). First we build a minimal installation/recovery - system, then we reboot into that recovery image to prepare the - device for the full target install. +The install process has two stages, and is intended that you should not +need to open the device and add a serial console (although it may be +handy for visibility, and in case anything goes wrong). First we build a +minimal installation/recovery system, then we reboot into that recovery +image to prepare the device for the full target install. - Installation using a USB stick - ============================== +=== Installation using a USB stick - First, build the image for the USB stick. Review - :file:`examples/recovery.nix` in order to change the default - root password (which is ``secret``) and/or the SSH keys, then - build it with +First, build the image for the USB stick. Review +`+examples/recovery.nix+` in order to change the default root password +(which is `+secret+`) and/or the SSH keys, then build it with - .. code-block:: console +[source,console] +---- +$ nix-build -I liminix-config=./examples/recovery.nix \ + --arg device "import ./devices/turris-omnia" \ + -A outputs.mbrimage -o mbrimage +$ file -L mbrimage +mbrimage: DOS/MBR boot sector; partition 1 : ID=0x83, active, start-CHS (0x0,0,5), end-CHS (0x6,130,26), startsector 4, 104602 sectors +---- - $ nix-build -I liminix-config=./examples/recovery.nix \ - --arg device "import ./devices/turris-omnia" \ - -A outputs.mbrimage -o mbrimage - $ file -L mbrimage - mbrimage: DOS/MBR boot sector; partition 1 : ID=0x83, active, start-CHS (0x0,0,5), end-CHS (0x6,130,26), startsector 4, 104602 sectors +Next, copy the image from your build machine to a USB storage medium +using `+dd+` or your other most favoured file copying tool, which might +be a comand something like this: - Next, copy the image from your build machine to a USB storage - medium using :command:`dd` or your other most favoured file copying - tool, which might be a comand something like this: +[source,console] +---- +$ dd if=mbrimage of=/dev/path/to/the/usb/stick \ + bs=1M conv=fdatasync status=progress +---- - .. code-block:: console +The Omnia's default boot order only checks USB after it has failed to +boot from eMMC, which is not ideal for our purpose. Unless you have a +serial cable, the easiest way to change this is by booting to TurrisOS +and logging in with ssh: - $ dd if=mbrimage of=/dev/path/to/the/usb/stick \ - bs=1M conv=fdatasync status=progress +[source,console] +---- +root@turris:/# fw_printenv boot_targets +boot_targets=mmc0 nvme0 scsi0 usb0 pxe dhcp +root@turris:/# fw_setenv boot_targets usb0 mmc0 +root@turris:/# fw_printenv boot_targets +boot_targets=usb0 mmc0 +root@turris:/# reboot -f +---- - The Omnia's default boot order only checks USB after it has failed - to boot from eMMC, which is not ideal for our purpose. Unless you - have a serial cable, the easiest way to change this is by booting - to TurrisOS and logging in with ssh: +It should now boot into the recovery image. It expects a network cable +to be plugged into LAN2 with something on the other end of it that +serves DHCP requests. Check your DHCP server logs for a request from a +`+liminix-recovery+` host and figure out what IP address was assigned. - .. code-block:: console +[source,console] +---- +$ ssh liminix-recovery.lan +---- - root@turris:/# fw_printenv boot_targets - boot_targets=mmc0 nvme0 scsi0 usb0 pxe dhcp - root@turris:/# fw_setenv boot_targets usb0 mmc0 - root@turris:/# fw_printenv boot_targets - boot_targets=usb0 mmc0 - root@turris:/# reboot -f +You should get a "Busybox" banner and a root prompt. Now you can start +preparing the device to install Liminix on it. First we'll mount the +root filesystem and take a snapshot: - It should now boot into the recovery image. It expects a network - cable to be plugged into LAN2 with something on the other end of - it that serves DHCP requests. Check your DHCP server logs for a - request from a ``liminix-recovery`` host and figure out what IP - address was assigned. +[source,console] +---- +# mkdir /dest && mount /dev/mmcblk0p1 /dest +# schnapps -d /dest create "pre liminix" +# schnapps -d /dest list +ERROR: not a valid btrfs filesystem: / + # | Type | Size | Date | Description +------+-----------+-------------+---------------------------+------------------------------------ + 1 | single | 16.00KiB | 1970-01-01 00:11:49 +0000 | pre liminix +---- - .. code-block:: console +(`+not a valid btrfs filesystem: /+` is not a real error) - $ ssh liminix-recovery.lan +then we can remove all the files - You should get a "Busybox" banner and a root prompt. Now you can - start preparing the device to install Liminix on it. First we'll - mount the root filesystem and take a snapshot: +[source,console] +---- +# rm -r /dest/@/* +---- - .. code-block:: console +and then it's ready to install the real Liminix system onto. On your +build system, create the Liminix configuration you wish to install: here +we'll use the `+rotuer+` example. - # mkdir /dest && mount /dev/mmcblk0p1 /dest - # schnapps -d /dest create "pre liminix" - # schnapps -d /dest list - ERROR: not a valid btrfs filesystem: / - # | Type | Size | Date | Description - ------+-----------+-------------+---------------------------+------------------------------------ - 1 | single | 16.00KiB | 1970-01-01 00:11:49 +0000 | pre liminix +[source,console] +---- +build$ nix-build -I liminix-config=./examples/rotuer.nix \ + --arg device "import ./devices/turris-omnia" \ + -A outputs.systemConfiguration +---- - (``not a valid btrfs filesystem: /`` is not a real error) +and then use `+min-copy-closure+` to copy it to the device. - then we can remove all the files +[source,console] +---- +build$ nix-shell --run \ + "min-copy-closure -r /dest/@ root@liminix-recovery.lan result" +---- - .. code-block:: console +and activate it - # rm -r /dest/@/* +[source,console] +---- +build$ ssh root@liminix-recovery.lan \ + "/dest/@/$(readlink result)/bin/install /dest/@" +---- - and then it's ready to install the real Liminix system onto. On - your build system, create the Liminix configuration you wish to - install: here we'll use the ``rotuer`` example. +The final steps are performed directly on the device again: add a +symlink so U-Boot can find `+/boot+`, then restore the default boot +order and reboot into the new configuration. - .. code-block:: console +[source,console] +---- +# cd /dest && ln -s @/boot . +# fw_setenv boot_targets "mmc0 nvme0 scsi0 usb0 pxe dhcp" +# cd / ; umount /dest +# reboot +---- - build$ nix-build -I liminix-config=./examples/rotuer.nix \ - --arg device "import ./devices/turris-omnia" \ - -A outputs.systemConfiguration +=== Installation using a TFTP server and serial console - and then use :command:`min-copy-closure` to copy it to the device. +If you have a <> and a TFTP server, and would +rather use them than fiddling with USB sticks, the +`+examples/recovery.nix+` configuration also works using the +`+tftpboot+` output. So you can do - .. code-block:: console +[source,console] +---- +build$ nix-build -I liminix-config=./examples/recovery.nix \ + --arg device "import ./devices/turris-omnia" \ + -A outputs.tftpboot +---- - build$ nix-shell --run \ - "min-copy-closure -r /dest/@ root@liminix-recovery.lan result" - - and activate it - - .. code-block:: console - - build$ ssh root@liminix-recovery.lan \ - "/dest/@/$(readlink result)/bin/install /dest/@" - - The final steps are performed directly on the device again: add - a symlink so U-Boot can find :file:`/boot`, then restore the - default boot order and reboot into the new configuration. - - .. code-block:: console - - # cd /dest && ln -s @/boot . - # fw_setenv boot_targets "mmc0 nvme0 scsi0 usb0 pxe dhcp" - # cd / ; umount /dest - # reboot - - - Installation using a TFTP server and serial console - =================================================== - - If you have a :ref:`serial` console connection and a TFTP server, - and would rather use them than fiddling with USB sticks, the - :file:`examples/recovery.nix` configuration also works - using the ``tftpboot`` output. So you can do - - .. code-block:: console - - build$ nix-build -I liminix-config=./examples/recovery.nix \ - --arg device "import ./devices/turris-omnia" \ - -A outputs.tftpboot - - and then paste the generated :file:`result/boot.scr` into - U-Boot, and you will end up with the same system as you would - have had after booting from USB. If you don't have a serial - console connection you could probably even get clever with - elaborate use of :command:`fw_setenv`, but that is left as - an exercise for the reader. +and then paste the generated `+result/boot.scr+` into U-Boot, and you +will end up with the same system as you would have had after booting +from USB. If you don't have a serial console connection you could +probably even get clever with elaborate use of `+fw_setenv+`, but that +is left as an exercise for the reader. ''; diff --git a/devices/zyxel-nwa50ax/default.nix b/devices/zyxel-nwa50ax/default.nix index e398567..6705dbe 100644 --- a/devices/zyxel-nwa50ax/default.nix +++ b/devices/zyxel-nwa50ax/default.nix @@ -10,94 +10,93 @@ }; description = '' - Zyxel NWA50AX - ******************** - Zyxel NWA50AX is quite close to the GL-MT300N-v2 "Mango" device, but it is based on the MT7621 - chipset instead of the MT7628. +== Zyxel NWA50AX - Installation - ============ +Zyxel NWA50AX is quite close to the GL-MT300N-v2 "Mango" device, but it is based on the MT7621 +chipset instead of the MT7628. - This device is pretty, but, due to its A/B capabilities, can be a bit hard - to use completely. +=== Installation - The stock vendor firmware is a downstream fork of U-Boot: - with restricted boot commands. Fortunately, OpenWrt folks figured out trivial command injections, - so you can use most of the OpenWrt commands without trouble by just command injecting - atns, atna or atnf, e.g. atns "; $real_command". +This device is pretty, but, due to its A/B capabilities, can be a bit hard +to use completely. - From factory web UI, you can upload the result of the zyxel-nwa-fit output. - From another operating system, you need to `dumpimage -T flat_dt -p 0 $zyxel-nwa-fit -o firmware.bin`, - `flash_erase $(mtd partition of the target partition firmware or zy_firmware) 0 0`, then you complete by - `nandwrite -p $(mtd partition of the target partition firmware or zy_firmware) firmware.bin`. +The stock vendor firmware is a downstream fork of U-Boot: +with restricted boot commands. Fortunately, OpenWrt folks figured out trivial command injections, +so you can use most of the OpenWrt commands without trouble by just command injecting +atns, atna or atnf, e.g. atns "; $real_command". - How to put the firmware.bin on the machine is left to you as an exercise, e.g. SSH, TFTP, whatever. +From factory web UI, you can upload the result of the zyxel-nwa-fit output. +From another operating system, you need to `dumpimage -T flat_dt -p 0 $zyxel-nwa-fit -o firmware.bin`, +`flash_erase $(mtd partition of the target partition firmware or zy_firmware) 0 0`, then you complete by +`nandwrite -p $(mtd partition of the target partition firmware or zy_firmware) firmware.bin`. - From serial, you have two choices: +How to put the firmware.bin on the machine is left to you as an exercise, e.g. SSH, TFTP, whatever. - - Flash this system via U-Boot: - same reasoning as from an existing Linux system, two choices: - - ymodem the binary, perform the write manually, you can inspire yourself - from the `script` contained in the vendor firmware, those are just a FIT containing a script. - - prepare a FIT containing a script executing your commands, tftpboot this. +From serial, you have two choices: - - boot from an existing Liminix system, e.g. TFTPBOOT image. - - boot from an OpenWrt system, i.e. follow OpenWrt steps. +- Flash this system via U-Boot: + same reasoning as from an existing Linux system, two choices: + - ymodem the binary, perform the write manually, you can inspire yourself + from the `script` contained in the vendor firmware, those are just a FIT containing a script. + - prepare a FIT containing a script executing your commands, tftpboot this. - Once you are in a Linux system, understand that this device has A/B boot. +- boot from an existing Liminix system, e.g. TFTPBOOT image. +- boot from an OpenWrt system, i.e. follow OpenWrt steps. - OpenWrt provides you with `zyxel-bootconfig` to set/unset the image status and choice. +Once you are in a Linux system, understand that this device has A/B boot. - The kernel is booted with `bootImage=` which tells you which slot are you on. +OpenWrt provides you with `zyxel-bootconfig` to set/unset the image status and choice. - You should find yourself with 10ish MTD partitions, the most interesting ones are two: +The kernel is booted with `bootImage=` which tells you which slot are you on. - - firmware: 40MB - - firmware_1: 40MB +You should find yourself with 10ish MTD partitions, the most interesting ones are two: - In the current setup, they are split further into kernel (8MB) and ubi (32MB). +- firmware: 40MB +- firmware_1: 40MB - Once you are done with first installation, note that if you want to use the A/B feature, - you need to write a _secondary_ image on the slot B. There is no proper flashing code - that will set the being-updated slot to `new` and boot on it to verify if it's working. - This is a WIP. +In the current setup, they are split further into kernel (8MB) and ubi (32MB). - Upgrading your system can be achieved via: +Once you are done with first installation, note that if you want to use the A/B feature, +you need to write a secondary image on the slot B. There is no proper flashing code +that will set the being-updated slot to `new` and boot on it to verify if it's working. +This is a WIP. - - `liminix-rebuild` for the userspace. - - `flash_erase` + `nandwrite` for the kernelspace to the other slot than the one you are booted on, - note that you can just nandwrite the mtd partition corresponding to the *kernel* and not the whole firmware. +Upgrading your system can be achieved via: - If you soft-bricked your AP, i.e. you cannot boot anything in U-Boot, no worries, just plug the serial console, - prepare a TFTP server (via `tufted` for example), download vendor firmware, set up `atns`, `atnf`, etc. and run `atnz`. +- `liminix-rebuild` for the userspace. +- `flash_erase` + `nandwrite` for the kernelspace to the other slot than the one you are booted on, + note that you can just nandwrite the mtd partition corresponding to the *kernel* and not the whole firmware. - This will reflash everything back to normal via TFTP. +If you soft-bricked your AP, i.e. you cannot boot anything in U-Boot, no worries, just plug the serial console, +prepare a TFTP server (via `tufted` for example), download vendor firmware, set up `atns`, `atnf`, etc. and run `atnz`. - If you hard-bricked your AP, i.e. U-Boot is telling you to transfer a valid bootloader via ymodem, just extract - a U-Boot from the vendor OS, send it via ymodem and use the previous operations to perform a full flash this time - of all partitions. +This will reflash everything back to normal via TFTP. - Note that if you erased your MRD partition, you lost your serial and MAC address. There's no way to recover the original one - except by reading the physical label on your… device! +If you hard-bricked your AP, i.e. U-Boot is telling you to transfer a valid bootloader via ymodem, just extract +a U-Boot from the vendor OS, send it via ymodem and use the previous operations to perform a full flash this time +of all partitions. - If you super-hard-bricked your AP, i.e. no output on serial console, congratulations, you reached one of the rare state - of this device. You need an external NAND flasher to repair it and write the first stage from Mediatek to continue the previous - recovery operations. +Note that if you erased your MRD partition, you lost your serial and MAC address. There's no way to recover the original one +except by reading the physical label on your… device! - Development TODO list: +If you super-hard-bricked your AP, i.e. no output on serial console, congratulations, you reached one of the rare state +of this device. You need an external NAND flasher to repair it and write the first stage from Mediatek to continue the previous +recovery operations. - - Better support for upgrade automation w.r.t. to A/B, e.g. automagic scripts. - - Mount the logs partition, mount / as overlayfs of firmware ? rootfs and rootfs_data for extended data. - - Jitter-based entropy injection? Device can be slow to initialize its CRNG and hostapd will reject few clients at the start because of that. - - Defaults for hostapd based on MT7915 capabilities? See the example for one possible list. - - Remove primary/secondary hack and put it in preinit. - - Offer ways to reflash the *bootloader* itself to support direct boot via UBI and kernel upgrades via filesystem rewrite. +Development TODO list: - Vendor web page: https://www.zyxel.com/fr/fr/products/wireless/ax1800-wifi-6-dual-radio-nebulaflex-access-point-nwa50ax +- Better support for upgrade automation w.r.t. to A/B, e.g. automagic scripts. +- Mount the logs partition, mount / as overlayfs of firmware ? rootfs and rootfs_data for extended data. +- Jitter-based entropy injection? Device can be slow to initialize its CRNG and hostapd will reject few clients at the start because of that. +- Defaults for hostapd based on MT7915 capabilities? See the example for one possible list. +- Remove primary/secondary hack and put it in preinit. +- Offer ways to reflash the *bootloader* itself to support direct boot via UBI and kernel upgrades via filesystem rewrite. - OpenWrt web page: https://openwrt.org/inbox/toh/zyxel/nwa50ax - OpenWrt tech data: https://openwrt.org/toh/hwdata/zyxel/zyxel_nwa50ax +Vendor web page: https://www.zyxel.com/fr/fr/products/wireless/ax1800-wifi-6-dual-radio-nebulaflex-access-point-nwa50ax + +OpenWrt web page: https://openwrt.org/inbox/toh/zyxel/nwa50ax +OpenWrt tech data: https://openwrt.org/toh/hwdata/zyxel/zyxel_nwa50ax ''; diff --git a/doc.nix b/doc.nix index 76cae25..a0171d4 100644 --- a/doc.nix +++ b/doc.nix @@ -41,7 +41,7 @@ stdenv.mkDerivation { buildPhase = '' cat ${json} | fennel --correlate doc/parse-options.fnl > doc/module-options-generated.inc.rst cat ${json} | fennel --correlate doc/parse-options-outputs.fnl > doc/outputs-generated.inc.rst - cp ${(import ./doc/hardware.nix)} doc/hardware.rst + cp ${(import ./doc/hardware.nix)} doc/hardware.adoc make -C doc html ''; installPhase = '' diff --git a/doc/hardware.nix b/doc/hardware.nix index e133704..e115140 100644 --- a/doc/hardware.nix +++ b/doc/hardware.nix @@ -10,12 +10,11 @@ let tag = ".. _${lib.strings.replaceStrings [ " " ] [ "-" ] n}:"; d' = { description = '' - ${n} - ${substring 0 (stringLength n) "============================"} + == ${n} ''; } // d; in - "${tag}\n\n${d'.description}" + "\n${d'.description}" ) devices; in writeText "hwdoc" '' diff --git a/doc/index.adoc b/doc/index.adoc index 081c3c9..fb44cb2 100644 --- a/doc/index.adoc +++ b/doc/index.adoc @@ -24,7 +24,7 @@ include::code-of-conduct.adoc[] [appendix] = Supported hardware -=== Recommended devices +== Recommended devices For development, the supported GL.iNet devices are all good choices if you can find them, as they have a builtin "debrick" procedure in the