Hi Eugeniu,
On Thu, May 23, 2019 at 6:33 PM Eugeniu Rosca erosca@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@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 feedduring '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