[U-Boot] [PATCH v3 3/3] doc: relocate/rename Android README and add BCB overview

[Sam Protsenko]

Hi Eugeniu,

On Thu, May 23, 2019 at 6:33 PM Eugeniu Rosca <erosca at de.adit-jv.com> wrote:
>
> Rename:
>  - doc/{README.avb2 => android/avb2.txt}
>  - doc/{README.android-fastboot => android/fastboot.txt}
>
> Add a new file documenting the 'bcb' command:
>  - doc/android/bcb.txt
>
> The new directory structure has been reviewed by Simon in
> https://patchwork.ozlabs.org/patch/1101107/#2176031 .
>
> Signed-off-by: Eugeniu Rosca <erosca at de.adit-jv.com>
> ---
> v3:
>  - Newly pushed.
> ---
>  doc/{README.avb2 => android/avb2.txt}         |  0
>  doc/android/bcb.txt                           | 89 +++++++++++++++++++
>  .../fastboot.txt}                             |  0
>  3 files changed, 89 insertions(+)
>  rename doc/{README.avb2 => android/avb2.txt} (100%)
>  create mode 100644 doc/android/bcb.txt
>  rename doc/{README.android-fastboot => android/fastboot.txt} (100%)
>

Sorry for the late review, but it seems like some links to renamed doc
weren't changed properly (easily found by grep). Can you please add
change [1] to this patch, so that we don't need to send it separately
later?

[1] https://pastebin.ubuntu.com/p/nSd5z8JFtr/

Thanks!

> diff --git a/doc/README.avb2 b/doc/android/avb2.txt
> similarity index 100%
> rename from doc/README.avb2
> rename to doc/android/avb2.txt
> diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt
> new file mode 100644
> index 000000000000..7b7177cacf21
> --- /dev/null
> +++ b/doc/android/bcb.txt
> @@ -0,0 +1,89 @@
> +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!
> +
> +
> +1. 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
> +
> +
> +2. '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
> +
> +
> +3. 'BCB'. EXAMPLE OF GETTING REBOOT REASON
> +-----------------------------------
> +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
> +
> +
> +4. 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
> diff --git a/doc/README.android-fastboot b/doc/android/fastboot.txt
> similarity index 100%
> rename from doc/README.android-fastboot
> rename to doc/android/fastboot.txt
> --
> 2.21.0
>