From 9bdf0e8fef8683f147bb11c61242dde67d1be291 Mon Sep 17 00:00:00 2001
From: Eugeniu Rosca <erosca@de.adit-jv.com>
Date: Thu, 23 May 2019 17:32:23 +0200
Subject: [PATCH] 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>
---
 doc/{README.avb2 => android/avb2.txt}         |  0
 doc/android/bcb.txt                           | 89 +++++++++++++++++++
 .../fastboot.txt}                             |  0
 3 files changed, 89 insertions(+)
 rename doc/{README.avb2 => android/avb2.txt} (100%)
 create mode 100644 doc/android/bcb.txt
 rename doc/{README.android-fastboot => android/fastboot.txt} (100%)

diff --git a/doc/README.avb2 b/doc/android/avb2.txt
similarity index 100%
rename from doc/README.avb2
rename to doc/android/avb2.txt
diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt
new file mode 100644
index 0000000000..7b7177cacf
--- /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/README.android-fastboot b/doc/android/fastboot.txt
similarity index 100%
rename from doc/README.android-fastboot
rename to doc/android/fastboot.txt
-- 
2.39.5