1 Android Bootloader Control Block (BCB)
3 The 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
10 Additions and fixes are welcome!
14 ---------------------------------
15 Bootloader Control Block (BCB) is a well established term/acronym in
16 the Android namespace which refers to a location in a dedicated raw
17 (i.e. FS-unaware) flash (e.g. eMMC) partition, usually called "misc",
18 which is used as media for exchanging messages between Android userspace
19 (particularly recovery [1]) and an Android-capable bootloader.
21 On higher level, BCB provides a way to implement a subset of Android
22 Bootloader 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]
29 2. 'BCB'. SHELL COMMAND OVERVIEW
30 -----------------------------------
31 The 'bcb' command provides a CLI to facilitate the development of the
32 requirements enumerated above. Below is the command's help message:
35 bcb - Load/set/clear/test/dump/store Android BCB fields
38 bcb load <dev> <part> - load BCB from mmc <dev>:<part>
39 bcb set <field> <val> - set BCB <field> to <val>
40 bcb clear [<field>] - clear BCB <field> or all fields
41 bcb test <field> <op> <val> - test BCB <field> against <val>
42 bcb dump <field> - dump BCB <field>
43 bcb store - store BCB back to mmc
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
57 3. 'BCB'. EXAMPLE OF GETTING REBOOT REASON
58 -----------------------------------
59 if bcb load 1 misc; then
61 if bcb test command = bootonce-bootloader; then
62 bcb clear command; bcb store;
63 # do the equivalent of AOSP ${fastbootcmd}
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
70 # boot Android OS normally
73 # corrupted/non-existent BCB
74 # report error or boot non-Android OS (platform-specific)
78 4. ENABLE ON YOUR BOARD
79 -----------------------------------
80 The following Kconfig options must be enabled:
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