dan/liminix
1
0
Fork 5
Code

review installation docs

Browse Source
This commit is contained in:
Daniel Barlow 2025-04-07 23:33:10 +01:00
parent 6b61ba3b52
commit 887fe16020
3 changed files with 63 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/admin.adoc
View File

@ -220,7 +220,6 @@ This will install the previous configuration's activation binary into
/bin, and copy its kernel and initramfs into /boot. Note that it depends /bin, and copy its kernel and initramfs into /boot. Note that it depends
on the previous system not having been garbage-collected. on the previous system not having been garbage-collected.
[[levitate]]
==== Adding packages ==== Adding packages
If you simply wish to add a package without any change to services, you If you simply wish to add a package without any change to services, you
@ -238,8 +237,9 @@ nix-shell -p min-copy-closure root@the-device result/
Note that this only copies the package and its dependencies to the Note that this only copies the package and its dependencies to the
device: it doesn't update any profile to add it to `+$PATH+` device: it doesn't update any profile to add it to `+$PATH+`
[[rebuilding the system]] [reftext="Levitate"]
=== Reinstalling on a running system [[levitate]]
=== Levitate: Reinstalling on a running system
Liminix is initially installed from a monolithic `+firmware.bin+` - and Liminix is initially installed from a monolithic `+firmware.bin+` - and
unless you're running a writable filesystem, the only way to update it unless you're running a writable filesystem, the only way to update it

1
doc/development.adoc
View File

@ -184,6 +184,7 @@ documentation has a
https://openwrt.org/docs/techref/hardware/port.serial[good explanation] https://openwrt.org/docs/techref/hardware/port.serial[good explanation]
of what you may expect to find on the device. of what you may expect to find on the device.
[[tufted]]
`tufted` is a rudimentary TFTP server which runs from the command `tufted` is a rudimentary TFTP server which runs from the command
line, has an allowlist for client connections, and follows symlinks, line, has an allowlist for client connections, and follows symlinks,
so you can have your device download images direct from the so you can have your device download images direct from the

141
doc/installation.adoc
View File

@ -1,4 +1,4 @@
== Installation = Installation
Hardware devices vary wildly in their affordances for installing new Hardware devices vary wildly in their affordances for installing new
operating systems, so it should be no surprise that the Liminix operating systems, so it should be no surprise that the Liminix
@ -6,7 +6,23 @@ installation procedure is hardware-dependent. This section contains
generic instructions, but please refer to the documentation for your generic instructions, but please refer to the documentation for your
device to find whether and how well they apply. device to find whether and how well they apply.
=== Building a firmware image Most of the supported devices fall into one of two broad categories:
* devices we install by preparing a raw flash image and copying it
directly onto (some part of) the flash. This is analogous to (though
not quite the same as) using
https://www.man7.org/linux/man-pages/man1/dd.1.html:dd(1) on a
"grown up" computer to copy a raw disk image. Devices in this
category are usually smaller, older, and/or less powerful.
* devices where the vendor provides a "higher level" storage
abstraction, such as http://linux-mtd.infradead.org/doc/ubi.html:UBI
over raw flash, or a consumer flash such as MMC, or another storage
technology entirely. Installation on these devices is less uniform
because it depends on exactly what kind of storage abstraction.
== Building a firmware image
Liminix uses the Nix language to provide congruent configuration Liminix uses the Nix language to provide congruent configuration
management. This means that to change anything about the way in which a management. This means that to change anything about the way in which a
@ -38,32 +54,27 @@ $ nix-build -I liminix-config=./configuration.nix \
--arg device "import ./devices/gl-mt300a" -A outputs.default --arg device "import ./devices/gl-mt300a" -A outputs.default
---- ----
Usually (not always, _please check the documentation for your device_) For raw flash devices, this will leave you with a file
this will leave you with a file `+result/firmware.bin+` which you now `+result/firmware.bin+` which you now need to write to the flash.
need to flash to the device. For other devices, _please check the device documentation_
=== Flashing from the boot monitor (TFTP install) == Flashing from the boot monitor (TFTP install)
If you are prepared to open the device and have a TTL serial adaptor of You will need
some kind to connect it to, you can probably use U-Boot and a TFTP
server to download and flash the image.
This is quite hardware-specific and may even involve soldering - see the * to open the device and attach a TTL serial adaptor of some kind
documention for your device. However, it is in some ways the most * a TFTP server on the network that the device is plugged into
"reliable" option: if you can see what's happening (or not happening) in (or can be plugged into for installation)
early boot, the risk of "bricking" is substantially reduced and you have
options for recovering if you misstep or flash a bad image. Installing via serial connection is quite hardware-specific and
depending on the device may even involve soldering. However, it is in
some ways the most "reliable" option: if you can see what's happening
(or not happening) in early boot, the risk of "bricking" is
substantially reduced and you have options for recovering if you
misstep or flash a bad image.
[[serial]] [[serial]]
==== Serial connections === Serial connections
Every device that we have so far encountered in Liminix uses
https://docs.u-boot.org/en/latest/[U-Boot, the "Universal Boot
Loader"] so it's worth knowing a bit about it. "Universal" is in this
context a bit of a misnomer, though: encountering _mainline_ U-Boot is
very rare and often you'll find it is a fork from some version last
updated in 2008. Upgrading U-Boot is more or less complicated depending
on the device and is outside scope for Liminix.
To speak to U-Boot on your device you'll usually need a serial To speak to U-Boot on your device you'll usually need a serial
connection to it. This typically involves opening the box, locating the connection to it. This typically involves opening the box, locating the
@ -98,53 +109,52 @@ from U-Boot, followed by the instruction to hit some key to stop
autoboot. Do this and you will get to the prompt. If you didn't see autoboot. Do this and you will get to the prompt. If you didn't see
anything, the strong likelihood is that TX and RX are the wrong way anything, the strong likelihood is that TX and RX are the wrong way
around, or your computer is expecting flow control which the 3 wire around, or your computer is expecting flow control which the 3 wire
connection does not provide. . If you see garbage, try a different connection does not provide. If you see garbage, try a different
speed. speed.
Interesting commands to try first in U-Boot are `+help+` and Interesting commands to try first in U-Boot are `+help+` and
`+printenv+`. `+printenv+`.
=== TFTP
You will also need to configure a TFTP server on a network that's You will also need to configure a TFTP server on a network that's
accessible to the device: how you do that will vary according to which accessible to the device: how you do that will vary according to which
TFTP server you're using and so is out of scope for this document. TFTP server you're using and so is out of scope for this document.
HINT: <<tufted>>, a rudimentary TFTP server, is supplied with Liminix
for development purposes. It may or may not fit your needs here.
==== Building and installing the image ==== Building and installing the image
Follow the device-specific instructions for "TFTP install": usually, the Follow the device-specific instructions for "TFTP install": usually, the
steps are steps are
* build the [.title-ref]#outputs.mtdimage# output * build the [.title-ref]#outputs.mtdimage# output
* copy `+result/firmware.bin+` to your TFTP server * copy `+result/firmware.bin+` to wherever your TFTP server serves files
* copy/paste the commands in `+result/flash.scr+` one at a time into the from
* execute the commands listed in `+result/flash.scr+` at the
U-Boot command line U-Boot command line
* reset the device * reset the device
You should now see messages from U-Boot, then from the Linux kernel and You should now see messages from U-Boot, then from the Linux kernel and
eventually a shell prompt. eventually a shell prompt.
[NOTE] NOTE: Before you reboot, check which networks the device is plugged into, and
====
Before you reboot, check which networks the device is plugged into, and
disconnect as necessary. If you've just installed a DHCP server or disconnect as necessary. If you've just installed a DHCP server or
anything similar that responds to broadcasts, you may not want it to do anything else that responds to broadcasts, you may not want it to do
that on the network that you temporarily connected it to for installing that on the network that you temporarily connected it to for installing
it. it.
====
=== Flashing from OpenWrt == Flashing from OpenWrt
[CAUTION] CAUTION: Untested! A previous version of these instructions (without
==== the -e flag) led to soft-bricking the device when flashing a JFFS2
Untested! A previous version of these instructions (without the -e flag) image. The current version _should_ work better but if you are reading this
led to bricking the device when flashing a jffs2 image. If you are message then nobody has yet confirmed it
reading this message, nobody has yet reported on whether the new
instructions are any better.
====
If your device is running OpenWrt then it probably has the `+mtd+` If your device is running OpenWrt then it probably has the `+mtd+`
command installed. Build the [.title-ref]#outputs.mtdimage# output (as command installed. Transfer `+result/firmware.bin+` onto the running
you would for a TFTP install) and then transfer `+result/firmware.bin+` device using e.g. `+scp+`. Now flash as follows:
onto the device using e.g. `+scp+`. Now flash as follows:
[source,console] [source,console]
---- ----
@ -160,46 +170,13 @@ manual] which may also contain (hardware-dependent) instructions on how
to flash an image using the vendor firmware - perhaps even from a web to flash an image using the vendor firmware - perhaps even from a web
interface. interface.
=== Flashing from Liminix == Flashing from Liminix
If the device is already running Liminix and has been configured with If the device is already running Liminix then in general you cannot safely
`+levitate+`, you can use that to safely flash your new image. Refer to copy a new image over the top of the running system while it is running.
`+levitate+` for an explanation.
If the device is running Liminix but doesn't have `+levitate+` your If the running system was configured with <<levitate>> you can use
options are more limited. You may attempt to use `+flashcp+` but it that to safely flash your new image. Otherwise you may attempt to use
doesn't always work: as it copies the new image over the top of the `+flashcp+` directly, but bust out the serial leads in preparation for
active root filesystem, surprise may ensue. Consider instead using a it going horribly wrong.
serial connection: you may need one anyway after trying flashcp if it
corrupts the image.
==== flashcp (not generally recommended)
Connect to the device and locate the "firmware" partition, which you can
do with a combination of `+dmesg+` output and the contents of
`+/proc/mtd+`
[source,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"
----
Copy `+result/firmware.bin+` to the device and now run (in this example)
[source,console]
----
flashcp -v firmware.bin /dev/mtd3
----