doc: relocate/rename Android README and add BCB overview

Rename:
 - doc/{README.avb2 => android/avb2.txt}
 - doc/{README.android-fastboot => android/fastboot.txt}

Add a new file documenting the 'bcb' command:
 - doc/android/bcb.txt

The new directory structure has been reviewed by Simon in
https://patchwork.ozlabs.org/patch/1101107/#2176031 .

Signed-off-by: Eugeniu Rosca <erosca@de.adit-jv.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

3 files changed, 414 insertions, 0 deletions

diff --git a/doc/android/avb2.txt b/doc/android/avb2.txt
new file mode 100644
index 00000000000..a29cee1b6f5
--- /dev/null
+++ b/doc/android/avb2.txt
@@ -0,0 +1,111 @@
+Android Verified Boot 2.0
+
+This file contains information about the current support of Android Verified
+Boot 2.0 in U-boot
+
+1. OVERVIEW
+---------------------------------
+Verified Boot establishes a chain of trust from the bootloader to system images
+* Provides integrity checking for:
+  - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
+    partition is done and the hash is compared with the one stored in
+    the VBMeta image
+  - system/vendor partitions: verifying root hash of dm-verity hashtrees.
+* Provides capabilities for rollback protection.
+
+Integrity of the bootloader (U-boot BLOB and environment) is out of scope.
+
+For additional details check:
+https://android.googlesource.com/platform/external/avb/+/master/README.md
+
+1.1. AVB using OP-TEE (optional)
+---------------------------------
+If AVB is configured to use OP-TEE (see 4. below) rollback indexes and
+device lock state are stored in RPMB. The RPMB partition is managed by
+OP-TEE (https://www.op-tee.org/) which is a secure OS leveraging ARM
+TrustZone.
+
+
+2. AVB 2.0 U-BOOT SHELL COMMANDS
+-----------------------------------
+Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
+different testing purposes:
+
+avb init <dev> - initialize avb 2.0 for <dev>
+avb verify - run verification process using hash data from vbmeta structure
+avb read_rb <num> - read rollback index at location <num>
+avb write_rb <num> <rb> - write rollback index <rb> to <num>
+avb is_unlocked - returns unlock status of the device
+avb get_uuid <partname> - read and print uuid of partition <partname>
+avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
+partition <partname> to buffer <addr>
+avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
+<partname> by <offset> using data from <addr>
+
+
+3. PARTITIONS TAMPERING (EXAMPLE)
+-----------------------------------
+Boot or system/vendor (dm-verity metadata section) is tampered:
+=> avb init 1
+=> avb verify
+avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
+descriptor.
+Slot verification result: ERROR_IO
+
+Vbmeta partition is tampered:
+=> avb init 1
+=> avb verify
+avb_vbmeta_image.c:206: ERROR: Hash does not match!
+avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
+HASH_MISMATCH
+Slot verification result: ERROR_IO
+
+
+4. ENABLE ON YOUR BOARD
+-----------------------------------
+The following options must be enabled:
+CONFIG_LIBAVB=y
+CONFIG_AVB_VERIFY=y
+CONFIG_CMD_AVB=y
+
+In addtion optionally if storing rollback indexes in RPMB with help of
+OP-TEE:
+CONFIG_TEE=y
+CONFIG_OPTEE=y
+CONFIG_OPTEE_TA_AVB=y
+CONFIG_SUPPORT_EMMC_RPMB=y
+
+Then add `avb verify` invocation to your android boot sequence of commands,
+e.g.:
+
+=> avb_verify=avb init $mmcdev; avb verify;
+=> if run avb_verify; then                       \
+        echo AVB verification OK. Continue boot; \
+        set bootargs $bootargs $avb_bootargs;    \
+   else                                          \
+        echo AVB verification failed;            \
+        exit;                                    \
+   fi;                                           \
+
+=> emmc_android_boot=                                   \
+       echo Trying to boot Android from eMMC ...;       \
+       ...                                              \
+       run avb_verify;                                  \
+       mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
+       mmc read ${loadaddr} ${boot_start} ${boot_size}; \
+       bootm $loadaddr $loadaddr $fdtaddr;              \
+
+
+To switch on automatic generation of vbmeta partition in AOSP build, add these
+lines to device configuration mk file:
+
+BOARD_AVB_ENABLE := true
+BOARD_AVB_ALGORITHM := SHA512_RSA4096
+BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
+
+After flashing U-boot don't forget to update environment and write new
+partition table:
+=> env default -f -a
+=> setenv partitions $partitions_android
+=> env save
+=> gpt write mmc 1 $partitions_android
diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt
new file mode 100644
index 00000000000..7b7177cacf2
--- /dev/null
+++ b/doc/android/bcb.txt
@@ -0,0 +1,89 @@
+Android Bootloader Control Block (BCB)
+
+The purpose behind this file is to:
+ - give an overview of BCB w/o duplicating public documentation
+ - describe the main BCB use-cases which concern U-Boot
+ - reflect current support status in U-Boot
+ - mention any relevant U-Boot build-time tunables
+ - precisely exemplify one or more use-cases
+
+Additions and fixes are welcome!
+
+
+1. OVERVIEW
+---------------------------------
+Bootloader Control Block (BCB) is a well established term/acronym in
+the Android namespace which refers to a location in a dedicated raw
+(i.e. FS-unaware) flash (e.g. eMMC) partition, usually called "misc",
+which is used as media for exchanging messages between Android userspace
+(particularly recovery [1]) and an Android-capable bootloader.
+
+On higher level, BCB provides a way to implement a subset of Android
+Bootloader Requirements [2], amongst which are:
+ - Android-specific bootloader flow [3]
+ - Get the "reboot reason" (and act accordingly) [4]
+ - Get/pass a list of commands from/to recovery [1]
+ - TODO
+
+
+2. 'BCB'. SHELL COMMAND OVERVIEW
+-----------------------------------
+The 'bcb' command provides a CLI to facilitate the development of the
+requirements enumerated above. Below is the command's help message:
+
+=> bcb
+bcb - Load/set/clear/test/dump/store Android BCB fields
+
+Usage:
+bcb load  <dev> <part>       - load  BCB from mmc <dev>:<part>
+bcb set   <field> <val>      - set   BCB <field> to <val>
+bcb clear [<field>]          - clear BCB <field> or all fields
+bcb test  <field> <op> <val> - test  BCB <field> against <val>
+bcb dump  <field>            - dump  BCB <field>
+bcb store                    - store BCB back to mmc
+
+Legend:
+<dev>   - MMC device index containing the BCB partition
+<part>  - MMC partition index or name containing the BCB
+<field> - one of {command,status,recovery,stage,reserved}
+<op>    - the binary operator used in 'bcb test':
+          '=' returns true if <val> matches the string stored in <field>
+          '~' returns true if <val> matches a subset of <field>'s string
+<val>   - string/text provided as input to bcb {set,test}
+          NOTE: any ':' character in <val> will be replaced by line feed
+          during 'bcb set' and used as separator by upper layers
+
+
+3. 'BCB'. EXAMPLE OF GETTING REBOOT REASON
+-----------------------------------
+if bcb load 1 misc; then
+    # valid BCB found
+    if bcb test command = bootonce-bootloader; then
+        bcb clear command; bcb store;
+        # do the equivalent of AOSP ${fastbootcmd}
+        # i.e. call fastboot
+    else if bcb test command = boot-recovery; then
+        bcb clear command; bcb store;
+        # do the equivalent of AOSP ${recoverycmd}
+        # i.e. do anything required for booting into recovery
+    else
+        # boot Android OS normally
+    fi
+else
+    # corrupted/non-existent BCB
+    # report error or boot non-Android OS (platform-specific)
+fi
+
+
+4. ENABLE ON YOUR BOARD
+-----------------------------------
+The following Kconfig options must be enabled:
+CONFIG_PARTITIONS=y
+CONFIG_MMC=y
+CONFIG_BCB=y
+
+[1] https://android.googlesource.com/platform/bootable/recovery
+[2] https://source.android.com/devices/bootloader
+[3] https://patchwork.ozlabs.org/patch/746835/
+    ("[U-Boot,5/6] Initial support for the Android Bootloader flow")
+[4] https://source.android.com/devices/bootloader/boot-reason
diff --git a/doc/android/fastboot.txt b/doc/android/fastboot.txt
new file mode 100644
index 00000000000..431191c473f
--- /dev/null
+++ b/doc/android/fastboot.txt
@@ -0,0 +1,214 @@
+================
+Android Fastboot
+================
+
+Overview
+========
+
+The protocol that is used over USB and UDP is described in the
+``README.android-fastboot-protocol`` file in the same directory.
+
+The current implementation supports the following standard commands:
+
+- ``boot``
+- ``continue``
+- ``download``
+- ``erase`` (if enabled)
+- ``flash`` (if enabled)
+- ``getvar``
+- ``reboot``
+- ``reboot-bootloader``
+- ``set_active`` (only a stub implementation which always succeeds)
+
+The following OEM commands are supported (if enabled):
+
+- oem format - this executes ``gpt write mmc %x $partitions``
+
+Support for both eMMC and NAND devices is included.
+
+Client installation
+===================
+
+The counterpart to this is the fastboot client which can be found in
+Android's ``platform/system/core`` repository in the fastboot
+folder. It runs on Windows, Linux and OSX. The fastboot client is
+part of the Android SDK Platform-Tools and can be downloaded from:
+
+https://developer.android.com/studio/releases/platform-tools
+
+Board specific
+==============
+
+USB configuration
+-----------------
+
+The fastboot gadget relies on the USB download gadget, so the following
+options must be configured:
+
+::
+
+   CONFIG_USB_GADGET_DOWNLOAD
+   CONFIG_USB_GADGET_VENDOR_NUM
+   CONFIG_USB_GADGET_PRODUCT_NUM
+   CONFIG_USB_GADGET_MANUFACTURER
+
+NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers
+supported by the fastboot client. The list of vendor IDs supported can
+be found in the fastboot client source code.
+
+General configuration
+---------------------
+
+The fastboot protocol requires a large memory buffer for
+downloads. This buffer should be as large as possible for a
+platform. The location of the buffer and size are set with
+``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These
+may be overridden on the fastboot command line using ``-l`` and
+``-s``.
+
+Fastboot environment variables
+==============================
+
+Partition aliases
+-----------------
+
+Fastboot partition aliases can also be defined for devices where GPT
+limitations prevent user-friendly partition names such as "boot", "system"
+and "cache".  Or, where the actual partition name doesn't match a standard
+partition name used commonly with fastboot.
+
+The current implementation checks aliases when accessing partitions by
+name (flash_write and erase functions).  To define a partition alias
+add an environment variable similar to:
+
+``fastboot_partition_alias_<alias partition name>=<actual partition name>``
+
+for example:
+
+``fastboot_partition_alias_boot=LNX``
+
+Variable overrides
+------------------
+
+Variables retrived through ``getvar`` can be overridden by defining
+environment variables of the form ``fastboot.<variable>``. These are
+looked up first so can be used to override values which would
+otherwise be returned. Using this mechanism you can also return types
+for NAND filesystems, as the fully parameterised variable is looked
+up, e.g.
+
+``fastboot.partition-type:boot=jffs2``
+
+Boot command
+------------
+
+When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then
+that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
+
+Partition Names
+===============
+
+The Fastboot implementation in U-Boot allows to write images into disk
+partitions. Target partitions are referred on the host computer by
+their names.
+
+For GPT/EFI the respective partition name is used.
+
+For MBR the partitions are referred by generic names according to the
+following schema:
+
+  <device type><device index letter><partition index>
+
+Example: ``hda3``, ``sdb1``, ``usbda1``
+
+The device type is as follows:
+
+  * IDE, ATAPI and SATA disks: ``hd``
+  * SCSI disks: ``sd``
+  * USB media: ``usbd``
+  * MMC and SD cards: ``mmcsd``
+  * Disk on chip: ``docd``
+  * other: ``xx``
+
+The device index starts from ``a`` and refers to the interface (e.g. USB
+controller, SD/MMC controller) or disk index. The partition index starts
+from ``1`` and describes the partition number on the particular device.
+
+Writing Partition Table
+=======================
+
+Fastboot also allows to write the partition table to the media. This can be
+done by writing the respective partition table image to a special target
+"gpt" or "mbr". These names can be customized by defining the following
+configuration options:
+
+::
+
+   CONFIG_FASTBOOT_GPT_NAME
+   CONFIG_FASTBOOT_MBR_NAME
+
+In Action
+=========
+
+Enter into fastboot by executing the fastboot command in U-Boot for either USB:
+
+::
+
+   => fastboot usb 0
+
+or UDP:
+
+::
+
+   => fastboot udp
+   link up on port 0, speed 100, full duplex
+   Using ethernet@4a100000 device
+   Listening for fastboot command on 192.168.0.102
+
+On the client side you can fetch the bootloader version for instance:
+
+::
+
+   $ fastboot getvar bootloader-version
+   bootloader-version: U-Boot 2014.04-00005-gd24cabc
+   finished. total time: 0.000s
+
+or initiate a reboot:
+
+::
+
+   $ fastboot reboot
+
+and once the client comes back, the board should reset.
+
+You can also specify a kernel image to boot. You have to either specify
+the an image in Android format *or* pass a binary kernel and let the
+fastboot client wrap the Android suite around it. On OMAP for instance you
+take zImage kernel and pass it to the fastboot client:
+
+::
+
+   $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage
+   creating boot image...
+   creating boot image - 1847296 bytes
+   downloading 'boot.img'...
+   OKAY [  2.766s]
+   booting...
+   OKAY [ -0.000s]
+   finished. total time: 2.766s
+
+and on the U-Boot side you should see:
+
+::
+
+   Starting download of 1847296 bytes
+   ........................................................
+   downloading of 1847296 bytes finished
+   Booting kernel..
+   ## Booting Android Image at 0x81000000 ...
+   Kernel load addr 0x80008000 size 1801 KiB
+   Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
+      Loading Kernel Image ... OK
+   OK
+
+   Starting kernel ...