| Message ID | 20190523153223.18185-4-erosca@de.adit-jv.com |
|---|---|
| State | Accepted |
| Delegated to: | Tom Rini |
| Headers | show |
| Series | Add 'bcb' command to read/modify/write Android BCB | expand |
Hi Eugeniu, On Thu, 23 May 2019 at 16:33, Eugeniu Rosca <erosca@de.adit-jv.com> wrote: > > Rename: > - doc/{README.avb2 => android/avb2.txt} This should be in a separate patch since it isn't related to adding the new docs, actually. > - 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%) Looks good. Reviewed-by: Simon Glass <sjg@chromium.org> Regards, Simon
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 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 >
Hi Sam, On Tue, Jul 02, 2019 at 09:11:45PM +0300, Sam Protsenko wrote: > Hi Eugeniu, [..] > 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/ Sure. I will update the series asap. Thanks for commenting!
Hi Simon, On Sat, Jun 22, 2019 at 08:09:51PM +0100, Simon Glass wrote: > On Thu, 23 May 2019 at 16:33, Eugeniu Rosca <erosca@de.adit-jv.com> wrote: > > > > Rename: > > - doc/{README.avb2 => android/avb2.txt} > > This should be in a separate patch since it isn't related to adding > the new docs, actually. I will incorporate the finding in the upcoming revision. Thanks for the review comments! [..] > Looks good. > > Reviewed-by: Simon Glass <sjg@chromium.org>
On Thu, May 23, 2019 at 05:32:23PM +0200, Eugeniu Rosca 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> > Reviewed-by: Simon Glass <sjg@chromium.org> Applied to u-boot/master, 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
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%)