From 9bdf0e8fef8683f147bb11c61242dde67d1be291 Mon Sep 17 00:00:00 2001 From: Eugeniu Rosca 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 Reviewed-by: Simon Glass --- 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 - load BCB from mmc : +bcb set - set BCB to +bcb clear [] - clear BCB or all fields +bcb test - test BCB against +bcb dump - dump BCB +bcb store - store BCB back to mmc + +Legend: + - MMC device index containing the BCB partition + - MMC partition index or name containing the BCB + - one of {command,status,recovery,stage,reserved} + - the binary operator used in 'bcb test': + '=' returns true if matches the string stored in + '~' returns true if matches a subset of 's string + - string/text provided as input to bcb {set,test} + NOTE: any ':' character in 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