Skip to content

Limit supported ways of installing and booting postmarketOS

Problem statement

We currently support a whole lot of different ways to boot postmarketOS, often leading to frustrating bugs in the initramfs such as:

  • root/boot partition can't be found when only one is in a subpartition !5625 (merged)
  • root partition not getting resized due to /dev/mapper paths being inconsistent !5632 (merged)
  • root/boot partitions not being found because of wrong UUIDs on the kernel cmdline (e.g. on an Android device using "fastboot boot" to boot a new boot image on an existing install).

These issues have been longstanding and regress on different devices with slightly different usecases. This really points to a deeper underlying issue: we just support too many different methods of booting.

Current ways to boot postmarketOS

We additionally support a large number of ways to boot the distro, these are not extensively documented and unnecessarily inconsistent across devices (in aid of greater user freedom, but at an increasing burden for maintainership and support).

  • Android boot image -> boot/root on existing android partitions (ANY partitions)
  • Android boot image -> boot and/or root on subpartitions of ANY partition
  • Android boot image -> boot partition and stowaway root partition image stored on userdata
  • EFI/extlinux -> (systemd-boot) -> kernel -> boot and/or root partitions (root could be on subpartition when migrating an Android device to EFI)

Ways we want to support booting postmarketOS

This is meant to be an exhaustive list of supported ways to boot postmarketOS! The major differences are:

  • Making pmOS_boot optional for Android/Chrome devices that don't need it (since !5636 makes initramfs-extra opt-in).

  • Dropping support for booting with subpartitions, and forcing all existing users to migrate (back up and re-install).

  • Android devices with userdata partition MUST use it as root OR another partition following the DPS (Discoverable Partition Specification)

    • Check DPS by UUID, userdata by label
    • If multiple root partitions are found then ABORT
      • suggest removing sdcard, can do some clever error messages with heuristics

  • Android devices that use a boot partition (e.g. for initramfs-extra) can flash it to any normal partition that meets the size requirements, where possible a larger partition like system should be recommended over one that risks being too small (e.g. 64mb is probably too small).

  • Root partition can be specified by UUID on the kernel cmdline. This would only be set when the kernel is loaded from the pmOS_boot partition (extlinux or ESP), so NOT on Android or ChromeOS devices which boot from a custom boot/kpart partition.

  • Android bootloader -> kernel -> rootfs (no boot partition).

  • (android device) lk2nd/u-boot (extlinux/efi) -> kernel -> rootfs

    • pmOS_boot partition must exist (ESP)
      • lk2nd tries some well-known partitions by name?
      • U-Boot looks for /EFI/Boot/bootaa64.efi
    • can be flashed to one of a set list of Android partitions
      • system, vendor, cache
    • Standard requirements for Android root partition as above (userdata/DPS)

  • EFI (can nuke partition table)

    • Must follow DPS
    • ESP, and normal root partition
    • UUID on kernel cmdline
    • In the future, additional partitions for A/B, immutable

Multi-boot

  • bootloader MUST be able to pick from multiple kernels
  • How to tie ESP and root partition together?
    • Set UUIDs on kernel cmdline for root, no need to specify boot since initramfs-extra unused. Boot is mounted by fstab.
Edited by Caleb Connolly
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information