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