Tow-Boot

From postmarketOS
Icon WARNING: postmarketOS tools (pmbootstrap, on-device-installer) do not support Tow-Boot in "shared storage mode" yet! See !2162 and postmarketos-ondev#59. If you attempt to install postmarketOS on a device that relies on booting Tow-Boot in shared storage mode, you will overwrite Tow-Boot and your device will probably not boot anymore!
Notice Open call for help and contributions: Small announcement about Tow-Boot
Tow-Boot
Name Tow-Boot
1st stage
Works
2nd stage
Works
Resources homepage source code

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 67401509-72e7-4628-b1af-edd128e4316a 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

Tow-Boot in the graphical boot menu

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 Escape or Ctrl+C. 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 Volume down 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 Volume up 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 pmbootstrap!2162 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.

See also

U-Boot porting