| Eugeniu Rosca | 9bdf0e8 | 2019-05-23 17:32:23 +0200 | [diff] [blame] | 1 | Android Bootloader Control Block (BCB) |
| 2 | |
| 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 |
| 9 | |
| 10 | Additions and fixes are welcome! |
| 11 | |
| 12 | |
| 13 | 1. OVERVIEW |
| 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. |
| 20 | |
| 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] |
| 26 | - TODO |
| 27 | |
| 28 | |
| 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: |
| 33 | |
| 34 | => bcb |
| 35 | bcb - Load/set/clear/test/dump/store Android BCB fields |
| 36 | |
| 37 | Usage: |
| 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 |
| 44 | |
| 45 | Legend: |
| 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 | |
| 57 | 3. 'BCB'. EXAMPLE OF GETTING REBOOT REASON |
| 58 | ----------------------------------- |
| 59 | if 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 |
| 72 | else |
| 73 | # corrupted/non-existent BCB |
| 74 | # report error or boot non-Android OS (platform-specific) |
| 75 | fi |
| 76 | |
| 77 | |
| 78 | 4. ENABLE ON YOUR BOARD |
| 79 | ----------------------------------- |
| 80 | The following Kconfig options must be enabled: |
| 81 | CONFIG_PARTITIONS=y |
| 82 | CONFIG_MMC=y |
| 83 | CONFIG_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 |