Add firmware docs

FIRMWARE.md

@@ -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.

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.