1Android Bootloader Control Block (BCB) 2 3The purpose behind this file is to: 4 - give an overview of BCB w/o duplicating public documentation 5 - describe the main BCB use-cases which concern U-Boot 6 - reflect current support status in U-Boot 7 - mention any relevant U-Boot build-time tunables 8 - precisely exemplify one or more use-cases 9 10Additions and fixes are welcome! 11 12 131. OVERVIEW 14--------------------------------- 15Bootloader Control Block (BCB) is a well established term/acronym in 16the Android namespace which refers to a location in a dedicated raw 17(i.e. FS-unaware) flash (e.g. eMMC) partition, usually called "misc", 18which is used as media for exchanging messages between Android userspace 19(particularly recovery [1]) and an Android-capable bootloader. 20 21On higher level, BCB provides a way to implement a subset of Android 22Bootloader Requirements [2], amongst which are: 23 - Android-specific bootloader flow [3] 24 - Get the "reboot reason" (and act accordingly) [4] 25 - Get/pass a list of commands from/to recovery [1] 26 - TODO 27 28 292. 'BCB'. SHELL COMMAND OVERVIEW 30----------------------------------- 31The 'bcb' command provides a CLI to facilitate the development of the 32requirements enumerated above. Below is the command's help message: 33 34=> bcb 35bcb - Load/set/clear/test/dump/store Android BCB fields 36 37Usage: 38bcb load <dev> <part> - load BCB from mmc <dev>:<part> 39bcb set <field> <val> - set BCB <field> to <val> 40bcb clear [<field>] - clear BCB <field> or all fields 41bcb test <field> <op> <val> - test BCB <field> against <val> 42bcb dump <field> - dump BCB <field> 43bcb store - store BCB back to mmc 44 45Legend: 46<dev> - MMC device index containing the BCB partition 47<part> - MMC partition index or name containing the BCB 48<field> - one of {command,status,recovery,stage,reserved} 49<op> - the binary operator used in 'bcb test': 50 '=' returns true if <val> matches the string stored in <field> 51 '~' returns true if <val> matches a subset of <field>'s string 52<val> - string/text provided as input to bcb {set,test} 53 NOTE: any ':' character in <val> will be replaced by line feed 54 during 'bcb set' and used as separator by upper layers 55 56 573. 'BCB'. EXAMPLE OF GETTING REBOOT REASON 58----------------------------------- 59if bcb load 1 misc; then 60 # valid BCB found 61 if bcb test command = bootonce-bootloader; then 62 bcb clear command; bcb store; 63 # do the equivalent of AOSP ${fastbootcmd} 64 # i.e. call fastboot 65 else if bcb test command = boot-recovery; then 66 bcb clear command; bcb store; 67 # do the equivalent of AOSP ${recoverycmd} 68 # i.e. do anything required for booting into recovery 69 else 70 # boot Android OS normally 71 fi 72else 73 # corrupted/non-existent BCB 74 # report error or boot non-Android OS (platform-specific) 75fi 76 77 784. ENABLE ON YOUR BOARD 79----------------------------------- 80The following Kconfig options must be enabled: 81CONFIG_PARTITIONS=y 82CONFIG_MMC=y 83CONFIG_BCB=y 84 85[1] https://android.googlesource.com/platform/bootable/recovery 86[2] https://source.android.com/devices/bootloader 87[3] https://patchwork.ozlabs.org/patch/746835/ 88 ("[U-Boot,5/6] Initial support for the Android Bootloader flow") 89[4] https://source.android.com/devices/bootloader/boot-reason 90