From PINE64
Jump to navigation Jump to search
Working on a page about setting up a p-boot test platform here. Will post and link the article appropriately when finished.

P-boot Introduction

P-boot is a bootloader for the pinephone by Ondrej Jirman (user name Megous, aka Megi). It is capable of supporting a multi-boot installation, similar to Grub in a desktop environment, enabling the install of multiple distributions on a single sd card. In combination with a btrfs filesystem, it is possible to backup and restore entire OS installations utilizing btrfs shapshots. For example, on one sd card a user can install or remove several distributions, including a preferred known working installation, with each entire OS routinely backed up before updating or changing configurations. In the event of breakage any snapshot OS is restored with a few simple commands. The above functionality is maintained without ever having to change the partition structure of the sd card.

The Multi-boot Demo Image

The simplest way to try not only p-boot, but also a wide selection of distributions for the Pinephone, is with the PinePhone multi-distro demo image, also produced by Megi. This makes an excellent beginner's first experience with burning an image to sd card, as it provides the new PinePhone user the opportunity to immediately try a wide selection of distributions and mobile environments. The distributions are fully updatable, though U-boot and kernel upgrades have been inhibited to prevent breaking the installation. The demo image provides a template for a nearly complete multiboot test platform for Pinephone.


See the PinePhone multi-distro demo image homepage for current download options, which include torrent or direct download via the project site or mirror. The image is also available through purchase of a preloaded sd card (via third-party @ For faster downloads, and to support seeding, use your preferred torrent application. To obtain via direct download (bandwidth limited):

wget -c

wget -c

  • Verify the file signature of the compressed image:

sha256sum multi.img.zst

cat SHA256

  • Decompress the image:

zstd -d multi.img.zst

Structure of the demo image

Before we flash to sd card, let's take a look at the decompressed demo image:

$ sudo fdisk -l multi.img
[sudo] password for xxxx: 
Disk multi.img: 9.28 GiB, 9961472000 bytes, 19456000 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x12345678

Device     Boot  Start      End  Sectors  Size Id Type
multi.img1 *      8192   409599   401408  196M 83 Linux
multi.img2      409600 19455999 19046400  9.1G 83 Linux

The image contains an MSDOS partion table (disklabel). There are two partitions. Both are coded (83) as type "Linux". The boot flag on the first partition is set. This is what will be written to our device during installation.


The p-boot demo image is flashed either to a micro sd or to the pinephone's eMMC, just as any other Pinephone software release image. See PinePhone Installation Instructions for more details.

For this portion of the guide we will assume the user is flashing from a desktop/laptop linux installation to an sd card reader. In this context the block device you will write to should be named /dev/sdX, and the first partition on that device /dev/sdX1, where "X" is the proper drive letter for the card reader. When performing disk operations use extreme caution to verify the correct device. Flashing will destroy all data on the target. Note that the demo image will be flashed to the whole device (e.g. sdX), not a device partition (e.g. sdX1).

To flash a micro sd using dd;

  • Verify the correct device:


  • Flash the image:

sudo dd if=multi.img of=/dev/sdX bs=4M oflag=direct status=progress

  • Optional: verify the write (must be done before mounting or booting):

dd if=/dev/sdX bs=1M count=9500 | sha256sum

cat SHA256

Congratulations! You have successfully flashed the demo image, which is bootable at this stage. You wouldn't want to update anything or use much space yet, though. To make room for extended use your installation you still need to resize the main partition and the filesystem inside. To do that:

Verify the proper block device for the demo image main partition:

blkid -lt PARTUUID="12345678-02"

Do a dry run (-n) of resizing the partition:

echo ", +" | sfdisk -n -N 2 /dev/sdX

Review the output carefully. When you are fully comfortable this is correct, perform the resize:

echo ", +" | sfdisk -N 2 /dev/sdX

A muti-boot test platform with p-boot and btrfs

As you have seen in the resize operation above, the demo image utilizes a btrfs filesystem for its main partition. Linux users are aquainted with ext filesystems, but may not yet be familiar with btrfs. Btrfs is a next generation filesystem with features particularly suitable for setting up a flexible multiboot test system for Pinephone. Some features are outside the scope of this guide, but as most relevant here, btrfs has the following:

About Btrfs


Traditionally, multi-boot installations have been implemented by creating individual disk partitions for each OS. Each partition is allocated a specific amount of space, with the filesystem consuming the entire partition. This results in increasing wasted space with increasing numbers of partitions, and introduces a significant maintenance overhead for adding additional operating systems.

Btrfs provides an alternative in subvolumes. Subvolumes are filesystem divisions which may each be independently mounted as contained filesystems. They act as something of a cross between partitions and directories. Subvolumes are not device partitions, and remain a part of the top level btrfs filesystem residing on the partition as a whole. This means they are free to grow or shrink within the overall filesystem. Additionally, subvolumes may contain other subvolumes. Within a mounted subvolume, an enclosed subvolume will appear and function essentially as a directory.

Copy-on-write (CoW) capability

With CoW, when data is copied, the filesystem only actually writes metadata describing the copy to be performed. A second physical copy is not created on disk unless either the original data or its copy is changed. This means storing copies of data is extremely efficient; very little disk space is consumed for copies, no matter how much storage the original data occupies. When copies do change, the extra space consumed is only the amount of the individual files that have changed, not the entire subvolume (plus a small amount of filesystem metadata overhead).

Subvolume snapshots

Subvolume snapshots are a powerful application of the combination of subvolumes and CoW. An entire subvolume (for our purposes this will usually be an entire OS filesystem) can be copied as easily as:

sudo btrfs subvolume snapshot /path/to/original /path/to/copy

The copy will thereafter exist in the filesystem but occupy almost no space unless the original or copy changes.

Btrfs operations

Traditional tools to measure available space on the filesystem, such as du and df, are not reliable when applied to btrfs. The following command will provide extensive filesystem usage information. The output line "Free (estimated):" provides a reasonable estimate of free space available.

sudo btrfs fi usage /filesystem/mount/path

Renaming a subvolume (this is done while mounted) is as simple as moving it from the original name to the new name:

sudo mv /mnt/oldname /mnt/newname

To list the subvolumes in a filesystem:

sudo btrfs subvolume list -t /filesystem/mount/path

Installing an OS

Download the desired Pinephone software release.

Verify and decompress the image.

Connect the distro image to a loopback device:

sudo losetup -P /dev/loop0 distro_imagefile.img

Mount the distro image partitions

sudo mount -o ro /dev/loop0p1 /mnt/l0.1

sudo mount -o ro /dev/loop0p2 /mnt/l0.2

Create a subvolume to house the OS:

sudo btrfs subvolume create /mnt/btrfs_mnt_point/subvolume_name

sudo rsync -vaxHAX --progress /mnt/l0.2/ /mnt/btrfs_mnt_point/subvolume_name

sudo rsync -vaxHAX --progress /mnt/l0.1/ /mnt/btrfs_mnt_point/subvolume_name/boot

External links