u-boot/doc/android/bcb.rst
Sam Protsenko 586a1bf5b2 doc: android: Convert to Sphinx format
Convert Android documentation from regular txt format to Sphinx (RST).
Also add Android index.rst file and reference it in root index.rst, so
that Android documentation is visible.

Test:

    $ make htmldocs
    $ xdg-open doc/output/index.html

Signed-off-by: Sam Protsenko <joe.skb7@gmail.com>
Signed-off-by: Lokesh Vutla <lokeshvutla@ti.com>
2020-02-04 09:07:24 +05:30

100 lines
3.4 KiB
ReStructuredText

.. SPDX-License-Identifier: GPL-2.0+
Android Bootloader Control Block (BCB)
======================================
The purpose behind this file is to:
* give an overview of BCB w/o duplicating public documentation
* describe the main BCB use-cases which concern U-Boot
* reflect current support status in U-Boot
* mention any relevant U-Boot build-time tunables
* precisely exemplify one or more use-cases
Additions and fixes are welcome!
Overview
--------
Bootloader Control Block (BCB) is a well established term/acronym in
the Android namespace which refers to a location in a dedicated raw
(i.e. FS-unaware) flash (e.g. eMMC) partition, usually called ``misc``,
which is used as media for exchanging messages between Android userspace
(particularly recovery [1]_) and an Android-capable bootloader.
On higher level, BCB provides a way to implement a subset of Android
Bootloader Requirements [2]_, amongst which are:
* Android-specific bootloader flow [3]_
* Get the "reboot reason" (and act accordingly) [4]_
* Get/pass a list of commands from/to recovery [1]_
* TODO
'bcb'. Shell command overview
-----------------------------
The ``bcb`` command provides a CLI to facilitate the development of the
requirements enumerated above. Below is the command's help message::
=> bcb
bcb - Load/set/clear/test/dump/store Android BCB fields
Usage:
bcb load <dev> <part> - load BCB from mmc <dev>:<part>
bcb set <field> <val> - set BCB <field> to <val>
bcb clear [<field>] - clear BCB <field> or all fields
bcb test <field> <op> <val> - test BCB <field> against <val>
bcb dump <field> - dump BCB <field>
bcb store - store BCB back to mmc
Legend:
<dev> - MMC device index containing the BCB partition
<part> - MMC partition index or name containing the BCB
<field> - one of {command,status,recovery,stage,reserved}
<op> - the binary operator used in 'bcb test':
'=' returns true if <val> matches the string stored in <field>
'~' returns true if <val> matches a subset of <field>'s string
<val> - string/text provided as input to bcb {set,test}
NOTE: any ':' character in <val> will be replaced by line feed
during 'bcb set' and used as separator by upper layers
'bcb'. Example of getting reboot reason
---------------------------------------
.. code-block:: bash
if bcb load 1 misc; then
# valid BCB found
if bcb test command = bootonce-bootloader; then
bcb clear command; bcb store;
# do the equivalent of AOSP ${fastbootcmd}
# i.e. call fastboot
else if bcb test command = boot-recovery; then
bcb clear command; bcb store;
# do the equivalent of AOSP ${recoverycmd}
# i.e. do anything required for booting into recovery
else
# boot Android OS normally
fi
else
# corrupted/non-existent BCB
# report error or boot non-Android OS (platform-specific)
fi
Enable on your board
--------------------
The following Kconfig options must be enabled::
CONFIG_PARTITIONS=y
CONFIG_MMC=y
CONFIG_BCB=y
.. [1] https://android.googlesource.com/platform/bootable/recovery
.. [2] https://source.android.com/devices/bootloader
.. [3] https://patchwork.ozlabs.org/patch/746835/
("[U-Boot,5/6] Initial support for the Android Bootloader flow")
.. [4] https://source.android.com/devices/bootloader/boot-reason