Add firmware docs
This commit is contained in:
Samuel Dionne-Riel
parent
4a5f52ac08
commit
05483d110a
|
|
@ -0,0 +1,253 @@
|
|||
# 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.uimg` or `boot.scr` under `/` 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.
|
||||
|
||||
- https://gitlab.manjaro.org/tsys/linux-pinebook-pro
|
||||
|
||||
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](https://forum.pine64.org/showthread.php?tid=9059)
|
||||
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.
|
||||
21
README.md
21
README.md
|
|
@ -66,6 +66,8 @@ while most other packages can be fetched from the cache.
|
|||
|
||||
## `u-boot`
|
||||
|
||||
> **NOTE**: The following instructions are for if you haven't installed U-Boot to the SPI flash.
|
||||
|
||||
Assuming `/dev/mmcblk0` is an SD card.
|
||||
|
||||
```
|
||||
|
|
@ -78,10 +80,11 @@ the eMMC as a boot device first.
|
|||
|
||||
Alternatively, this u-boot can be installed to the eMMC.
|
||||
|
||||
Installing to SPI has yet to be investigated.
|
||||
|
||||
### Updating eMMC u-boot from NixOS
|
||||
|
||||
> **NOTE**: The following instructions are for if you haven't installed U-Boot to the SPI flash.
|
||||
|
||||
**Caution:** this could render your system unbootable. Do this when you are in
|
||||
a situation where you can debug and fix the system if this happens. With this
|
||||
said, it should be safe enough.
|
||||
|
|
@ -115,3 +118,19 @@ the image to your eMMC keeps external devices bootable.
|
|||
```
|
||||
|
||||
Note: poweroff must be used, reboot does not turn the hardware "off" enough.
|
||||
|
||||
|
||||
## About pre-built images
|
||||
|
||||
It is assumed that the official binary cache can be trusted. Any other source
|
||||
for images is of unknown trustworthiness.
|
||||
|
||||
As a broader goal of trust within the NixOS community, we strongly recommend
|
||||
users build their own images on hardware they trust so they know the
|
||||
provenance.
|
||||
|
||||
This is why this repository does not offer pre-built images. I would also like
|
||||
that no third party pre-built images are produced.
|
||||
|
||||
Once the upstream kernel fully supports the Pinebook Pro, it will not be an
|
||||
issue as the generic AArch64 images will work with the Pinebook Pro.
|
||||
|
|
|
|||
Loading…
Reference in New Issue