8.2 KiB
Firmware notes
Early July update
Starting early July 2020, this project provides a beta quality graphics-and-USB enabled U-Boot for the Pinebook Pro. This is made possible by using a preview of upcoming patches to U-Boot. See the Acknowledgements section of this document.
This will be called the opinionated firmware. It deviates from some U-Boot defaults, while keeping in the spirit of the original defaults.
TIP: Look at the Known issues section to know about the known issues!
This U-Boot build should be usable by users from other distributions, though has been customized a bit visually for NixOS users.
The boot order is, with the default build, the upstream boot order from U-Boot. Which means that it will first try to boot from eMMC, then from SD, then from USB.
Our opinionated changes, though, make it trivial to select an alternative boot option for one boot. You can cancel the default boot by mashing CTRL+C when prompted (and a bit later too).
Once canceled, you will be presented with a menu depicting the boot options that are normally tried in order.
*** U-Boot Boot Menu ***
Default U-Boot boot
Boot from eMMC
=> [Boot from SD]
Boot from USB
Boot PXE
Boot DHCP
Reboot
U-Boot console
Press UP/DOWN to move, ENTER to select
By selecting another option, the firmware will try to boot once from the given storage using the default U-Boot distro commands.
At the time of writing, the default boot sources on a device are:
- Bootable partition with an extlinux.conf compatible boot under
/or/boot(scan_dev_for_extlinux) - Bootable partition with boot scripts
boot.scr.uimgorboot.scrunder/or/boot(scan_dev_for_scripts) - UEFI program
efi/boot/bootaa64.efi(scan_dev_for_efi)
Building
If you're building on x86_64, it will automatically use cross-compilation. In that case the build should work assuming cross-compilation is working fine on current unstable.
Otherwise, on-device or on any other AArch64 system, the build should be trivial.
$ nix-build -I nixpkgs=channel:nixos-unstable -A pkgs.pinebookpro-firmware-installer
Installing to SPI flash
This is not mandatory. The opinionated firmware still works just as well installed to SD or to eMMC.
These instructions assume the use of the opinionated U-Boot we are providing. You can also install to SPI using any other documented method.
Before starting, you will need an SD card on which you can write the Firmware installer image. This will overwrite the contents of that SD card.
# Replace sdX with the correct block device for your SD card.
# /dev/disk/by-path/platform-fe320000.dwmmc is the SD card on the Pinebook Pro
$ sudo dd if=firmware-installer-image.img of=/dev/sdX bs=512 oflag=direct,sync
With your SD card ready, you will need to boot our U-Boot build. My recommendation is to either install the updated U-Boot to your eMMC, or render your eMMC unbootable and boot from the firmware installer SD image.
To render the eMMC unbootable, from a booted system:
# This will prevent the U-Boot installed to eMMC from running.
$ sudo dd if=/dev/zero of=/dev/disk/by-path/platform-fe330000.sdhci bs=512 count=1 seek=64 oflag=direct,sync
$ sudo dd if=/dev/zero of=/dev/disk/by-path/platform-fe330000.sdhci bs=512 count=1 seek=16384 oflag=direct,sync
Once booted in our opinionated U-Boot build, you will need to then boot the SD image's installer scripts. From this U-Boot, you can cancel the boot process by mashing CTRL+C. Once canceled, select Boot from SD.
*** U-Boot Boot Menu ***
Default U-Boot boot
Boot from eMMC
=> [Boot from SD]
Boot from USB
Boot PXE
Boot DHCP
Reboot
U-Boot console
Press UP/DOWN to move, ENTER to select
This will present you with another menu.
*** U-Boot Boot Menu ***
=> [Flash firmware to SPI]
Completely erase SPI
Reboot
U-Boot console
Press UP/DOWN to move, ENTER to select
The options are self-explanatory. You shouldn't need to erase the SPI, unless you want to completely remove any traces of an installation.
Note that there are no further confirmation prompts. Selecting the Flash firmware to SPI option will install to the SPI flash.
395 bytes read in 4 ms (95.7 KiB/s)
## Executing script at 00500000
pinebook-pro-rk3399 firmware installer
1560028 bytes read in 188 ms (7.9 MiB/s)
SF: Detected gd25q128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB
SF: 1560576 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x17cddc
SF: 1560028 bytes @ 0x0 Written: OK
Flashing seems to have been successful! Resetting in 5 seconds
Once this is done, the Pinebook Pro will reboot automatically. From this point on you do not need U-Boot to be installed to the eMMC or to an SD card.
From other U-Boot builds
For non-opinionated U-Boot, you can run the command run bootcmd_mmc1 from
its CLI. Note that the U-Boot build will need to support boot menus, which is
not a default option, in addition to be configured with the ability to write to
the SPI flash. This will start the menu-based install.
You can also use the sf command to install it manually. Explaining this is
out of scope of this document.
Known issues
These are the current issues that makes this a beta release.
As far as the testing done goes, they do not cause any harm to the normal operation of the booted system, while being a net upgrade over the previous firmware which had no way for the user to select boot options via the device.
Keyboard input is wonky
I do not know how to better describe it. Sometimes the input is immediate, sometimes it will take a hot second before it happens. I recommend pressing an arrow key once and waiting up to 5 seconds (usually 2) when navigating the menu. Otherwise you may overshoot if you are impatient.
It may also be worsened by mixing serial input and keyboard input, but has not been conclusively validated.
Saving settings to SPI
While there is a patch upstream to do so, it seems to cause issues with USB input. This is to be investigated.
Hangs with kernel 5.6+
Using the patchset from tsys, which I believe is the gold standard, the graphics-enabled U-Boot will not boot kernels 5.6, 5.7 and the wip 5.8.
For the three kernel versions, the boot hangs at the what seems to be the same location.
For the time being, use the 5.4 LTS (or 5.5 if you don't mind an unmaintained kernel.)
FAQ
Why install to SPI flash?
This makes the Pinebook Pro act just like any other laptop. You can erase all the storage devices (SPI is not a storage device exactly) and still get a useful, albeit limited boot.
This also means that the user is fully in control of the storage. There is no special offset where they are required to install a program for the computer to boot successfully.
Finally, with the minimal UEFI support of the Pinebook Pro, and USB support, it is possible to boot a generic UEFI iso installer, just like you would on any other normal and sensible laptop. Once the upstream Linux kernel fully supports the Pinebook Pro, there will be no need for device-specific image or installation instructions. You will be able to install just like you would any other dumb laptop.
My machine does not boot after rendering the eMMC U-Boot unbootable
If you accidentally boot your machine without a firmware installed, your Pinebook Pro may look like it doesn't want to boot anymore. In fact it is likely booted into maskrom mode. Hold power for 15 real seconds, then try powering on with a known good SD card.
My machine does not boot after installing to SPI and is not in maskrom mode
Oof, first of all, sorry. In testing I have never had a flashing render my device unbootable.
Rescuing your device is not specific to this project. You can follow the instructions from the Pine64 forums to recover from a broken SPI flash.
Acknowledgements
Without access to a nearly final revision of the Graphics fixes for the Pinebook Pro, this wouldn't have been possible. Thank you Arnaud Patard from Hupstream for allowing me to release the preview build to the benefit of Pine users all around the world.