newedge/liminix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

convert all the hardware docs to adoc

Browse Source
This commit is contained in:
Daniel Barlow
2025-09-18 21:58:26 +01:00
parent ebfaba45e6
commit 4bdd30b58d
14 changed files with 426 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
devices/belkin-rt3200/default.nix
View File

@@ -1,78 +1,71 @@
{ {
description = '' description = ''
Belkin RT-3200 / Linksys E8450
******************************
This device is based on a 64 bit Mediatek MT7622 ARM platform, == Belkin RT-3200 / Linksys E8450
and is mostly feature-complete in Liminix but as of Dec 2024
has seen very little actual use.
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) === Hardware summary
- 128MB NAND flash
- 512MB RAM
- b/g/n wireless using MediaTek MT7622BV (MT7615E driver)
- a/n/ac/ax wireless using MediaTek MT7915E
* 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 Liminix on this device uses the UBI volume management system to perform
perform wear leveling on the flash. This is not set up from the wear leveling on the flash. This is not set up from the factory, so a
factory, so a one-time step is needed to prepare it before Liminix one-time step is needed to prepare it before Liminix can be installed.
can be installed.
==== Preparation
Preparation
-----------
To prepare the device for Liminix you first need to use the To prepare the device for Liminix you first need to use the
`OpenWrt UBI Installer https://github.com/dangowrt/owrt-ubi-installer[OpenWrt UBI Installer]
<https://github.com/dangowrt/owrt-ubi-installer>`_ image to image to rewrite the flash layout. As of Jan 2025 there are two versions
rewrite the flash layout. As of Jan 2025 there are two versions
of the installer available: the release version 1.0.2 and the 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. pre-release 1.1.3 and for Liminix you nee the pre-release. The release
The release version of the installer creates UBI volumes version of the installer creates UBI volumes according to an older
according to an older layout that is not compatible with layout that is not compatible with the Linux 6.6.67 kernel used in
the Linux 6.6.67 kernel used in Liminix. Liminix.
You can run the installer in one of two ways: You can run the installer in one of two ways: either follow the
either follow the instructions to do it through the vendor web instructions to do it through the vendor web interface, or you can drop
interface, or you can drop to U-Boot and use TFTP to U-Boot and use TFTP
.. code-block:: console
[source,console]
----
MT7622> setenv ipaddr 10.0.0.6 MT7622> setenv ipaddr 10.0.0.6
MT7622> setenv serverip 10.0.0.1 MT7622> setenv serverip 10.0.0.1
MT7622> tftpboot 0x42000000 openwrt-mediatek-mt7622-linksys_e8450-ubi-initramfs-recovery-installer.itb MT7622> tftpboot 0x42000000 openwrt-mediatek-mt7622-linksys_e8450-ubi-initramfs-recovery-installer.itb
MT7622> bootm 0x42000000 MT7622> bootm 0x42000000
----
This will write the new flash layout and then boot into a This will write the new flash layout and then boot into a "recovery"
"recovery" OpenWrt installation. OpenWrt installation.
Building/installing Liminix ==== Building/installing Liminix
----------------
The default target for this device is ``outputs.ubimage`` which The default target for this device is `+outputs.ubimage+` which makes a
makes a ubifs image suitable for use with :command:`ubiupdatevol`. ubifs image suitable for use with `+ubiupdatevol+`. To write this to the
To write this to the device we use the OpenWrt recovery system device we use the OpenWrt recovery system installed in the previous
installed in the previous step. In this configuration the step. In this configuration the device assigns itself the IP address
device assigns itself the IP address 192.168.1.1/24 on its LAN 192.168.1.1/24 on its LAN ports and expects the connected computer to
ports and expects the connected computer to have 192.168.1.254 have 192.168.1.254
.. warning:: The `ubi0_7` device in these instructions is correct [WARNING]
as of Dec 2024 (dangowrt/owrt-ubi-installer commit ====
d79e7928). If you are installing some time later, it The [.title-ref]#ubi0_7# device in these instructions is correct as of
is important to check the output from Dec 2024 (dangowrt/owrt-ubi-installer commit d79e7928). If you are
:command:`ubinfo -a` and make sure you are updating installing some time later, it is important to check the output from
the "liminix" volume and not some other one which had `+ubinfo -a+` and make sure you are updating the "liminix" volume and
been introduced since I wrote this. not some other one which had been introduced since I wrote this.
====
.. code-block:: console
[source,console]
----
$ nix-build -I liminix-config=./my-configuration.nix --arg device "import ./devices/belkin-rt3200" -A outputs.default $ 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" $ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs"
$ ssh root@192.168.1.1 $ ssh root@192.168.1.1
@@ -87,26 +80,28 @@
Name: liminix Name: liminix
Character device major/minor: 250:8 Character device major/minor: 250:8
root@OpenWrt:~# ubiupdatevol /dev/ubi0_7 /tmp/rootfs root@OpenWrt:~# ubiupdatevol /dev/ubi0_7 /tmp/rootfs
----
To make the new system bootable we also need to change some U-Boot variables. To make the new system bootable we also need to change some U-Boot
``boot_production`` needs to mount the filesystem and boot the FIT image variables. `+boot_production+` needs to mount the filesystem and boot
found there, and :code:`bootcmd` needs to be told _not_ to boot the rescue the FIT image found there, and `+bootcmd+` needs to be told not to boot
image if there are records in pstore, because that interferes with the rescue image if there are records in pstore, because that interferes
``config.log.persistent`` 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_boot_production $(fw_printenv -n boot_production)
root@OpenWrt:~# fw_setenv orig_bootcmd $(fw_printenv -n bootcmd) 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 boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}'
root@OpenWrt:~# fw_setenv bootcmd 'run boot_ubi' root@OpenWrt:~# fw_setenv bootcmd 'run boot_ubi'
----
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.
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 = { system = {

53
devices/gl-ar750/default.nix
View File

@@ -10,42 +10,39 @@
}; };
description = '' description = ''
GL.iNet GL-AR750
****************
Hardware summary == GL.iNet GL-AR750
================
=== Hardware summary
The GL-AR750 "Creta" travel router features: The GL-AR750 "Creta" travel router features:
- QCA9531 @650Mhz SoC * QCA9531 @650Mhz SoC
- dual band wireless: IEEE 802.11a/b/g/n/ac * dual band wireless: IEEE 802.11a/b/g/n/ac
- two 10/100Mbps LAN ports and one WAN * two 10/100Mbps LAN ports and one WAN
- 128MB DDR2 RAM * 128MB DDR2 RAM
- 16MB NOR Flash * 16MB NOR Flash
- supported in OpenWrt by the "ath79" SoC family * supported in OpenWrt by the "ath79" SoC family
The GL-AR750 has two distinct sets of wifi hardware. The 2.4GHz The GL-AR750 has two distinct sets of wifi hardware. The 2.4GHz radio is
radio is part of the QCA9531 SoC, i.e. it's on the same silicon as part of the QCA9531 SoC, i.e. it's on the same silicon as the CPU, the
the CPU, the Ethernet, the USB etc. The device is connected to the Ethernet, the USB etc. The device is connected to the host via
host via `AHB <https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture>`_ and it is https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture[AHB]
supported in Linux using the ath9k driver. 5GHz wifi and it is supported in Linux using the ath9k driver. 5GHz wifi is
is provided by a QCA9887 PCIe (PCI embedded) WLAN chip, provided by a QCA9887 PCIe (PCI embedded) WLAN chip, supported by the
supported by the ath10k driver. ath10k driver.
Installation === Installation
============
As with many GL.iNet devices, the stock vendor firmware As with many GL.iNet devices, the stock vendor firmware is a fork of
is a fork of OpenWrt, meaning that the binary created by OpenWrt, meaning that the binary created by `+system-outputs-mtdimage+`
:ref:`system-outputs-mtdimage` can be flashed using the can be flashed using the vendor web UI or the U-Boot emergency "unbrick"
vendor web UI or the U-Boot emergency "unbrick" routine. routine.
Flashing over an existing Liminix system is not possible while Flashing over an existing Liminix system is not possible while that
that system is running, otherwise you'll be overwriting flash system is running, otherwise you'll be overwriting flash partitions
partitions while they're in use - and that might not end well. while they're in use - and that might not end well. Configure the system
Configure the system with :ref:`levitate` if you need to with `+levitate+` if you need to make it upgradable.
make it upgradable.
Vendor web page: https://www.gl-inet.com/products/gl-ar750/ Vendor web page: https://www.gl-inet.com/products/gl-ar750/

34
devices/gl-mt300a/default.nix
View File

@@ -12,31 +12,29 @@
}; };
description = '' description = ''
GL.iNet GL-MT300A
***************** == GL.iNet GL-MT300A
The GL-MT300A is based on a MT7620 chipset. The GL-MT300A is based on a MT7620 chipset.
For flashing from U-Boot, the firmware partition is from For flashing from U-Boot, the firmware partition is from 0xbc050000 to
0xbc050000 to 0xbcfd0000. 0xbcfd0000.
WiFi on this device is provided by the rt2800soc module. It WiFi on this device is provided by the rt2800soc module. It expects
expects firmware to be present in the "factory" MTD partition, so firmware to be present in the "factory" MTD partition, so - assuming we
- assuming we want to use the wireless - we need to build MTD want to use the wireless - we need to build MTD support into the kernel
support into the kernel even if we're using TFTP root. even if we're using TFTP root.
Installation === Installation
============
The stock vendor firmware is a fork of OpenWrt, meaning that the The stock vendor firmware is a fork of OpenWrt, meaning that the binary
binary created by :ref:`system-outputs-mtdimage` can be flashed created by `+system-outputs-mtdimage+` can be flashed using the vendor
using the vendor web UI or the U-Boot emergency "unbrick" routine. web UI or the U-Boot emergency "unbrick" routine.
Flashing over an existing Liminix system is not possible while Flashing over an existing Liminix system is not possible while that
that system is running, otherwise you'll be overwriting flash system is running, otherwise you'll be overwriting flash partitions
partitions while they're in use - and that might not end well. while they're in use - and that might not end well. Configure the system
Configure the system with :ref:`levitate` if you need to with `+levitate+` if you need to make it upgradable.
make it upgradable.
Vendor web page: https://www.gl-inet.com/products/gl-mt300a/ Vendor web page: https://www.gl-inet.com/products/gl-mt300a/

29
devices/gl-mt300n-v2/default.nix
View File

@@ -10,26 +10,23 @@
}; };
description = '' 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 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 based on the MT7628 chipset instead of MT7620. It's also marginally
and comes in a yellow case not a blue one. Be sure your device is cheaper and comes in a yellow case not a blue one. Be sure your device
v2 not v1, which is a different animal and has only half as much RAM. 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 The stock vendor firmware is a fork of OpenWrt, meaning that the binary
binary created by :ref:`system-outputs-mtdimage` can be flashed created by `+system-outputs-mtdimage+` can be flashed using the vendor
using the vendor web UI or the U-Boot emergency "unbrick" routine. web UI or the U-Boot emergency "unbrick" routine.
Flashing over an existing Liminix system is not possible while Flashing over an existing Liminix system is not possible while that
that system is running, otherwise you'll be overwriting flash system is running, otherwise you'll be overwriting flash partitions
partitions while they're in use - and that might not end well. while they're in use - and that might not end well. Configure the system
Configure the system with :ref:`levitate` if you need to with `+levitate+` if you need to make it upgradable.
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/

81
devices/openwrt-one/default.nix
View File

@@ -1,71 +1,82 @@
{ {
description = '' description = ''
OpenWrt One
***********
Hardware summary == OpenWrt One
================
- MediaTek MT7981B (1300MHz) === Hardware summary
- 256MB NAND Flash
- 1024MB RAM
- WLan hardware: Mediatek MT7976C
Status * MediaTek MT7981B (1300MHz)
====== * 256MB NAND Flash
* 1024MB RAM
* WLan hardware: Mediatek MT7976C
- Only tested over TFTP so far. === Status
- WiFi (2.4G and 5G) works.
- 2.5G ethernet port works.
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 === Limitations
- nvme support untested
- I don't think the front LEDs work yet
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 === Installation
and how to install from TFTP to flash without going through OpenWrt.
The instructions below assume you can boot and SSH into OpenWrt, TODO: add instructions on how to boot directly from TFTP to memory and
for example by attaching a USB serial console to the front port, how to install from TFTP to flash without going through OpenWrt.
selecting 'boot from recovery' in the U-Boot menu, and connecting
to root@192.168.1.1 via the 1G ethernet port. 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.
Boot into OpenWrt and create a 'liminix' UBI partition: Boot into OpenWrt and create a 'liminix' UBI partition:
[source,console]
----
root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize root@OpenWrt:~# ubimkvol /dev/ubi0 --name=liminix --maxavsize
----
Remember the 'Volume ID' that was created for this new partition, or Remember the 'Volume ID' that was created for this new partition, or
find the one labeled 'liminix' using 'ubinfo -d 0 -n 5' etc. find the one labeled 'liminix' using 'ubinfo -d 0 -n 5' etc.
Build the UBI image and write it to this new partition: Build the UBI image and write it to this new partition:
$ nix-build -I liminix-config=./my-configuration.nix --arg device "import ./devices/openwrt-one" -A outputs.default
[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" $ cat result/rootfs | ssh root@192.168.1.1 "cat > /tmp/rootfs"
$ ssh root@192.168.1.1 $ 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` root@OpenWrt:~# ubiupdatevol /dev/ubi0_X /tmp/rootfs # replace X
with the volume id, if needed check with `ubinfo`
----
Reboot into the U-Boot prompt and boot with: Reboot into the U-Boot prompt and boot with:
OpenWrt One> ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}' [source,console]
----
OpenWrt One> ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}
----
If this works, reboot into OpenWrt and configure U-Boot to boot ubifs by default: If this works, reboot into OpenWrt and configure U-Boot to boot ubifs by
default:
[source,console]
----
root@OpenWrt:~# fw_setenv orig_boot_production $(fw_printenv -n boot_production) 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}' root@OpenWrt:~# fw_setenv boot_production 'led white on ; ubifsmount ubi0:liminix && ubifsload ''${loadaddr} boot/fit && bootm ''${loadaddr}'
----
Troubleshooting === Troubleshooting
===============
The instructions above assume you can boot and SSH into the (recovery) 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 OpenWrt installation. If you have broken your device to the point where
is no longer possible, you could re-install OpenWrt, but probably you could that is no longer possible, you could re-install OpenWrt, but probably
also install directly from U-Boot: you could also install directly from U-Boot:
https://github.com/u-boot/u-boot/blob/master/doc/README.ubi https://github.com/u-boot/u-boot/blob/master/doc/README.ubi
''; '';

16
devices/qemu-aarch64/default.nix
View File

@@ -10,17 +10,17 @@
}; };
description = '' description = ''
QEMU Aarch64
************
This target produces an image for == QEMU Aarch64
the `QEMU "virt" platform <https://www.qemu.org/docs/master/system/arm/virt.html>`_ using a 64 bit CPU type.
ARM targets differ from MIPS in that the kernel format expected This target produces an image for the
by QEMU is an "Image" (raw binary file) rather than an ELF https://www.qemu.org/docs/master/system/arm/virt.html[QEMU "virt"
file, but this is taken care of by :command:`run.sh`. Check the platform] using a 64 bit CPU type.
documentation for the :ref:`qemu` 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+`
target for more information.
''; '';
# this device is described by the "qemu" device # this device is described by the "qemu" device

17
devices/qemu-armv7l/default.nix
View File

@@ -11,17 +11,16 @@
# this device is described by the "qemu" device # this device is described by the "qemu" device
description = '' description = ''
QEMU ARM v7 == QEMU ARM v7
***********
This target produces an image for This target produces an image for the
the `QEMU "virt" platform <https://www.qemu.org/docs/master/system/arm/virt.html>`_ using a 32 bit CPU type. 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 ARM targets differ from MIPS in that the kernel format expected by QEMU
by QEMU is an "Image" (raw binary file) rather than an ELF is an "Image" (raw binary file) rather than an ELF file, but this is
file, but this is taken care of by :command:`run.sh`. Check the taken care of by `+run.sh+`. Check the documentation for the `+QEMU+`
documentation for the :ref:`QEMU` (MIPS) target for more information. (MIPS) target for more information. '';
'';
installer = "vmroot"; installer = "vmroot";
module = module =

28
devices/qemu/default.nix
View File

@@ -13,27 +13,23 @@
}; };
description = '' description = ''
QEMU MIPS == QEMU MIPS
*********
This target produces an image for This target produces an image for QEMU, the "generic and open source
QEMU, the "generic and open source machine emulator and machine emulator and virtualizer".
virtualizer".
MIPS QEMU emulates a "Malta" board, which was an ATX form factor MIPS QEMU emulates a "Malta" board, which was an ATX form factor
evaluation board made by MIPS Technologies, but mostly in Liminix evaluation board made by MIPS Technologies, but mostly in Liminix we use
we use paravirtualized devices (Virtio) instead of emulating paravirtualized devices (Virtio) instead of emulating hardware.
hardware.
Building an image for QEMU results in a :file:`result/` directory Building an image for QEMU results in a `+result/+` directory containing
containing ``run.sh`` ``vmlinux``, and ``rootfs`` files. To invoke `+run.sh+` `+vmlinux+`, and `+rootfs+` files. To invoke the emulator,
the emulator, run ``run.sh``. run `+run.sh+`.
The configuration includes two emulated "hardware" ethernet The configuration includes two emulated "hardware" ethernet devices and
devices and the kernel :code:`mac80211_hwsim` module to the kernel `+mac80211_hwsim+` module to provide an emulated wlan device.
provide an emulated wlan device. To read more about how To read more about how to connect to this network, refer to
to connect to this network, refer to :ref:`qemu-networking` `+qemu-networking+` in the Development manual.
in the Development manual.
''; '';
module = module =

17
devices/tp-archer-ax23/default.nix
View File

@@ -1,18 +1,15 @@
{ {
description = '' 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) * MediaTek MT7621 (880MHz)
- 16MB Flash * 16MB Flash
- 128MB RAM * 128MB RAM
- WLan hardware: Mediatek MT7905, MT7975 * WLan hardware: Mediatek MT7905, MT7975
Limitations === Limitations
===========
Status LEDs do not work yet. Status LEDs do not work yet.

154
devices/turris-omnia/default.nix
View File

@@ -1,77 +1,75 @@
{ {
description = '' description = ''
Turris Omnia == Turris Omnia
************
This is a 32 bit ARMv7 MVEBU device, which is usually shipped with This is a 32 bit ARMv7 MVEBU device, which is usually shipped with
TurrisOS, an OpenWrt-based system. Rather than reformatting the TurrisOS, an OpenWrt-based system. Rather than reformatting the builtin
builtin storage, we install Liminix on to the existing btrfs storage, we install Liminix on to the existing btrfs filesystem so that
filesystem so that the vendor snapshot/recovery system continues the vendor snapshot/recovery system continues to work (and provides you
to work (and provides you an easy rollback if you decide you don't an easy rollback if you decide you don't like Liminix after all).
like Liminix after all).
The install process has two stages, and is intended that you The install process has two stages, and is intended that you should not
should not need to open the device and add a serial console need to open the device and add a serial console (although it may be
(although it may be handy for visibility, and in case anything handy for visibility, and in case anything goes wrong). First we build a
goes wrong). First we build a minimal installation/recovery minimal installation/recovery system, then we reboot into that recovery
system, then we reboot into that recovery image to prepare the image to prepare the device for the full target install.
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 First, build the image for the USB stick. Review
:file:`examples/recovery.nix` in order to change the default `+examples/recovery.nix+` in order to change the default root password
root password (which is ``secret``) and/or the SSH keys, then (which is `+secret+`) and/or the SSH keys, then build it with
build it with
.. code-block:: console
[source,console]
----
$ nix-build -I liminix-config=./examples/recovery.nix \ $ nix-build -I liminix-config=./examples/recovery.nix \
--arg device "import ./devices/turris-omnia" \ --arg device "import ./devices/turris-omnia" \
-A outputs.mbrimage -o mbrimage -A outputs.mbrimage -o mbrimage
$ file -L 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 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 Next, copy the image from your build machine to a USB storage medium
medium using :command:`dd` or your other most favoured file copying using `+dd+` or your other most favoured file copying tool, which might
tool, which might be a comand something like this: be a comand something like this:
.. code-block:: console
[source,console]
----
$ dd if=mbrimage of=/dev/path/to/the/usb/stick \ $ dd if=mbrimage of=/dev/path/to/the/usb/stick \
bs=1M conv=fdatasync status=progress bs=1M conv=fdatasync status=progress
----
The Omnia's default boot order only checks USB after it has failed The Omnia's default boot order only checks USB after it has failed to
to boot from eMMC, which is not ideal for our purpose. Unless you boot from eMMC, which is not ideal for our purpose. Unless you have a
have a serial cable, the easiest way to change this is by booting serial cable, the easiest way to change this is by booting to TurrisOS
to TurrisOS and logging in with ssh: and logging in with ssh:
.. code-block:: console
[source,console]
----
root@turris:/# fw_printenv boot_targets root@turris:/# fw_printenv boot_targets
boot_targets=mmc0 nvme0 scsi0 usb0 pxe dhcp boot_targets=mmc0 nvme0 scsi0 usb0 pxe dhcp
root@turris:/# fw_setenv boot_targets usb0 mmc0 root@turris:/# fw_setenv boot_targets usb0 mmc0
root@turris:/# fw_printenv boot_targets root@turris:/# fw_printenv boot_targets
boot_targets=usb0 mmc0 boot_targets=usb0 mmc0
root@turris:/# reboot -f root@turris:/# reboot -f
----
It should now boot into the recovery image. It expects a network It should now boot into the recovery image. It expects a network cable
cable to be plugged into LAN2 with something on the other end of to be plugged into LAN2 with something on the other end of it that
it that serves DHCP requests. Check your DHCP server logs for a serves DHCP requests. Check your DHCP server logs for a request from a
request from a ``liminix-recovery`` host and figure out what IP `+liminix-recovery+` host and figure out what IP address was assigned.
address was assigned.
.. code-block:: console
[source,console]
----
$ ssh liminix-recovery.lan $ ssh liminix-recovery.lan
----
You should get a "Busybox" banner and a root prompt. Now you can You should get a "Busybox" banner and a root prompt. Now you can start
start preparing the device to install Liminix on it. First we'll preparing the device to install Liminix on it. First we'll mount the
mount the root filesystem and take a snapshot: root filesystem and take a snapshot:
.. code-block:: console
[source,console]
----
# mkdir /dest && mount /dev/mmcblk0p1 /dest # mkdir /dest && mount /dev/mmcblk0p1 /dest
# schnapps -d /dest create "pre liminix" # schnapps -d /dest create "pre liminix"
# schnapps -d /dest list # schnapps -d /dest list
@@ -79,71 +77,75 @@
# | Type | Size | Date | Description # | Type | Size | Date | Description
------+-----------+-------------+---------------------------+------------------------------------ ------+-----------+-------------+---------------------------+------------------------------------
1 | single | 16.00KiB | 1970-01-01 00:11:49 +0000 | pre liminix 1 | single | 16.00KiB | 1970-01-01 00:11:49 +0000 | pre liminix
----
(``not a valid btrfs filesystem: /`` is not a real error) (`+not a valid btrfs filesystem: /+` is not a real error)
then we can remove all the files then we can remove all the files
.. code-block:: console [source,console]
----
# rm -r /dest/@/* # rm -r /dest/@/*
----
and then it's ready to install the real Liminix system onto. On and then it's ready to install the real Liminix system onto. On your
your build system, create the Liminix configuration you wish to build system, create the Liminix configuration you wish to install: here
install: here we'll use the ``rotuer`` example. we'll use the `+rotuer+` example.
.. code-block:: console
[source,console]
----
build$ nix-build -I liminix-config=./examples/rotuer.nix \ build$ nix-build -I liminix-config=./examples/rotuer.nix \
--arg device "import ./devices/turris-omnia" \ --arg device "import ./devices/turris-omnia" \
-A outputs.systemConfiguration -A outputs.systemConfiguration
----
and then use :command:`min-copy-closure` to copy it to the device. and then use `+min-copy-closure+` to copy it to the device.
.. code-block:: console
[source,console]
----
build$ nix-shell --run \ build$ nix-shell --run \
"min-copy-closure -r /dest/@ root@liminix-recovery.lan result" "min-copy-closure -r /dest/@ root@liminix-recovery.lan result"
----
and activate it and activate it
.. code-block:: console [source,console]
----
build$ ssh root@liminix-recovery.lan \ build$ ssh root@liminix-recovery.lan \
"/dest/@/$(readlink result)/bin/install /dest/@" "/dest/@/$(readlink result)/bin/install /dest/@"
----
The final steps are performed directly on the device again: add The final steps are performed directly on the device again: add a
a symlink so U-Boot can find :file:`/boot`, then restore the symlink so U-Boot can find `+/boot+`, then restore the default boot
default boot order and reboot into the new configuration. order and reboot into the new configuration.
.. code-block:: console
[source,console]
----
# cd /dest && ln -s @/boot . # cd /dest && ln -s @/boot .
# fw_setenv boot_targets "mmc0 nvme0 scsi0 usb0 pxe dhcp" # fw_setenv boot_targets "mmc0 nvme0 scsi0 usb0 pxe dhcp"
# cd / ; umount /dest # cd / ; umount /dest
# reboot # reboot
----
=== Installation using a TFTP server and serial console
Installation using a TFTP server and serial console If you have a <<serial,serial console connection>> and a TFTP server, and would
=================================================== rather use them than fiddling with USB sticks, the
`+examples/recovery.nix+` configuration also works using the
If you have a :ref:`serial` console connection and a TFTP server, `+tftpboot+` output. So you can do
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
[source,console]
----
build$ nix-build -I liminix-config=./examples/recovery.nix \ build$ nix-build -I liminix-config=./examples/recovery.nix \
--arg device "import ./devices/turris-omnia" \ --arg device "import ./devices/turris-omnia" \
-A outputs.tftpboot -A outputs.tftpboot
----
and then paste the generated :file:`result/boot.scr` into and then paste the generated `+result/boot.scr+` into U-Boot, and you
U-Boot, and you will end up with the same system as you would will end up with the same system as you would have had after booting
have had after booting from USB. If you don't have a serial from USB. If you don't have a serial console connection you could
console connection you could probably even get clever with probably even get clever with elaborate use of `+fw_setenv+`, but that
elaborate use of :command:`fw_setenv`, but that is left as is left as an exercise for the reader.
an exercise for the reader.
''; '';

9
devices/zyxel-nwa50ax/default.nix
View File

@@ -10,14 +10,13 @@
}; };
description = '' description = ''
Zyxel NWA50AX
******************** == Zyxel NWA50AX
Zyxel NWA50AX is quite close to the GL-MT300N-v2 "Mango" device, but it is based on the MT7621 Zyxel NWA50AX is quite close to the GL-MT300N-v2 "Mango" device, but it is based on the MT7621
chipset instead of the MT7628. chipset instead of the MT7628.
Installation === Installation
============
This device is pretty, but, due to its A/B capabilities, can be a bit hard This device is pretty, but, due to its A/B capabilities, can be a bit hard
to use completely. to use completely.
@@ -59,7 +58,7 @@
In the current setup, they are split further into kernel (8MB) and ubi (32MB). In the current setup, they are split further into kernel (8MB) and ubi (32MB).
Once you are done with first installation, note that if you want to use the A/B feature, 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 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. that will set the being-updated slot to `new` and boot on it to verify if it's working.
This is a WIP. This is a WIP.

2
doc.nix
View File

@@ -41,7 +41,7 @@ stdenv.mkDerivation {
buildPhase = '' buildPhase = ''
cat ${json} | fennel --correlate doc/parse-options.fnl > doc/module-options-generated.inc.rst 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 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 make -C doc html
''; '';
installPhase = '' installPhase = ''

5
doc/hardware.nix
View File

@@ -10,12 +10,11 @@ let
tag = ".. _${lib.strings.replaceStrings [ " " ] [ "-" ] n}:"; tag = ".. _${lib.strings.replaceStrings [ " " ] [ "-" ] n}:";
d' = { d' = {
description = '' description = ''
${n} == ${n}
${substring 0 (stringLength n) "============================"}
''; '';
} // d; } // d;
in in
"${tag}\n\n${d'.description}" "\n${d'.description}"
) devices; ) devices;
in in
writeText "hwdoc" '' writeText "hwdoc" ''

2
doc/index.adoc
View File

@@ -24,7 +24,7 @@ include::code-of-conduct.adoc[]
[appendix] [appendix]
= Supported hardware = Supported hardware
=== Recommended devices == Recommended devices
For development, the supported GL.iNet devices are all good choices if 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 you can find them, as they have a builtin "debrick" procedure in the