.. _system-outputs-boot-sh:	

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

.. _system-outputs-extlinux:	

table: 0x781270
.. _system-outputs-kexecboot:	

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

.. _system-outputs-mtdimage:	

mtdimage
**********

This creates an image called :file:`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
: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 :file:`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.

.. _system-outputs-tftpboot:	

tftpboot
********

This output is intended for developing on a new device.
It assumes you have a serial connection and a
network connection to the device and that your
build machine is running a TFTP server.

The output is a directory containing kernel and
root filesystem image, and a script :file:`boot.scr` of U-Boot
commands that will load the images into memory and
run them directly,
instead of first writing them to flash. This saves
time and erase cycles.

It uses the Linux `phram <https://github.com/torvalds/linux/blob/master/drivers/mtd/devices/phram.c>`_ driver to emulate a flash device using a segment of physical RAM.

.. _system-outputs-tplink-safeloader:	

table: 0x781270
.. _system-outputs-u-boot:	

table: 0x781270
.. _system-outputs-ubimage:	

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:

.. code-block:: console

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

In this case the important value is ``ubi0``

2) list the available volumes and create a new one on which to install Liminix

.. code-block:: console

    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:

.. code-block:: console

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

Now we can make our new root volume

.. code-block:: console

    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
:file:`result/env.scr` into U-Boot, then run

.. code-block:: console

    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:

.. code-block:: console

    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

.. code-block:: console

    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.

6) Now you can reboot the device into Liminix

.. code-block:: console

    uboot> reset

.. _system-outputs-vmroot:	

vmroot
******

This target is for use with the qemu, qemu-aarch64, qemu-armv7l
devices. It generates an executable :file:`run.sh` which
invokes QEMU. It connects the Liminix
serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/monitor.html>`_
to stdin/stdout. Use ^P (not ^A) to switch between monitor and
stdio.

If you call :command:`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 :command:`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 :ref:`border-network-gateway` for details of how to
start an emulated upstream on the "access" network that
your Liminix device can talk to.