Phone and tablet UX + mmcboot support

[samueldr]

---

Give me the build

Woah there, you probably want to read and review before, but eh, if you want it, here it is:

Build 004.5

Built against e65e42d

Build	Installation notes	Troubleshooting guide
build 004.5 Pinephone A64 build	Installation notes	(none)
build 004.5 Pinephone Pro build	Installation notes	Troubleshooting guide

Outdated builds

• WIP 1 Pinephone Pro build

• WIP 2 Pinephone Pro build

• Built against db86fbf

  • WIP 3 Pinephone A64 build
  • WIP 3 Pinephone Pro build

• Built against ccf5627; main difference: mmcboot installer for Pinephone A64.

  • WIP 4 Pinephone A64 build
  • WIP 4 Pinephone Pro build

---

TODO

• Final reviews / approval by peers

---

What is this?

This is my attempt at making boot on "Linux phones" as painless as possible.

Features:

• LED management
• Phone keys based control
• User-friendlier universal defaults
• "Status reporting"

Anti-features:

• Superficial status reporting without display enablement.

LED management

The LED is lit-up as early as possible, assuming it's RGB, it's lit-up red first.

When Tow-Boot starts running the default distro boot (as defined by U-Boot), it turns yellow.

Some additional boot modes will turn the LED different colours:

• Blue for Mass Storage
• Aqua for requesting SD card boot

Phone keys based control

As commonly done with "consumer" phones and mobile devices, holding volume keys during early boot phases will affect the boot in different manner.

• Volume up: Boot in USB Mass Storage mode
• Volume down: Request Operating System Boot from SD card

Note: USB Mass Storage (or UMS) exports the eMMC (internal) of the device over USB.

User-friendlier universal defaults

To make things less confusing across devices, all devices will load the operating system using the same rules.

The schemes supported by the distro boot scheme from U-Boot are all tried on the following devices in order:

• eMMC
• SD

The order is static and eMMC first on all devices. This is a deviation from the defaults from the different communities, and somewhat a deviation from the defaults of U-Boot. Doing so helps reduce confusion and should help reduce support load.

This helps reduce confusion, because the order the operating systems will be tried to be loaded is the same, wherever Tow-Boot was started from. This is quite important considering different SoCs have a different BootROM startup order, making it harder to "just" boot the SD card if started from the SD card.

Furthermore, attempting Operating System boot from eMMC first is a done considering booting from a removable storage should be a conscious choice, requested by the end-user.

Note: When all Operating System boot sources have been attempted, and none worked, the device will poweroff after reporting the failure.

Not specific to the Phone UX, Tow-Boot always uses 115200 baud rate. This way, the UART rate is always the same, helping a bit more with unified instructions.

"Status reporting"

In addition to the LEDs reporting the current boot state, vibration support has been added. The device will vibrate once as early as possible.

When failing to do the Operating System boot from SD as requested by the user (holding volume down), the LED will flash 4 times, and the device will vibrate accordingly. Boot will continue to the default distro boot.

When failing to do the default distro boot, the LED will flash 10 times, and the device will vibrate accordingly. Then the device will poweroff.

Note: when connected to a power source, some devices (the Pinephone Pro) will not poweroff, and will instead reboot.

In addition to that, with the shared disk image, a protective partition is added to the GPT to prevent bad manipulations from breaking the installed Platform Firmware. This protective partition also provides strong guarantees when updating the Tow-Boot install, such that when its size increases, it is assured not to interfere with the other partitions.

Superficial status reporting without display enablement

As described previously, all of this is done such that the user knows what is happening, even though the display shows nothing.

This, to me is a sort of "anti-feature", but in reality we must keep this scheme such that further devices can use it even if a display driver has not been written yet for them.

---

How do I install this?

Ideally this would be installed to SPI flash using an SPI flash installer. An implementation was written with a "specialized" Linux system build so that the initial lack of display enablement on the Pinephone Pro wouldn't be an issue.

Alas, none of the targeted devices support SPI boot, thus none can be installed to dedicated storage.

To install to eMMC, the steps will generally be the same:

• These instructions will clobber the content of the SD card and the eMMC, defining a new partition table.
• Write the shared.disk-image.img to an SD card as-is
• Boot the device to USB Mass Storage by holding Volume Up
• Write the shared.disk-image.img to the phone.

Note: With some SoCs (e.g. Rockchip) you will need to "neuter" the Platform Firmware installed to the eMMC if there is one already installed.

How do I install a Linux distro after installing Tow-Boot?

This is a hard question to answer correctly. This will require a change in habits of the different distributions.

Misc. distro notes

Mobile NixOS

I can only answer for the distribution I'm involved with, Mobile NixOS.

A temporary installation method has been added:

• [HACK] Add outputs.u-boot.temp-tow-boot-install-script mobile-nixos/mobile-nixos#442
• [WIP] pine64-pinephonepro: Init mobile-nixos/mobile-nixos#445

It relies on a script and Mass Storage support on the target device. This is a method I think would be acceptable to keep recommending for other distros. The main thing to understand here is the script manipulates the partitions, then splats the content in them.

The permanent solution will be an installer system. The user will write Tow-Boot to the eMMC, and boot from a universal SD card that holds an installer system that will guide the user through some questions about partitioning (e.g. ask about FDE and filesystems), the preferred graphical environment, and then do a "classic" opinionated nixos-install under the covers.

---

Handles part of #104. (Devices listing on the website.)

[Danct12]

For mass storage mode, is it possible to export the SD card as well? It would be nice if you can write to SD card from there.

[samueldr]

Unless I missed something when I looked, the UMS driver for U-Boot at this point in time only handles exporting one LUN.

With UX improvements (mainly display output support) we could let the user pick which storage medium is exported.

An alternative could be to look into adding support for exporting more LUNs in upstream U-Boot.

[Be-ing]

An alternative could be to look into adding support for exporting more LUNs in upstream U-Boot.

I think letting the user choose which device is exported would be more foolproof. With both the SD and eMMC exported, the user could accidentally write to the wrong device. With Jump Drive on the PinePhone, I've had to check the drive size reported in dmesg to ensure I'm writing to the correct device. In the event the user is using an SD card that happens to be the same size as the eMMC drive, that could be tricky.

[samueldr]

This push rebases the work that was on this branch, with the refreshed work built on top of #78.

That rewrite was done because this PR showed it was really needed (in addition to making other things easier).

This push also includes the "ELO" changes, "Embedded Linux OS", which is used to build a touch-based installer system for installing to SPI, for devices that support installation to SPI.

[Strit]

Just writing to confirm that the WIP2 builds work fine on my Pinephone Pro.
It even makes the phone able to suspend!

Does the WIP3 build add something or is it just re-arranging some stuff?

[samueldr]

Re-arranging stuff, adding a Pinephone A64 pre-built artifact, and fixes the OS boot order regression.

But otherwise mostly the same.

[jussihi]

Hello, the download links don't seem to work for me for some reason. Is there some problems with the domain name redirection?

[samueldr]

AFAICT it still is working just fine here. wget or curl output might help track down issues.

[jussihi]

AFAICT it still is working just fine here. wget or curl output might help track down issues.

Thank you, it actually worked, it was just a bug or something in my web browser. I was able to download by copying the link to another tab (?!). Thanks for the work, now I'm rocking Tow-Boot on my PPP! It works great!

[justuser-ppp]

Hello all. I erased spi and flashed it. Now I cannot boot from sdcard. Is there any way to recover from this? Thank you for your help.

[justuser-ppp]

Apparently I still can boot from sdcard if i continue spamming volume down button on boot. Everything works as it should after. Strange.

[PureTryOut]

Note that you don't need to erase the SPI before flashing it, the flash button already handles that. Also please don't ask for user support here but join #tow-boot:matrix.org instead.

[justuser-ppp]

Thank you. Joined;)

[samueldr]

It was beginning to be too cumbersome to separate the changes for mmcboot support, when this PR touched the installer config.

I hate bundling more features into a huge PR, but this had to be done.

[chookity-pokk]

Note that you don't need to erase the SPI before flashing it, the flash button already handles that. Also please don't ask for user support here but join #tow-boot:matrix.org instead.

The tow-boot matrix doesn't seem to be join-able anymore?

[samueldr]

That's likely because to discover rooms, sometimes "via" servers are needed, try:

• https://matrix.to/#/#Tow-Boot:matrix.org?via=matrix.org

[NoahAndrews]

I just installed this onto my A64 Pinephone. The installation process was very smooth, and thanks to the new mmcboot support, it didn't wipe my existing OS installation! Awesome work.

[NoahAndrews]

This PR should get linked to #76