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

[Priit Laes]

On Tue, Oct 23, 2018 at 08:20:32PM +0300, Priit Laes wrote:
> 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.

Now that I used this approach with clean devices, I discovered an issue
where after `oem format`, the fastboot does not recognize the partitions:

$ fastboot flash loader1 data/sunxi-spl.bin 
target reported max download size of 33554432 bytes
sending 'loader1' (24 KB)...
OKAY [  0.008s]
writing 'loader1'...
FAILED (remote: cannot find partition)

I had to run following in the u-boot shell:

=> mmc dev 1
switch to partitions #0, OK
mmc1(part 0) is current device
=> mmc part 
[..skipped the list of correct partition printout..]
=> fastboot usb 0
...

And then flashing from the host worked.

Any hints where to look to properly fix it?

> +
> +[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