Jump to content

Tow-Boot: Difference between revisions

From postmarketOS Wiki
Samueldr (talk | contribs)
m Correct U-Boot capitalizing
m Minor cleanup
 
(9 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Note|Tow-Boot support is not merged in pmbootstrap yet. This is a work in progress}}
{{Warning|postmarketOS tools (pmbootstrap, on-device-installer) do not support Tow-Boot in "shared storage mode" yet! See {{MR|2162}} and {{issue|59|postmarketos-ondev}}. 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: [https://gist.github.com/samueldr/8750e4aabbc23badec7a8798cabd4ed1 Small announcement about Tow-Boot]}}


[https://tow-boot.org/ Tow-Boot] is an opinionated [https://www.denx.de/wiki/U-Boot 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.
{{Infobox bootloader
| name = Tow-Boot
| first-stage = Y
| second-stage = Y
| resource = [https://tow-boot.org homepage] [https://github.com/Tow-Boot/Tow-Boot source code]
}}


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.  
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 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 <code>67401509-72e7-4628-b1af-edd128e4316a</code> for this partition. Operating systems should not touch this partition and create their own partitions after it instead.
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 <code>67401509-72e7-4628-b1af-edd128e4316a</code> for this partition. Operating systems should not touch this partition and create their own partitions after it instead.


== Boot selection ==
== Boot selection ==
Line 17: Line 25:


=== Button + led devices ===
=== 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.
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 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.
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 light up the yellow led.
The default option is "Boot from internal storage" which will cause the LED to glow yellow when selected.


If the {{Button|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 {{Button|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 {{Button|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.
If the {{Button|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 ==
== 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.
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 {{MR|2162|pmbootstrap}} merged is required. With this pmbootstrap will detect the GPT partition for Tow-Boot using the [https://git.sr.ht/~martijnbraam/findtow 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.


For devices with the shared storage strategy a pmbootstrap with {{MR|2162|pmbootstrap}} merged is required. With this pmbootstrap will detect the GPT partition for Tow-Boot using the [https://git.sr.ht/~martijnbraam/findtow 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.
== See also ==
[[U-Boot porting]]


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.
[[Category:Low-level]]

Latest revision as of 12:40, 1 June 2024

Warning 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 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

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 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.

See also

U-Boot porting