HowTo: PINEBOOK Pro with Debian GNU/Linux 10 or Devuan GNU+Linux 3 using mainline kernel and u-boot

Posted on 5 January, 2021 at 04:10 UTC by Daniel Kulesz

Category: meta

I have written this guide to outline how I finally managed to get the official version of Devuan GNU+Linux 3 or Debian GNU/Linux 10 installed on a PINEBOOK Pro. It shows how to achieve this using official mainline u-boot and kernel from upstream (no unofficial patches) and without using third-party repositories. However, it does use self-compiled (unpackaged) versions of u-boot and kernel as tweaking their default build configuration files is currently still required.

This is how the result looks like on my device:

PBP

Status

As of 2021-01-05:

Most basic functionality is there.
The display works but requires the official Debian kernel to be recompiled with one configuration parameter changed (covered in this guide).
Adjusting the display brightness using hotkeys does not work out-of-the-box (at least in LXQt).
The disk encryption password has to be entered either blindly on-device or using the serial console as the display turns on too late (during init instead of initramfs). If you you decide to enter the password on-device, boot messages will still be displayed on the serial console (but no password prompt).
The microSD functionality is broken (several kernel errors).
Using external video-out and wifi requires loading non-free blobs (the ones for wifi can be installed using official Debian packages from the non-free section). I am not sure whether this applies to bluetooth as well.
Reboots often result in garbled screen output. Therefore, to perform a reboot, it is advised to turn the device off and on again.
Using further deblobbed sources (e.g. Linux/Libre or cleaned trusted firmware) has not been tried.

Covered topics and goals

This guide builds upon my general guide for building Devuan GNU+Linux 3 or Debian GNU/Linux 10 for various ARM64 boards [1]. It basically adds steps which are specific for the PINEBOOK Pro. The goal is to supplement my general guide instead of copying it.

As the display does not work directly after installation, a working serial console connection to your PINEBOOK Pro is required. Alternatively, you could log in remotely using a USB-ethernet adapter or include the steps in the preparation, but these alternatives are not covered in this guide.

Caution: This guide is WORK-IN-PROGRESS (WIP) and has not been fully tested.

Disclaimer

All data and information provided in this tutorial is for informational purposes only. The author makes no representations as to accuracy, completeness, currentness, suitability, or validity of any information on this tutorial and will not be liable for any errors, omissions, or delays in this information or any losses, injuries, or damages arising from its display or use. All information is provided on an as-is basis.

In no event, the author will be liable for any loss or damage including without limitation, indirect or consequential loss or damage, or any loss or damage whatsoever arising from loss of data or profits arising out of, or in connection with, the use of this tutorial.

Prepare the assets

Follow my general guide for installing Debian/Devuan on arm64 [1] but with the following deviations:

Step 2: Install the unstable kernel (it is marked as optional in the guide, however, the PINEBOOK Pro requires it).
Step 3: Do not install the ssh server and dropbear (unless you really want to).
Step 3: Do not delete your regular user (you don’t want to have just root on a laptop).
Step 5: This guide has been written using version tags v2.4 for the trusted firmware and v2020.10 for u-boot.
Step 5: When building u-boot, use the configuration file pinebook-pro_defconfig, but comment the line (PREBOOT=y) in it before building (obtained this hint from [2]). The configuration file resides in the configs subdirectory of u-boot.
Step 6 and 7: Skip these steps, as they differ substantially (this is what this guide is for).

Initial installation / flashing

As of now, the Linux kernel 5.10 shipped in Debian unstable has severe issues with microSD cards. Therefore, it is required to install a different OS on the PINEBOOK Pro first and flash our Debian/Devuan files from there.

Grabbing artifacts

First of all, copy the following artifacts from step 5 to a USB drive:

devuan-aarch64-bootfs.tar.gz
devuan-aarch64-rootfs.tar.gz
idbloader.img
u-boot.itb

Preparing Armbian

This guide assumes that the installation on the PINEBOOK Pro is done using Armbian. Therefore, download and flash Armbian as described on their website to a microSD card. Once you have Armbian running, connect to the internet (e. g. using wifi or an USB-Ethernet adapter).

Next, install additional packages:

apt install cryptsetup f2fs-tools sfdisk

Now, insert the USB drive with the files from step 5, mount it (if not done automatically) and change to the directory where it is mounted. We will refer to this path as /path/to/your/mounted/usb/drive/ in the rest of this guide.

Verifying disks (IMPORTANT)

Before we start flashing, verify using fdisk that mmcblk2 is your internal eMMC flash and mmcblk1 is the microSD card from where your Armbian is running:

fdisk -l

IMPORTANT: Do not execute the following steps if this is not the case!

Flashing

Wipe out the first sectors of the internal eMMC:

dd if=/dev/zero of=/dev/mmcblk2 bs=1M count=100
sync

Create a sfdisk template:

cat <<'EOF'>>sfdisk.template
label: mbr
unit: sectors
first-lba: 64

start=        2048, size=       16384
start=       18432, size=      614400, bootable
start=      632832
EOF

Partition the internal eMMC flash:

/sbin/sfdisk devuan3-rockpro64.img < sfdisk.template

Format the boot partition:

mkfs.ext4 -m0 -L boot /dev/mmcblk2p2

For the root partition, create an encrypted partition (choose a strong passphrase), unlock it, and format it using the f2fs filesystem:

cryptsetup luksFormat /dev/mmcblk2p3 --label=rootencrypted
cryptsetup luksOpen /dev/mmcblk2p3 somename
mkfs.f2fs -l root /dev/mmcblk2p3

Flash the boot partition:

mount /dev/mmcblk2p2 /mnt
cd /mnt
tar xzvpf /path/to/your/mounted/usb/drive/devuan-aarch64-bootfs.tar.gz .
sync
cd
umount /mnt

Flash the root partition:

mount /dev/mapper/somename /mnt
cd /mnt
tar xzvpf /path/to/your/mounted/usb/drive/devuan-aarch64-rootfs.tar.gz .

Change the following line in /mnt/etc/inittab (only required for Devuan, not for Debian):

#T0:23:respawn:/sbin/getty -L ttyAMA0 115200 screen
T0:23:respawn:/sbin/getty -L ttyS2 1500000 screen

In addition, uncomment the following lines in order to activate the regular consoles in /mnt/etc/inittab as well (again, this only applies to Devuan):

1:2345:respawn:/sbin/getty 38400 tty1
2:23:respawn:/sbin/getty 38400 tty2
3:23:respawn:/sbin/getty 38400 tty3
4:23:respawn:/sbin/getty 38400 tty4
5:23:respawn:/sbin/getty 38400 tty5
6:23:respawn:/sbin/getty 38400 tty6

Unmount the stuff:

cd /path/to/your/mounted/usb/drive/
umount /mnt
cryptsetup luksClose /dev/mapper/somename

Flash the bootloader and sync the contents:

dd if=idbloader.img of=/dev/mmcblk2 seek=64 conv=notrunc
dd if=u-boot.itb of=/dev/mmcblk2 seek=16384 conv=notrunc

Powering down

Shutdown down Armbian.
Remove the microSD card.

Intermediate test

Connect your serial console to the PINEBOOK Pro and another computer. Start your serial emulator and connect it. If you are using picocom and have only one USB-Serial device connected, the following should do:

picocom -b 1500000 /dev/ttyUSB0

Now, power on your PINEBOOK Pro and watch it boot. You should see u-boot and the kernel booting, then it should stop in initrd asking for the disk encryption password. Enter the password, let the boot finish and log in.

Getting the display to work

There are basically two reasons why the display does not work out-of-the-box:

Additional kernel modules need to be loaded (see [3]).
The configuration used by Debian to compile the Linux kernel sets a parameter that needs to be changed (see [4]).

Loading additional kernel modules

Add the required modules to the initramfs configuration:

cat <<'EOF'>>/etc/initramfs-tools/modules
analogix_dp
drm
drm_kms_helper
panel-simple
pwm_bl
rockchipdrm
EOF

And rebuild the initramfs:

update-initramfs -u

Recompiling the kernel

You can recompile the kernel either on the PINEBOOK Pro directly or on another machine running Debian/Devuan. I recommend the latter as it takes quite long on the device itself at heats it up which is not ideal for the battery.

No matter where you build, install the following packages:

apt install build-essential gcc-aarch64-linux-gnu git unzip bison flex libssl-dev bc pigz

Then grab the official Linux kernel source (use the current version and verify the download as described on kernel.org):

wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.10.4.tar.xz

Unpack the sources:

tar xvf linux-5.10.4.tar.xz

Copy the default Debian kernel config (if you are building externally, copy it to the machine where you are doing it):

cd linux-5.10.4
cp /boot/config-`uname-r` .

Edit the .config file and change the following line so its value is an empty string:

CONFIG_SYSTEM_TRUSTED_KEYS=""

Also change the setting CONFIG_ROCKCHIP_CDN_DP as follows:

# CONFIG_ROCKCHIP_CDN_DP is not set

In addition, I recommend adding some string to your kernel to make it better recognizable:

CONFIG_LOCALVERSION=".my01"

Also, change the following entry in the Makefile to significantly speed up packing when compilation ends:

#XGZIP = gzip
XGZIP = pigz

Start the build (on-device):

make -j6 bindeb-pkg

Or if you are building on a different device (change -j16 to match the number of the CPU threads you want to use, typically the maximum you have):

make -j16 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bindeb-pkg

After the build finishes, you should get the following Debian packages in the parent of the directory where you unpacked the kernel source (names will differ if you used a different kernel):

linux-headers-5.10.4.my01_5.10.4.my01-1_arm64.deb
linux-image-5.10.4.my01_5.10.4.my01-1_arm64.deb
linux-image-5.10.4.my01-dbg_5.10.4.my01-1_arm64.deb
linux-libc-dev_5.10.4.my01-1_arm64.deb

If you built the kernel externally, copy these files to your PINEBOOK Pro (otherwise you can use them directly). Install the kernel package (the other debs are only required for debugging and compiling additional modules):

dpkg -i linux-image-5.10.4.my01_5.10.4.my01-1_arm64.deb

Remove the currently installed kernel and the metapackage (otherwise updates could break your display again):

apt autoremove linux-image-`uname-r`

Check the symlinks in /boot/vmlinuz and /boot/initrd.img point to the newly installed kernel:

ls -l /boot

That’s it! Power down the PINEBOOK Pro (do not just reboot as this might cause garbled display output). Power the device back on, wait a bit and enter your drive encryption password using the serial console. After entering the password, your screen should finally turn on.

Remember: You are now running your device with a self-compiled kernel that gets no automatic updates. Make sure you download, build and install new kernel versions regularly so you don’t miss out on security updates!

Enter drive encryption password on-device

I did not succeed to persuade the display to turn on before the password prompt is shown. However, you can choose to enter the password “blindly” on-device. You will get boot messages on the serial console but the password will need to be entered on-device. To do this, add the following parameter in the append line to your /boot/extlinux/extlinux.conf line:

console=ttyS2,1500000 console=tty0

Power down the laptop, power it on, wait aprox 30 seconds and enter the password blindly to continue booting.

Increasing backlight brightness

Changing the brightness via hotkeys does not work ootb on the LXQt desktop. However, the brightness of the display’s backlight can be set to maximum via the following command as root:

echo 4095 > /sys/devices/platforms/edp-backlight/backlight/edp-backlight

The value 4095 is the maximum, you can also set a lower value of course.

Additional blobs for wifi and video-out

I discourage the use of non-free blobs and recommend using the PINEBOOK Pro with a ath9k-based USB wifi dongle instead. However, if there is interest I will update this section and add the necessary steps.

Credits

I would like to thank all the helpful minds in the official PINE64 forums (especially the users “toons”, “as400” and “schwarzwieweiss”) who pointed me to the principal solutions for some of the steps covered in this guide.

External References

(The providers of external resources are solely responsible for them - see legal notice).

History / Changelog

[2021-01-09] Added missing kernel config parameter (ROCKCHIP_CDN_DP)
[2021-01-07] Added photo, refined information about non-free blobs
[2021-01-05] Changed info about not being able to enter password on-device, added section how to achieve this, added section about display brightness
[2021-01-05] Posted in forums (PINE64 and dev1galaxy) and updated status, fixed mmcblk1 mention in section “Verifying disks”, fixed various small glitches
[2021-01-05] First publication

Comments

(Comment features are provided by external parties and are not monitored by me.)

Please use the discussion forum thread in [4]. I will consider adding further options once this guide gets more mature.