Pinebook Pro Recovery with Void Linux (xbps)

[bds]

Pinebook Pro Recover with Void Linux (xbps)

Hello all!

I recently received my Pinebook Pro and, as I have gathered has happened to quite a few people, broke the system with an initial Manjaro update. I thought I'd do my part to help anyone else having the same problem by documenting what I've figured out over the last few days. This will basically be a compilation of a bunch of different articles and tutorials from across the internet, with application specific advice. I'll try to link all major sources. I chose to use Void Linux just 'cause it's what I'm used to, and xbps makes building a system onto the SD card super easy.

While I've learned a lot through this process, I'm by no means an expert. I would appreciate any input, correction, or elaboration the topics discussed.

Just to account for any hardware differences, this was on a PBP received on Jan 11 2024. I haven't checked into this, but if there's any where I can find a hardware revision number or anything like that, let me know.

Some preamble:
The PBP can boot directly from, in order:
- the onboard SPI module,
- the onboard eMMC module, or
- a microSD card.

By default, nothing is written to the SPI. The factory Manjaro ARM system is installed on the eMMC. From what I understand, the system breaks after a Manjaro update because the system updates the bootloader package without properly configuring it. The result is that the PBP boots from the eMMC, but the user gets nothing but a black screen.

Fortunately, the PBP mainboard has a hardware switch to block access to the eMMC, so we can turn that on and boot instead from a microSD card.

Regarding the bootloader, I to use Tow-Boot. I don't have experience any with alternatives, but it was simple to flash and is flexible at boot-time, which is what I was looking for.

So this was my strategy:
1. Disable the eMMC
2. Boot from SD card
3. Flash Tow-Boot to the SPI
4. Re-enable the eMMC
5. Boot again from the SD card
6. ???
7. System repaired.

If I wanted to, I think I could have skipped a couple steps by re-enabling the eMMC while the system was running and flashing Tow-Boot to the eMMC's boot partition. However, I like having the bootloader on the SPI and didn't want to keep Manjaro anyways. Furthermore, this method lets me use GPT and EFI; this probably doesn't matter but it just feels right.

# Setup
To start off with, we're gonna want an existing Void Linux system, though you should be able to follow the same process on any Linux system using a statically-linked XBPSThis can be from a live image, though depending on your setup that might present some issues with memory and device throughput when writing to the SD card.

First off, we're gonna want to make sure all our repositories and packages are up to date:

Code:

# xbps-install -Su xbps
# xpbs-install -Su

Next, we'll make sure we have the packages we need for building the system on the SD card. `binfmt` and `qemu-static-user` are required for cross-building, so they're not required on an aarch64 host system.

Code:

# xbps-install -Su xz wget xtools binfmt-support qemu-user-static

Enable the `binfmt-support` service:

Code:

# ln -s /etc/sv/binfmt-support /var/service

# Building the SD card
First, identify your SD card's device handle. If your host system has built-in SD card support, it will likely be `/dev/mmcblkX`. I was using a USB adapter, so mine was at `/dev/sdX`.

## Flash Tow-Boot to the SD card
It should go without saying, but make sure to back up anything you don't want to lose.

Download and extract Tow-Boot for the PBP:

Code:

# wget https://github.com/Tow-Boot/Tow-Boot/releases/download/release-2022.07-006/pine64-pinebookPro-2022.07-006.tar.xz
# tar xvf pine64-pinebookPro-2022.07-006.tar.xz

Flash Tow-Boot to the SD card. For reference, we're using the "shared storage strategy.":

Code:

# dd if=pine64-pinebookPro-2022.07-006.tar.xz/shared.disk-image.img of=/dev/XXX bs=1M oflag=direct,sync status=progress

## Install Void via chroot
This next portion follows this guide from the Void Handbook. In particular, we're using the XBPS method.

### Partition and format the SD card
Flashing Tow-Boot should have created initialized a GPT partition table and created a partition at the beginning of the SD card. I used cfdisk to partition the rest of the SD card, so it looks like this:
/dev/sdg1 = Tow-Boot
/dev/sdg2 = +256M, EFI System
/dev/sdg3 = to the end of the disk, Linux Filesystem.

After that, create the filesystems:

Code:

# mkfs.vfat /dev/sdg2
# mkfs.ext4 /dev/sdg3

### Mount the new filesystems

Code:

# mount /dev/sdg3 /mnt
# mkdir -p /mnt/boot/efi
# mount /dev/sdg2 /mnt/boot/efi

### Creating the base installation
A caveat: I don't actually know what the ideal kernel and firmware situation looks like. Void's Pinebook Pro packages seem fairly old, and I specifically want to avoid the `pinebookpro-uboot` package (and the `pinebookpro-base` package which depends on it). I opted to use the basic linux kernel and install the `pinebookpro-firmware` package, because I figured it couldn't hurt. Regardless...

We want to set environment variables that we'll use to tell XBPS which repo to pull from and what architecture to use. Set `ARCH` to either `aarch64` or `aarch64-musl` to use glibc or musl, respectively.

Code:

# REPO=https://repo-default.voidlinux.org/current/aarch64
# ARCH=aarch64-musl

Copy the RSA keys from the host to the SD card:

Code:

# mkdir -p /mnt/var/db/xbps/keys
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/

And finally we'll use XBPS to bootstrap the installation.

Code:

# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system pinebookpro-firmware linux

### Configuration
Chroot into the new installation using `xchroot`:

Code:

# xchroot /mnt /bin/bash

Set the root password:

Code:

[xchroot /mnt] # passwd

Follow the instructions in the Void Handbook for configuring fstab and for installing GRUB. We want to use the instructions for UEFI, with the `grub-arm64-efi` package, and use the `--removable` flag on `grub-install`

Before leaving the chroot, install `mtd-utils`, which has the `flashcp` utility we'll use for flashing to the SPI, and run `xbps-reconfigure` to make sure everything's set up correctly.

Code:

[xchroot /mnt] # xbps-install mtd-utils
[xchroot /mnt] # xbps-reconfigure -fa
[xchroot /mnt] # exit

### The final touch
Before unmounting the SD card and slapping it into the PBP, copy over the Tow-Boot image we're gonna flash to the SPI.

Code:

# cp pine64-pinebookPro-2022.07-006/binaries/Tow-Boot.spi.bin /mnt/root
# umount -R /mnt

## Booting the SD card and flashing the SPI
As long as the eMMC is disabled, you should now be able to insert the SD card and boot into it through Tow-Boot, followed by GRUB. Log in using the root password you set earlier, and flash the Tow-Boot image we copied over onto the SPI:

Code:

flashcp Tow-Boot.spi.bin /dev/mtd0

At this point, you should be able to remove the SD card, enable the eMMC, reboot the machine, and be met with the Tow-Boot graphical interface, though the system installed on the eMMC will likely still be unusable. I leave repairing/replacing the system installed on the eMMC as an exercise for the reader. I followed a similar process to what's described above to install Void Linux with EFI boot. It should be noted that GPT doesn't play well with the layout of the eMMC's boot memory, so you should zero out the first 32768 bytes and skip them in your partition scheme, or perhaps just flash Tow-Boot's `noenv` image onto it. This document was helpful for some details.

That's all, thank you.