Outputs

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 installed. The options available for a particular device are described in the section for that device.

Shell script to run on the target device that invokes kexec with appropriate options

table: 0x8f8b20

kexecboot

Directory containing files needed for kexec booting. Can be copied onto the target device using ssh or similar

mtdimage

This creates an image called firmware.bin suitable for squashfs or jffs2 systems. It can be flashed from U-Boot (if you have a serial console connection), or on some devices from the vendor firmware, or from a Liminix kexecboot system.

If you are flashing from U-Boot, the file flash.scr is a sequence of commands which you can paste at the U-Boot prompt to to transfer the firmware file from a TFTP server and write it to flash. Please read the script before running it: flash operations carry the potential to brick your device

Note

TTL serial connections typically have no form of flow control and so don’t always like having massive chunks of text pasted into them - and U-Boot may drop characters while it’s busy. So don’t necessarily expect to copy-paste the whole of flash.scr into a terminal emulator and have it work just like that. You may need to paste each line one at a time, or even retype it.

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 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.

table: 0x8f8b20

ubimage

This output provides a UBIFS filesystem image and a small U-Boot script to make the manual installation process very slightly simpler. You will need a serial connection and a network connection to a TFTP server containing the filesystem image it creates.

Warning

These steps were tested on a Belkin RT3200 (also known as Linksys E8450). Other devices may be set up differently, so use them as inspiration and don’t just paste them blindly.

  1. determine which MTD device is being used for UBI, and the partition name:

uboot>  ubi part
Device 0: ubi0, MTD partition ubi

In this case the important value is ubi0

  1. list the available volumes and create a new one on which to install Liminix

uboot> ubi info l
[ copious output scrolls past ]

Expect there to be existing volumes and for some or all of them to be important. Unless you know what you’re doing, don’t remove anything whose name suggests it’s related to uboot, or any kind of backup or recovery partition. To see how much space is free:

uboot> ubi info
[ ... ]
UBI: available PEBs:             823

Now we can make our new root volume

uboot> ubi create liminix -

3) transfer the root filesystem from the build system and write it to the new volume. Paste the environment variable settings from result/env.scr into U-Boot, then run

uboot> tftpboot ${loadaddr} result/rootfs
uboot> ubi write ${loadaddr} liminix $filesize

Now we have the root filesystem installed on the device. You can even mount it and poke around using ubifsmount ubi0:liminix; ubifsls  /

4) optional: before you configure the device to boot into Liminix automatically, you can try booting it by hand to see if it works:

uboot> ubifsmount ubi0:liminix
uboot> ubifsload ${loadaddr} boot/uimage
uboot> bootm ${loadaddr}

Once you’ve done this and you’re happy with it, reset the device to U-Boot. You don’t need to recreate the volume but you do need to repeat step 3.

5) Instructions for configuring autoboot are likely to be very device-dependent. On the Linksys E8450/Belkin RT3200, the environment variable boot_production governs what happens on a normal boot, so you could do

uboot> setenv boot_production 'led $bootled_pwr on ; ubifsmount ubi0:liminix; ubifsload ${loadaddr} boot/uimage; bootm ${loadaddr}'

On other devices, some detective work may be needed. Try running printenv and look for likely commands, try looking at the existing boot process, maybe even try looking for documentation for that device.

  1. Now you can reboot the device into Liminix

uboot> reset

vmroot

This target is for use with the qemu, qemu-aarch64, qemu-armv7l devices. It generates an executable run.sh which invokes QEMU. It connects the Liminix serial console and the QEMU monitor to stdin/stdout. Use ^P (not ^A) to switch between monitor and stdio.

If you call run.sh with --background /path/to/some/directory as the first parameter, it will fork into the background and open Unix sockets in that directory for console and monitor. Use nix-shell --run connect-vm to connect to either of these sockets, and ^O to disconnect.

Liminix VMs are networked using QEMU socket networking. The default behaviour is to connect

  • multicast 230.0.0.1:1234 (“access”) to eth0

  • multicast 230.0.0.1:1235 (“lan”) to eth1

Refer to Border Network Gateway for details of how to start an emulated upstream on the “access” network that your Liminix device can talk to.