megi's PinePhone Development Log RSS


2021–10–13: How to adapt multi-boot image to your needs

I've added a program to p-boot that allows you to extract contents of the boot partition to a directory, so that you can modify it and re-import back into the boot partition.

This allows you to change menu items in the boot image, customize graphics of the boot menu, update the kernel, change kernel boot parameters, add new distributions to the existing multi-distro image, etc.

It's as simple as:

p-boot-unconf new-dir /dev/mmcblk0p1

Now you can edit contents of new-dir in any way you want. If you don't want to change the kernel, you'll only want to modify the boot.conf file.

To save the changes back to the boot partition, you can run:

p-boot-conf new-dir /dev/mmcblk0p1

And that's it. :)

Multi-boot image has some nice builtin structure that you can use to your advantage. Each distribution is contained in its own subvolume in the main btrfs filesystem on the second partition.

For example, the subvolume strucuture may look like this if you mount the second partition of the multi-distro SD card on your PC:


Here manjaro-phosh is the subvolume that's actually booted, .pre-boot/manjaro-phosh is snapshot of the manjaro-phosh before it was booted for the first time and .pristine/manjaro-phosh is the snapshot of the original root filesystem of the distribution, before I applied any fixes to it, to make it not mess up the multi-distribution image with so called first boot scripts.

So if you want to restore one of the distributions to the original state, you can simply run:

btrfs subvolume delete manjaro-phosh
btrfs subvolume snapshot .pre-boot/manjaro-phosh manjaro-phosh

And that's it. Next time you boot manjaro-phosh, it will be in the original state. This is useful if some update breaks the distro, or whatever.

You can use this to your advantage, and make a snapshot before trying some new thing that can potentially make the distribution unusable.

btrfs subvolume snapshot manjaro-phosh manjaro-phosh-2021-10-13

Go wild and if anything breaks, you can recover with:

btrfs subvolume delete manjaro-phosh
btrfs subvolume snapshot manjaro-phosh-2021-10-13 manjaro-phosh

In fact you can create several snapshots of the same distribution, add boot menu for each snapshot (snapshot is itself a subvolume and snapshots in btrfs are writable) and just use both snapshots in parallel. :)

If you don't want to keep losing your data in /home or /root when you switch between OS snapshots, you can create subvolumes for those directories and mount those subvolumes via fstab. That way you can revert from failed OS update, but keep your data (or share data between distributions in the multi boot image in general).

If you want to save space you can delete distributions you don't like from the multi-distro image:

btrfs subvolume delete manjaro-phosh
btrfs subvolume delete .pre-boot/manjaro-phosh
btrfs subvolume delete .pristine/manjaro-phosh
p-boot-unconf boot-export /dev/mmcblk0p1
# remove manjaro phosh from boot-export/boot.conf
p-boot-conf boot-export /dev/mmcblk0p1

The similar way (just in revers) you can add any new distribution to the multi-boot image:

btrfs subvolume create new-distro

# get rootfs tarball for the distro from somewhere
bsdtar -xp --numeric-owner -C new-distro -f tarball.tar.gz

p-boot-unconf boot-export /dev/mmcblk0p1
# add new-distro to boot-export/boot.conf (you can get inspiration
# by looking at the existing boot entries on how to do it)
p-boot-conf boot-export /dev/mmcblk0p1

And that's pretty much it. You may even boot the distro's own kernel and initramfs, if it supports btrfs out of the box. Otherwise, you can stick with my kernel.

If you want to update my kernel, the latest version is always available at: in the ppd.tar.gz package. You only need to copy the Image file over linux-0.img and board-1.1.dtb over dtb-0.img and board-1.2.dtb over dtb2-0.img in the boot-export directory.

Once you have the boot filesystem exported to some directory, you don't need to keep re-exporting it over and over again. You can skip the p-boot-unconf boot-export /dev/mmcblk0p1 from then on.

You can also have multiple boot options for the same distribution in the boot menu. I use this to try different kernels during development. If one fails, I just boot the older one that is known to work.

The same way you can experiment with different crust or TF-A versions, without ever having to remove the back cover of your pinephone again.

All this management is also doable from the booted pinephone itself.

P-boot is that good. :)

The necessary tools are pre-built in the p-boot repository.

(WARNING: All filenames in the above text are examples, you have to modify the commands to your own situation/needs!)