doc/android/bcb.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Android Bootloader Control Block (BCB)
   4 ======================================
   5
   6 The 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
  14 Additions and fixes are welcome!
  15
  16 Overview
  17 --------
  18
  19 Bootloader Control Block (BCB) is a well established term/acronym in
  20 the Android namespace which refers to a location in a dedicated raw
  21 (i.e. FS-unaware) flash (e.g. eMMC) partition, usually called ``misc``,
  22 which is used as media for exchanging messages between Android userspace
  23 (particularly recovery [1]_) and an Android-capable bootloader.
  24
  25 On higher level, BCB provides a way to implement a subset of Android
  26 Bootloader 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
  37 The ``bcb`` command provides a CLI to facilitate the development of the
  38 requirements 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  <dev> <part>       - load  BCB from mmc <dev>:<part>
  45    bcb set   <field> <val>      - set   BCB <field> to <val>
  46    bcb clear [<field>]          - clear BCB <field> or all fields
  47    bcb test  <field> <op> <val> - test  BCB <field> against <val>
  48    bcb dump  <field>            - dump  BCB <field>
  49    bcb store                    - store BCB back to mmc
  50
  51    Legend:
  52    <dev>   - MMC device index containing the BCB partition
  53    <part>  - MMC partition index or name containing the BCB
  54    <field> - one of {command,status,recovery,stage,reserved}
  55    <op>    - the binary operator used in 'bcb test':
  56              '=' returns true if <val> matches the string stored in <field>
  57              '~' returns true if <val> matches a subset of <field>'s string
  58    <val>   - string/text provided as input to bcb {set,test}
  59              NOTE: any ':' character in <val> will be replaced by line feed
  60              during 'bcb set' and used as separator by upper layers
  61
  62
  63 'bcb'. Example of getting reboot reason
  64 ---------------------------------------
  65
  66 .. code-block:: bash
  67
  68    if bcb load 1 misc; then
  69        # valid BCB found
  70        if bcb test command = bootonce-bootloader; then
  71            bcb clear command; bcb store;
  72            # do the equivalent of AOSP ${fastbootcmd}
  73            # i.e. call fastboot
  74        else if bcb test command = boot-recovery; then
  75            bcb clear command; bcb store;
  76            # do the equivalent of AOSP ${recoverycmd}
  77            # i.e. do anything required for booting into recovery
  78        else
  79            # boot Android OS normally
  80        fi
  81    else
  82        # corrupted/non-existent BCB
  83        # report error or boot non-Android OS (platform-specific)
  84    fi
  85
  86
  87 Enable on your board
  88 --------------------
  89
  90 The following Kconfig options must be enabled::
  91
  92    CONFIG_PARTITIONS=y
  93    CONFIG_MMC=y
  94    CONFIG_BCB=y
  95
  96 .. [1] https://android.googlesource.com/platform/bootable/recovery
  97 .. [2] https://source.android.com/devices/bootloader
  98 .. [3] https://patchwork.ozlabs.org/patch/746835/
  99        ("[U-Boot,5/6] Initial support for the Android Bootloader flow")
 100 .. [4] https://source.android.com/devices/bootloader/boot-reason