[U-Boot] [PATCH 5/5] sunxi: doc: Add basic fastboot example

[Priit Laes]

From: Priit Laes <priit.laes at paf.com>

Signed-off-by: Priit Laes <plaes at plaes.org>
---
 board/sunxi/README.fastboot | 98 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 98 insertions(+)
 create mode 100644 board/sunxi/README.fastboot

diff --git a/board/sunxi/README.fastboot b/board/sunxi/README.fastboot
new file mode 100644
index 0000000..470fa6f
--- /dev/null
+++ b/board/sunxi/README.fastboot
@@ -0,0 +1,98 @@
+Using fastboot on sunxi devices
+===============================
+
+Fastboot is a diagnostic protocol, primarily used to modify the
+filesystems on the flash device via USB or UDP. It requires that
+the device is started in a boot loader or Seconday Boot Loader mode.
+
+This document currently walks through an installation with a device
+with eMMC storage.
+
+Prerequisites
+-------------
+
+* fastboot binaries installed on client machine
+* sunxi-tools installed on client machine (optional)
+* u-boot tools (mkimage)
+* u-boot binaries for the target sunxi device
+* filesystem images
+  * root file system containing operating system
+  * vfat file system 
+* Sunxi device connected to client via OTG port
+
+Getting your device into Fastboot mode
+--------------------------------------
+
+To enter into fastboot mode, execute the `fastboot` command in
+U-Boot:
+
+$ fastboot usb 0
+
+On the client machine, you can check whether the device is visible
+using the `fastboot devices` command. And for fun, you can also
+fetch the bootloader version using the fastboot protocol:
+
+$ fastboot devices 
+1234567890abcdef	fastboot
+$ fastboot getvar bootloader-version
+bootloader-version: U-Boot 2018.11-rc2-00033-ge3beca3a2f
+finished. total time: 0.000s
+
+Preparing the device for flashing
+---------------------------------
+
+Now that the device is in the fastboot mode, we can continue with
+creating the partitions on the device. By default, u-boot for sunxi
+defines following partitions:
+
+* loader1 - partition for secondary program loader
+* loader2 - partition for u-boot
+* esp     - EFI system partition, also used for u-boot to look up boot.scr
+* system  - Root partition for system
+
+These partitions have also assigned GUID's according to Discoverable
+Partitions Specification [1], to enable automatic discovery of partitions
+and their mountpoints.
+
+You can start by formatting the internal storage by executing the
+`fastboot oem format` command from client:
+
+$ fastboot oem format
+
+This equivalent to running the `gpt write mmc 1 $partitions` from u-boot.
+
+[1] https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/
+
+Flashing the device
+-------------------
+
+Now that we have the partitions created, all that is left for us
+is to flash the data.
+
+`loader1` is used for storing the Seconday Program Loader, in our
+case, it is the `spl/sunxi-spl.bin` in the u-boot directory:
+
+$ fastboot flash loader1 spl/sunxi-spl.bin
+
+`loader2` is for storing the u-boot binary. `u-boot.img` in the
+u-boot source directory:
+
+$ fastboot flash loader2 u-boot.img
+
+`esp` partition (EFI System Partition) can be kept empty, although
+if it is VFAT partition, u-boot automatically looks up the `boot.scr`
+file for device-specific configuration. (You can create empty vfat
+partition by `fallocate -l 32M esp.img && mkfs.vfat esp.img`)
+
+$ fastboot flash esp esp.img
+
+`system` partition is where the operating system resides. Creating
+that is left as an exercise to the reader.
+
+$ fastboot flash system system.img
+
+Now, if everything has been properly set up (aka proper kernel
+with machine-specific dtb installed on system.img, and boot.scr
+on esp partition), you can reboot the machine:
+
+$ fastboot reboot
-- 
git-series 0.9.1