Tow-Boot
 |
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! |
 |
Open call for help and contributions: Small announcement about 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 easy to accidentally overwrite. 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 as a normal software partition) if the bootloader can boot from those.
In case none of those nice options are available, then Tow-Boot would have to be flashed onto the SD or eMMC storage itself. This is not favorable since now, Tow-Boot can be wiped by formatting the normal storage. When using this shared storage strategy, Tow-Boot would be installed before flashing 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 the disk where the Tow-Boot bootloader resides. 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
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 used on the majority of handheld devices postmarketOS supports since most phones and tablets don't have hardware keyboards on them.
When starting, the first thing that happens is that the RGB LED will glow 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 cause the LED to glow yellow when selected.
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 LED will glow blue and the device should show up as a USB mass storage device 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 a simple method to flash pmOS to the eMMC, the USB mass storage mode of Tow-Boot described above can be used.
For devices with the shared storage strategy a installation of 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, however, the ondev installer is run against a shared storage medium anyway, Tow-Boot will be wiped and will have to be reinstalled.