commit 608d750b602c9c43735bace1a565fdb9a4cebb58
parent f5a7b7867921f66f7e10a2de4b3fc9fbe964353e
Author: Daniel Barlow <dan@telent.net>
Date: Fri, 24 Mar 2023 23:38:41 +0000
describe how to flash Liminix, and kexecboot
Diffstat:
| M | doc/user.rst | | | 154 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
1 file changed, 135 insertions(+), 19 deletions(-)
diff --git a/doc/user.rst b/doc/user.rst
@@ -9,39 +9,155 @@ Configuring for your use case
You need to create a ``configuration.nix`` that describes your router
and the services that you want to run on it. Start by copying
-``vanilla-configuration.nix`` and adjusting it.
+``vanilla-configuration.nix`` and adjusting it, or look in the `examples`
+directory for some pre-written configurations.
+
+If you want to create a configuration that can be installed on
+a hardware device, be sure to include the "flashable" module.
+
+.. code-block: nix
+
+ imports = [
+ ./modules/flashable.nix
+ ]
+
Building and flashing
*********************
-You need to set ``<liminix-config>`` to point to your
-``configuration.nix``, the file for your hardware device definition as
-argument ``device``, and to choose an appropriate output attribute
-depending on what your device is and how you plan to install onto
-it. For example:
+An example command to build Liminix might look like this:
+
+.. code-block:: console
+
+ nix-build -I liminix-config=./tests/smoke/configuration.nix \
+ --arg device "import ./devices/qemu" -A outputs.default
+
+In this command ``<liminix-config>`` points to your
+``configuration.nix``, ``device`` is the file for your hardware device
+definition, and ``outputs.default`` will generate some kind of
+Liminix image output appropriate to that device.
+
+For the qemu device in this example, ``outputs.default`` is an alias
+for ``outputs.vmbuild``, which creates a directory containing a
+squashfs root image and a kernel. You can use the `mips-vm` command to
+run this.
+
+For the currently supported hardware devices, ``outputs.default``
+creates a directory containing a file called ``firmware.bin``. This
+is a raw image file that can be written directly to the firmware flash
+partition.
+
+
+Flashing with :command:`flashcp`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This requires an existing Liminix system, or perhaps some other
+operating system on the device which provides the :command:`flashcp`
+command. You need to locate the "firmware" partition, which you can do
+with a combination of :command:`dmesg` output and the contents of
+:file:`/proc/mtd`
+
+.. code-block:: console
+
+ <5>[ 0.469841] Creating 4 MTD partitions on "spi0.0":
+ <5>[ 0.474837] 0x000000000000-0x000000040000 : "u-boot"
+ <5>[ 0.480796] 0x000000040000-0x000000050000 : "u-boot-env"
+ <5>[ 0.487056] 0x000000050000-0x000000060000 : "art"
+ <5>[ 0.492753] 0x000000060000-0x000001000000 : "firmware"
+
+ # cat /proc/mtd
+ dev: size erasesize name
+ mtd0: 00040000 00001000 "u-boot"
+ mtd1: 00010000 00001000 "u-boot-env"
+ mtd2: 00010000 00001000 "art"
+ mtd3: 00fa0000 00001000 "firmware"
+ mtd4: 002a0000 00001000 "kernel"
+ mtd5: 00d00000 00001000 "rootfs"
+
+Then you can copy the image to the device with :command:`ssh`
+
+.. code-block:: console
+
+ build-machine$ tar chf - result/firmware.bin | \
+ ssh root@the-device tar -C /run -xvf -
+
+and then connect to the device and run
+
+
+.. code-block:: console
+
+ flashcp firmware.bin /dev/mtd3
+
+
+
+Flashing from OpenWrt (untested)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your device is running OpenWrt then it probably has the
+:command:`mtd` command installed and you can use it as follows:
+
+.. code-block:: console
+
+ mtd -r write /tmp/firmware_image.bin firmware
+
+For more information, please see the `OpenWrt manual <https://openwrt.org/docs/guide-user/installation/sysupgrade.cli>`_
+
+
+Flashing from the boot monitor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are prepared to open the device and have a TTL serial adaptor
+or some kind to connect it to, you can probably flash it using U-Boot.
+This is quite hardware-specific: please refer to the Developer Manual.
+
+
+
+Updates to running devices
+**************************
+
+To mitigate the risk of flashing a new configuration and potentially
+render the device unresponsive if the configuration is unbootable or
+doesn't bring up a network device, Liminix has a
+"try before write" mode.
+
+To test a configuration without writing it to flash, import the
+``kexecboot`` module and build ``outputs.kexecboot`` instead of
+``outputs.default``. This generates a directory containing the root
+filesystem image and kernel, along with an executable called `kexec`
+and a `boot.sh` script that runs it with appropriate arguments.
+
+For example
+
+.. code-block:: console
+
+ nix-build --show-trace -I liminix-config=./examples/arhcive.nix \
+ --arg device "import ./devices/gl-ar750"
+ -A outputs.kexecboot && \
+ (tar chf - result | ssh root@the-device tar -C /run -xvf -)
+
+and then login to the device and run
.. code-block:: console
- nix-build -I liminix-config=./tests/smoke/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
+ cd /run/result
+ sh ./boot.sh .
-``outputs.default`` is intended to do something appropriate for the
-device, whatever that is. For the qemu device, it creates a directory
-containing a squashfs root image and a kernel.
-Future versions of this manual will at this point refer to
-device-specific instructions for installing Liminix using the router's
-Web UI or other non-invasive method. As of Feb 2023, the only way to
-flash a device is to take the cover off and connect wires to the
-serial console pads - so, check in the Developer Manual.
+This will load the new kernel and map the root filesystem into a RAM
+disk, then start executing the new kernel. *This is effectively a
+reboot - be sure to close all open files and finish anything else
+you were doing first.*
+If the new system crashes or is rebooted, then the device will revert
+to the old configuration it finds in flash. Thus, by combining kexec
+boot with a hardware watchdog you can try new images with very little
+chance of bricking anything. When you are happy that the new
+configuration is correct, build and flash a flashable image of it.
-Updating a running device
-*************************
-Feature forthcoming.
-Module options
+Module options (tbd)
**************
