summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEugeniu Rosca <erosca@de.adit-jv.com>2019-05-23 18:32:23 +0300
committerTom Rini <trini@konsulko.com>2019-07-11 21:11:19 +0300
commit9bdf0e8fef8683f147bb11c61242dde67d1be291 (patch)
tree0a4c6072e08dc363fa20dc4d5b153bea2ee65f2b
parentdb7b7a05b2671c63cd49955dee58157045c68f05 (diff)
downloadu-boot-9bdf0e8fef8683f147bb11c61242dde67d1be291.tar.xz
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>
-rw-r--r--doc/android/avb2.txt (renamed from doc/README.avb2)0
-rw-r--r--doc/android/bcb.txt89
-rw-r--r--doc/android/fastboot.txt (renamed from doc/README.android-fastboot)0
3 files changed, 89 insertions, 0 deletions
diff --git a/doc/README.avb2 b/doc/android/avb2.txt
index a29cee1b6f..a29cee1b6f 100644
--- a/doc/README.avb2
+++ b/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
index 431191c473..431191c473 100644
--- a/doc/README.android-fastboot
+++ b/doc/android/fastboot.txt