doc/android/bcb.txt

   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