Tow-Boot

Tow-Boot is an opinionated U-Boot distribution. It provides a more consistent U-Boot experience across devices and is preconfigured to have a nice graphical boot menu if possible on the hardware.

In the ideal case Tow-Boot is flashed to an SPI flash chip in the device since that's usually the first boot option of the hardware and is not easily accidentally overwritten. On some devices there's no SPI flash available but it's possible to put Tow-Boot in a special eMMC hardware partition (this shows up as a seperate mmc device, not a normal software partition) if the bootloader can boot from those.

In case none of those nice options are available then Tow-Boot would be put on the SD or eMMC storage itself. This is not favorable since now Tow-Boot is wipe-able by formatting the normal storage. When using this shared storage strategy Tow-Boot would be installed before installing postmarketOS and it will create it's own GPT partition table on the storage with a single small partition at the start. This partition doesn't contain a filesystem but is there to protect that area of the disk from being accidentally overwritten with something else. It marks the location on disk where Tow-Boot iself is stored. The GPT partition type UUID is  for this partition. Operating systems should not touch this partition and create their own partitions after it instead.

Boot selection
One of the things Tow-Boot standardizes is boot selection. This is roughly split in two groups:

Screen + keyboard devices


On devices with a keyboard and working display Tow-Boot will display the U-Boot logs to the screen while starting and has a prompt to press or +. This will show a nice graphical boot selection menu for selecting between the various internal and external storage options.

Button + led devices
Devices that either don't have display+keyboard integrated, or don't have the drivers for that working in U-Boot yet have a fallback method where booting is influenced by leds and buttons on the device. This is also most devices postmarketOS supports since most phones and tablets don't have hardware keyboards on them.

When starting this the first thing that happens is that the RGB led will be red. After this the led can turn either yellow, blue or cyan depending on the boot selection.

The default option is "Boot from internal storage" which will light up the yellow led.

If the button is held down then Tow-Boot will try to boot from the SD card. This will light up the led in cyan.

If the button is held down then the blue led will light up and the device should show up as USB mass storage when plugged into your computer. This mass-storage device will expose the eMMC storage of the device.

Flashing postmarketOS
The USB mass storage mode of Tow-Boot is ideal for flashing postmarketOS to the device. When the device has Tow-Boot on dedicated storage like SPI flash or an eMMC hardware partition postmarketOS can just be written to the SD or eMMC and Tow-Boot should find it and boot it. For easily flashing to the eMMC the USB mass storage mode of Tow-Boot described above can be used.

For devices with the shared storage strategy a pmbootstrap with merged is required. With this pmbootstrap will detect the GPT partition for Tow-Boot using the findtow utility and make sure not to touch that part of partitioning on the disk. It will instead remove all the other partitions from the disk and create new postmarketOS partitions after the Tow-Boot partition.

Currently the On-device installer doesn't support tow-boot shared storage yet. If the ondev installer is ran against a shared storage medium anyway the Tow-Boot will be wiped and will have to be reinstalled.