[U-Boot] [PATCH v4 4/4] doc: android: add BCB overview and usage

[Eugeniu Rosca]

Document the BCB concept and U-Boot command, touching below aspects:
 - 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

Signed-off-by: Eugeniu Rosca <erosca at de.adit-jv.com>
---
v4:
 - This is carved out from https://patchwork.ozlabs.org/patch/1104245/
   ("[v3,3/3] doc: relocate/rename Android README and add BCB overview")
   with no modifications.
---
 doc/android/bcb.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 doc/android/bcb.txt

diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt
new file mode 100644
index 000000000000..7b7177cacf21
--- /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
-- 
2.22.0