[PATCH] doc: android: Convert to Sphinx format

Sam Protsenko joe.skb7 at gmail.com
Tue Jan 14 20:43:21 CET 2020


Hi Heinrich,

Forgot to mention, this patch is intended to be applied on top of this series:

    https://patchwork.ozlabs.org/cover/1215282/

That's why you see that warning. Once the series is merged, the build
log will be clean.

Thanks for testing!

On Tue, Jan 14, 2020 at 8:34 PM Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> On 1/14/20 6:50 PM, Sam Protsenko wrote:
> > 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 at gmail.com>
> > ---
> >   MAINTAINERS                                   |   4 +-
> >   cmd/Kconfig                                   |   2 +-
> >   doc/android/{ab.txt => ab.rst}                |  39 ++---
> >   doc/android/avb2.rst                          | 133 ++++++++++++++++++
> >   doc/android/avb2.txt                          | 115 ---------------
> >   doc/android/bcb.rst                           | 100 +++++++++++++
> >   doc/android/bcb.txt                           |  89 ------------
> >   ...oot-protocol.txt => fastboot-protocol.rst} |  45 +++---
> >   doc/android/{fastboot.txt => fastboot.rst}    |  92 ++++++------
> >   doc/android/index.rst                         |  14 ++
> >   doc/index.rst                                 |  12 ++
> >   test/py/tests/test_android/test_avb.py        |   2 +-
> >   12 files changed, 351 insertions(+), 296 deletions(-)
> >   rename doc/android/{ab.txt => ab.rst} (52%)
> >   create mode 100644 doc/android/avb2.rst
> >   delete mode 100644 doc/android/avb2.txt
> >   create mode 100644 doc/android/bcb.rst
> >   delete mode 100644 doc/android/bcb.txt
> >   rename doc/android/{fastboot-protocol.txt => fastboot-protocol.rst} (82%)
> >   rename doc/android/{fastboot.txt => fastboot.rst} (79%)
> >   create mode 100644 doc/android/index.rst
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 438fb225ab..b9e7cd9944 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -56,7 +56,7 @@ R:  Sam Protsenko <semen.protsenko at linaro.org>
> >   S:  Maintained
> >   F:  cmd/ab_select.c
> >   F:  common/android_ab.c
> > -F:   doc/android/ab.txt
> > +F:   doc/android/ab.rst
> >   F:  include/android_ab.h
> >   F:  test/py/tests/test_android/test_ab.py
> >
> > @@ -65,7 +65,7 @@ M:  Igor Opaniuk <igor.opaniuk at gmail.com>
> >   S:  Maintained
> >   F:  cmd/avb.c
> >   F:  common/avb_verify.c
> > -F:   doc/android/avb2.txt
> > +F:   doc/android/avb2.rst
> >   F:  include/avb_verify.h
> >   F:  lib/libavb/
> >   F:  test/py/tests/test_android/test_avb.py
> > diff --git a/cmd/Kconfig b/cmd/Kconfig
> > index 98d944fb0a..6833185805 100644
> > --- a/cmd/Kconfig
> > +++ b/cmd/Kconfig
> > @@ -866,7 +866,7 @@ config CMD_FASTBOOT
> >         Android devices. Fastboot requires either the network stack
> >         enabled or support for acting as a USB device.
> >
> > -       See doc/android/fastboot.txt for more information.
> > +       See doc/android/fastboot.rst for more information.
> >
> >   config CMD_FDC
> >       bool "fdcboot - Boot from floppy device"
> > diff --git a/doc/android/ab.txt b/doc/android/ab.rst
> > similarity index 52%
> > rename from doc/android/ab.txt
> > rename to doc/android/ab.rst
> > index 9f37ed5c58..961895c32e 100644
> > --- a/doc/android/ab.txt
> > +++ b/doc/android/ab.rst
> > @@ -1,3 +1,5 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> >   Android A/B updates
> >   ===================
> >
> > @@ -7,41 +9,44 @@ Overview
> >   A/B system updates ensures modern approach for system update. This feature
> >   allows one to use two sets (or more) of partitions referred to as slots
> >   (normally slot A and slot B). The system runs from the current slot while the
> > -partitions in the unused slot can be updated [1].
> > +partitions in the unused slot can be updated [1]_.
> >
> >   A/B enablement
> >   --------------
> >
> >   The A/B updates support can be activated by specifying next options in
> > -your board configuration file:
> > +your board configuration file::
> >
> >       CONFIG_ANDROID_AB=y
> >       CONFIG_CMD_AB_SELECT=y
> >
> >   The disk space on target device must be partitioned in a way so that each
> >   partition which needs to be updated has two or more instances. The name of
> > -each instance must be formed by adding suffixes: _a, _b, _c, etc.
> > -For example: boot_a, boot_b, system_a, system_b, vendor_a, vendor_b.
> > +each instance must be formed by adding suffixes: ``_a``, ``_b``, ``_c``, etc.
> > +For example: ``boot_a``, ``boot_b``, ``system_a``, ``system_b``, ``vendor_a``,
> > +``vendor_b``.
> >
> > -As a result you can use 'ab_select' command to ensure A/B boot process in your
> > +As a result you can use ``ab_select`` command to ensure A/B boot process in your
> >   boot script. This command analyzes and processes A/B metadata stored on a
> > -special partition (e.g. "misc") and determines which slot should be used for
> > +special partition (e.g. ``misc``) and determines which slot should be used for
> >   booting up.
> >
> >   Command usage
> >   -------------
> >
> > +.. code-block:: none
> > +
> >       ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]>
> >
> > -for example:
> > +for example::
> >
> >       => ab_select slot_name mmc 1:4
> >
> > -or
> > +or::
> >
> >       => ab_select slot_name mmc 1#misc
> >
> > -Result:
> > +Result::
> >
> >       => printenv slot_name
> >       slot_name=a
> > @@ -49,19 +54,19 @@ Result:
> >   Based on this slot information, the current boot partition should be defined,
> >   and next kernel command line parameters should be generated:
> >
> > - - androidboot.slot_suffix=
> > - - root=
> > +* ``androidboot.slot_suffix=``
> > +* ``root=``
> >
> > -For example:
> > +For example::
> >
> >       androidboot.slot_suffix=_a root=/dev/mmcblk1p12
> >
> > -A/B metadata is organized according to AOSP reference [2]. On the first system
> > -start with A/B enabled, when 'misc' partition doesn't contain required data,
> > -the default A/B metadata will be created and written to 'misc' partition.
> > +A/B metadata is organized according to AOSP reference [2]_. On the first system
> > +start with A/B enabled, when ``misc`` partition doesn't contain required data,
> > +the default A/B metadata will be created and written to ``misc`` partition.
> >
> >   References
> >   ----------
> >
> > -[1] https://source.android.com/devices/tech/ota/ab
> > -[2] bootable/recovery/bootloader_message/include/bootloader_message/bootloader_message.h
> > +.. [1] https://source.android.com/devices/tech/ota/ab
> > +.. [2] https://android.googlesource.com/platform/bootable/recovery/+/refs/tags/android-10.0.0_r25/bootloader_message/include/bootloader_message/bootloader_message.h
> > diff --git a/doc/android/avb2.rst b/doc/android/avb2.rst
> > new file mode 100644
> > index 0000000000..a072119574
> > --- /dev/null
> > +++ b/doc/android/avb2.rst
> > @@ -0,0 +1,133 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +Android Verified Boot 2.0
> > +=========================
> > +
> > +This file contains information about the current support of Android Verified
> > +Boot 2.0 in U-Boot.
> > +
> > +Overview
> > +--------
> > +
> > +Verified Boot establishes a chain of trust from the bootloader to system images:
> > +
> > +* Provides integrity checking for:
> > +
> > +  * Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
> > +    partition is done and the hash is compared with the one stored in
> > +    the VBMeta image
> > +  * ``system``/``vendor`` partitions: verifying root hash of dm-verity hashtrees
> > +
> > +* Provides capabilities for rollback protection
> > +
> > +Integrity of the bootloader (U-Boot BLOB and environment) is out of scope.
> > +
> > +For additional details check [1]_.
> > +
> > +AVB using OP-TEE (optional)
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback
> > +indexes and device lock state are stored in RPMB. The RPMB partition is managed
> > +by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM
> > +TrustZone.
> > +
> > +AVB 2.0 U-Boot shell commands
> > +-----------------------------
> > +
> > +Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
> > +different testing purposes::
> > +
> > +    avb init <dev> - initialize avb 2.0 for <dev>
> > +    avb verify - run verification process using hash data from vbmeta structure
> > +    avb read_rb <num> - read rollback index at location <num>
> > +    avb write_rb <num> <rb> - write rollback index <rb> to <num>
> > +    avb is_unlocked - returns unlock status of the device
> > +    avb get_uuid <partname> - read and print uuid of partition <partname>
> > +    avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
> > +    partition <partname> to buffer <addr>
> > +    avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
> > +    <partname> by <offset> using data from <addr>
> > +
> > +Partitions tampering (example)
> > +------------------------------
> > +
> > +Boot or system/vendor (dm-verity metadata section) is tampered::
> > +
> > +   => avb init 1
> > +   => avb verify
> > +   avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
> > +   descriptor.
> > +   Slot verification result: ERROR_IO
> > +
> > +Vbmeta partition is tampered::
> > +
> > +   => avb init 1
> > +   => avb verify
> > +   avb_vbmeta_image.c:206: ERROR: Hash does not match!
> > +   avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
> > +   HASH_MISMATCH
> > +   Slot verification result: ERROR_IO
> > +
> > +Enable on your board
> > +--------------------
> > +
> > +The following options must be enabled::
> > +
> > +   CONFIG_LIBAVB=y
> > +   CONFIG_AVB_VERIFY=y
> > +   CONFIG_CMD_AVB=y
> > +
> > +In addtion optionally if storing rollback indexes in RPMB with help of
> > +OP-TEE::
> > +
> > +   CONFIG_TEE=y
> > +   CONFIG_OPTEE=y
> > +   CONFIG_OPTEE_TA_AVB=y
> > +   CONFIG_SUPPORT_EMMC_RPMB=y
> > +
> > +Then add ``avb verify`` invocation to your android boot sequence of commands,
> > +e.g.::
> > +
> > +   => avb_verify=avb init $mmcdev; avb verify;
> > +   => if run avb_verify; then                       \
> > +           echo AVB verification OK. Continue boot; \
> > +           set bootargs $bootargs $avb_bootargs;    \
> > +      else                                          \
> > +           echo AVB verification failed;            \
> > +           exit;                                    \
> > +      fi;                                           \
> > +
> > +   => emmc_android_boot=                                   \
> > +          echo Trying to boot Android from eMMC ...;       \
> > +          ...                                              \
> > +          run avb_verify;                                  \
> > +          mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
> > +          mmc read ${loadaddr} ${boot_start} ${boot_size}; \
> > +               bootm $loadaddr $loadaddr $fdtaddr;         \
> > +
> > +If partitions you want to verify are slotted (have A/B suffixes), then current
> > +slot suffix should be passed to ``avb verify`` sub-command, e.g.::
> > +
> > +   => avb verify _a
> > +
> > +To switch on automatic generation of vbmeta partition in AOSP build, add these
> > +lines to device configuration mk file::
> > +
> > +   BOARD_AVB_ENABLE := true
> > +   BOARD_AVB_ALGORITHM := SHA512_RSA4096
> > +   BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
> > +
> > +After flashing U-Boot don't forget to update environment and write new
> > +partition table::
> > +
> > +   => env default -f -a
> > +   => setenv partitions $partitions_android
> > +   => env save
> > +   => gpt write mmc 1 $partitions_android
> > +
> > +References
> > +----------
> > +
> > +.. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md
> > +.. [2] https://www.op-tee.org/
> > diff --git a/doc/android/avb2.txt b/doc/android/avb2.txt
> > deleted file mode 100644
> > index 48e9297c75..0000000000
> > --- a/doc/android/avb2.txt
> > +++ /dev/null
> > @@ -1,115 +0,0 @@
> > -Android Verified Boot 2.0
> > -
> > -This file contains information about the current support of Android Verified
> > -Boot 2.0 in U-boot
> > -
> > -1. OVERVIEW
> > ----------------------------------
> > -Verified Boot establishes a chain of trust from the bootloader to system images
> > -* Provides integrity checking for:
> > -  - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
> > -    partition is done and the hash is compared with the one stored in
> > -    the VBMeta image
> > -  - system/vendor partitions: verifying root hash of dm-verity hashtrees.
> > -* Provides capabilities for rollback protection.
> > -
> > -Integrity of the bootloader (U-boot BLOB and environment) is out of scope.
> > -
> > -For additional details check:
> > -https://android.googlesource.com/platform/external/avb/+/master/README.md
> > -
> > -1.1. AVB using OP-TEE (optional)
> > ----------------------------------
> > -If AVB is configured to use OP-TEE (see 4. below) rollback indexes and
> > -device lock state are stored in RPMB. The RPMB partition is managed by
> > -OP-TEE (https://www.op-tee.org/) which is a secure OS leveraging ARM
> > -TrustZone.
> > -
> > -
> > -2. AVB 2.0 U-BOOT SHELL COMMANDS
> > ------------------------------------
> > -Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
> > -different testing purposes:
> > -
> > -avb init <dev> - initialize avb 2.0 for <dev>
> > -avb verify - run verification process using hash data from vbmeta structure
> > -avb read_rb <num> - read rollback index at location <num>
> > -avb write_rb <num> <rb> - write rollback index <rb> to <num>
> > -avb is_unlocked - returns unlock status of the device
> > -avb get_uuid <partname> - read and print uuid of partition <partname>
> > -avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
> > -partition <partname> to buffer <addr>
> > -avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
> > -<partname> by <offset> using data from <addr>
> > -
> > -
> > -3. PARTITIONS TAMPERING (EXAMPLE)
> > ------------------------------------
> > -Boot or system/vendor (dm-verity metadata section) is tampered:
> > -=> avb init 1
> > -=> avb verify
> > -avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
> > -descriptor.
> > -Slot verification result: ERROR_IO
> > -
> > -Vbmeta partition is tampered:
> > -=> avb init 1
> > -=> avb verify
> > -avb_vbmeta_image.c:206: ERROR: Hash does not match!
> > -avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
> > -HASH_MISMATCH
> > -Slot verification result: ERROR_IO
> > -
> > -
> > -4. ENABLE ON YOUR BOARD
> > ------------------------------------
> > -The following options must be enabled:
> > -CONFIG_LIBAVB=y
> > -CONFIG_AVB_VERIFY=y
> > -CONFIG_CMD_AVB=y
> > -
> > -In addtion optionally if storing rollback indexes in RPMB with help of
> > -OP-TEE:
> > -CONFIG_TEE=y
> > -CONFIG_OPTEE=y
> > -CONFIG_OPTEE_TA_AVB=y
> > -CONFIG_SUPPORT_EMMC_RPMB=y
> > -
> > -Then add `avb verify` invocation to your android boot sequence of commands,
> > -e.g.:
> > -
> > -=> avb_verify=avb init $mmcdev; avb verify;
> > -=> if run avb_verify; then                       \
> > -        echo AVB verification OK. Continue boot; \
> > -        set bootargs $bootargs $avb_bootargs;    \
> > -   else                                          \
> > -        echo AVB verification failed;            \
> > -        exit;                                    \
> > -   fi;                                           \
> > -
> > -=> emmc_android_boot=                                   \
> > -       echo Trying to boot Android from eMMC ...;       \
> > -       ...                                              \
> > -       run avb_verify;                                  \
> > -       mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
> > -       mmc read ${loadaddr} ${boot_start} ${boot_size}; \
> > -       bootm $loadaddr $loadaddr $fdtaddr;              \
> > -
> > -If partitions you want to verify are slotted (have A/B suffixes), then current
> > -slot suffix should be passed to 'avb verify' sub-command, e.g.:
> > -
> > -=> avb verify _a
> > -
> > -To switch on automatic generation of vbmeta partition in AOSP build, add these
> > -lines to device configuration mk file:
> > -
> > -BOARD_AVB_ENABLE := true
> > -BOARD_AVB_ALGORITHM := SHA512_RSA4096
> > -BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
> > -
> > -After flashing U-boot don't forget to update environment and write new
> > -partition table:
> > -=> env default -f -a
> > -=> setenv partitions $partitions_android
> > -=> env save
> > -=> gpt write mmc 1 $partitions_android
> > diff --git a/doc/android/bcb.rst b/doc/android/bcb.rst
> > new file mode 100644
> > index 0000000000..8861608300
> > --- /dev/null
> > +++ b/doc/android/bcb.rst
> > @@ -0,0 +1,100 @@
> > +.. 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
> > diff --git a/doc/android/bcb.txt b/doc/android/bcb.txt
> > deleted file mode 100644
> > index 7b7177cacf..0000000000
> > --- a/doc/android/bcb.txt
> > +++ /dev/null
> > @@ -1,89 +0,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!
> > -
> > -
> > -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/android/fastboot-protocol.txt b/doc/android/fastboot-protocol.rst
> > similarity index 82%
> > rename from doc/android/fastboot-protocol.txt
> > rename to doc/android/fastboot-protocol.rst
> > index e9e7166a26..e723659e49 100644
> > --- a/doc/android/fastboot-protocol.txt
> > +++ b/doc/android/fastboot-protocol.rst
> > @@ -1,12 +1,13 @@
> > -FastBoot  Version  0.4
> > -----------------------
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +FastBoot Version 0.4
> > +====================
> >
> >   The fastboot protocol is a mechanism for communicating with bootloaders
> >   over USB.  It is designed to be very straightforward to implement, to
> >   allow it to be used across a wide range of devices and from hosts running
> >   Linux, Windows, or OSX.
> >
> > -
> >   Basic Requirements
> >   ------------------
> >
> > @@ -66,31 +67,33 @@ Transport and Framing
> >   Example Session
> >   ---------------
> >
> > -Host:    "getvar:version"        request version variable
> > +.. code-block:: none
> > +
> > +    Host:    "getvar:version"        request version variable
> >
> > -Client:  "OKAY0.4"               return version "0.4"
> > +    Client:  "OKAY0.4"               return version "0.4"
> >
> > -Host:    "getvar:nonexistant"    request some undefined variable
> > +    Host:    "getvar:nonexistant"    request some undefined variable
> >
> > -Client:  "OKAY"                  return value ""
> > +    Client:  "OKAY"                  return value ""
> >
> > -Host:    "download:00001234"     request to send 0x1234 bytes of data
> > +    Host:    "download:00001234"     request to send 0x1234 bytes of data
> >
> > -Client:  "DATA00001234"          ready to accept data
> > +    Client:  "DATA00001234"          ready to accept data
> >
> > -Host:    < 0x1234 bytes >        send data
> > +    Host:    < 0x1234 bytes >        send data
> >
> > -Client:  "OKAY"                  success
> > +    Client:  "OKAY"                  success
> >
> > -Host:    "flash:bootloader"      request to flash the data to the bootloader
> > +    Host:    "flash:bootloader"      request to flash the data to the bootloader
> >
> > -Client:  "INFOerasing flash"     indicate status / progress
> > -         "INFOwriting flash"
> > -         "OKAY"                  indicate success
> > +    Client:  "INFOerasing flash"     indicate status / progress
> > +             "INFOwriting flash"
> > +             "OKAY"                  indicate success
> >
> > -Host:    "powerdown"             send a command
> > +    Host:    "powerdown"             send a command
> >
> > -Client:  "FAILunknown command"   indicate failure
> > +    Client:  "FAILunknown command"   indicate failure
> >
> >
> >   Command Reference
> > @@ -105,6 +108,8 @@ Command Reference
> >     specification.  OEM-specific commands should not begin with a
> >     lowercase letter, to prevent incompatibilities with future specs.
> >
> > +.. code-block:: none
> > +
> >    "getvar:%s"           Read a config/version variable from the bootloader.
> >                          The variable contents will be returned after the
> >                          OKAY response.
> > @@ -139,16 +144,14 @@ Command Reference
> >
> >     "powerdown"          Power off the device.
> >
> > -
> > -
> >   Client Variables
> >   ----------------
> >
> > -The "getvar:%s" command is used to read client variables which
> > +The ``getvar:%s`` command is used to read client variables which
> >   represent various information about the device and the software
> >   on it.
> >
> > -The various currently defined names are:
> > +The various currently defined names are::
> >
> >     version             Version of FastBoot protocol supported.
> >                         It should be "0.3" for this document.
> > diff --git a/doc/android/fastboot.txt b/doc/android/fastboot.rst
> > similarity index 79%
> > rename from doc/android/fastboot.txt
> > rename to doc/android/fastboot.rst
> > index 9de13223f8..de3f6c37d7 100644
> > --- a/doc/android/fastboot.txt
> > +++ b/doc/android/fastboot.rst
> > @@ -1,12 +1,12 @@
> > -================
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> >   Android Fastboot
> >   ================
> >
> >   Overview
> > -========
> > +--------
> >
> > -The protocol that is used over USB and UDP is described in
> > -``doc/android/fastboot-protocol.txt``.
> > +The protocol that is used over USB and UDP is described in [1]_.
> >
> >   The current implementation supports the following standard commands:
> >
> > @@ -22,25 +22,23 @@ The current implementation supports the following standard commands:
> >
> >   The following OEM commands are supported (if enabled):
> >
> > -- oem format - this executes ``gpt write mmc %x $partitions``
> > +- ``oem format`` - this executes ``gpt write mmc %x $partitions``
> >
> >   Support for both eMMC and NAND devices is included.
> >
> >   Client installation
> > -===================
> > +-------------------
> >
> >   The counterpart to this is the fastboot client which can be found in
> >   Android's ``platform/system/core`` repository in the fastboot
> >   folder. It runs on Windows, Linux and OSX. The fastboot client is
> > -part of the Android SDK Platform-Tools and can be downloaded from:
> > -
> > -https://developer.android.com/studio/releases/platform-tools
> > +part of the Android SDK Platform-Tools and can be downloaded from [2]_.
> >
> >   Board specific
> > -==============
> > +--------------
> >
> >   USB configuration
> > ------------------
> > +^^^^^^^^^^^^^^^^^
> >
> >   The fastboot gadget relies on the USB download gadget, so the following
> >   options must be configured:
> > @@ -57,7 +55,7 @@ supported by the fastboot client. The list of vendor IDs supported can
> >   be found in the fastboot client source code.
> >
> >   General configuration
> > ----------------------
> > +^^^^^^^^^^^^^^^^^^^^^
> >
> >   The fastboot protocol requires a large memory buffer for
> >   downloads. This buffer should be as large as possible for a
> > @@ -67,46 +65,46 @@ may be overridden on the fastboot command line using ``-l`` and
> >   ``-s``.
> >
> >   Fastboot environment variables
> > -==============================
> > +------------------------------
> >
> >   Partition aliases
> > ------------------
> > +^^^^^^^^^^^^^^^^^
> >
> >   Fastboot partition aliases can also be defined for devices where GPT
> > -limitations prevent user-friendly partition names such as "boot", "system"
> > -and "cache".  Or, where the actual partition name doesn't match a standard
> > +limitations prevent user-friendly partition names such as ``boot``, ``system``
> > +and ``cache``.  Or, where the actual partition name doesn't match a standard
> >   partition name used commonly with fastboot.
> >
> >   The current implementation checks aliases when accessing partitions by
> >   name (flash_write and erase functions).  To define a partition alias
> > -add an environment variable similar to:
> > +add an environment variable similar to::
> >
> > -``fastboot_partition_alias_<alias partition name>=<actual partition name>``
> > +    fastboot_partition_alias_<alias partition name>=<actual partition name>
> >
> > -for example:
> > +for example::
> >
> > -``fastboot_partition_alias_boot=LNX``
> > +    fastboot_partition_alias_boot=LNX
> >
> >   Variable overrides
> > -------------------
> > +^^^^^^^^^^^^^^^^^^
> >
> >   Variables retrived through ``getvar`` can be overridden by defining
> >   environment variables of the form ``fastboot.<variable>``. These are
> >   looked up first so can be used to override values which would
> >   otherwise be returned. Using this mechanism you can also return types
> >   for NAND filesystems, as the fully parameterised variable is looked
> > -up, e.g.
> > +up, e.g.::
> >
> > -``fastboot.partition-type:boot=jffs2``
> > +    fastboot.partition-type:boot=jffs2
> >
> >   Boot command
> > -------------
> > +^^^^^^^^^^^^
> >
> > -When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then
> > -that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
> > +When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set
> > +then that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
> >
> >   Partition Names
> > -===============
> > +---------------
> >
> >   The Fastboot implementation in U-Boot allows to write images into disk
> >   partitions. Target partitions are referred on the host computer by
> > @@ -115,11 +113,11 @@ their names.
> >   For GPT/EFI the respective partition name is used.
> >
> >   For MBR the partitions are referred by generic names according to the
> > -following schema:
> > +following schema::
> >
> > -  <device type><device index letter><partition index>
> > +    <device type><device index letter><partition index>
> >
> > -Example: ``hda3``, ``sdb1``, ``usbda1``
> > +Example: ``hda3``, ``sdb1``, ``usbda1``.
> >
> >   The device type is as follows:
> >
> > @@ -135,7 +133,7 @@ controller, SD/MMC controller) or disk index. The partition index starts
> >   from ``1`` and describes the partition number on the particular device.
> >
> >   Writing Partition Table
> > -=======================
> > +-----------------------
> >
> >   Fastboot also allows to write the partition table to the media. This can be
> >   done by writing the respective partition table image to a special target
> > @@ -148,34 +146,26 @@ configuration options:
> >      CONFIG_FASTBOOT_MBR_NAME
> >
> >   In Action
> > -=========
> > +---------
> >
> > -Enter into fastboot by executing the fastboot command in U-Boot for either USB:
> > -
> > -::
> > +Enter into fastboot by executing the fastboot command in U-Boot for either USB::
> >
> >      => fastboot usb 0
> >
> > -or UDP:
> > -
> > -::
> > +or UDP::
> >
> >      => fastboot udp
> >      link up on port 0, speed 100, full duplex
> >      Using ethernet at 4a100000 device
> >      Listening for fastboot command on 192.168.0.102
> >
> > -On the client side you can fetch the bootloader version for instance:
> > -
> > -::
> > +On the client side you can fetch the bootloader version for instance::
> >
> >      $ fastboot getvar version-bootloader
> >      version-bootloader: U-Boot 2019.07-rc4-00240-g00c9f2a2ec
> >      Finished. Total time: 0.005s
> >
> > -or initiate a reboot:
> > -
> > -::
> > +or initiate a reboot::
> >
> >      $ fastboot reboot
> >
> > @@ -184,9 +174,7 @@ and once the client comes back, the board should reset.
> >   You can also specify a kernel image to boot. You have to either specify
> >   the an image in Android format *or* pass a binary kernel and let the
> >   fastboot client wrap the Android suite around it. On OMAP for instance you
> > -take zImage kernel and pass it to the fastboot client:
> > -
> > -::
> > +take zImage kernel and pass it to the fastboot client::
> >
> >      $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage
> >      creating boot image...
> > @@ -197,9 +185,7 @@ take zImage kernel and pass it to the fastboot client:
> >      OKAY [ -0.000s]
> >      finished. total time: 2.766s
> >
> > -and on the U-Boot side you should see:
> > -
> > -::
> > +and on the U-Boot side you should see::
> >
> >      Starting download of 1847296 bytes
> >      ........................................................
> > @@ -212,3 +198,9 @@ and on the U-Boot side you should see:
> >      OK
> >
> >      Starting kernel ...
> > +
> > +References
> > +----------
> > +
> > +.. [1] :doc:`fastboot-protocol`
> > +.. [2] https://developer.android.com/studio/releases/platform-tools
> > diff --git a/doc/android/index.rst b/doc/android/index.rst
> > new file mode 100644
> > index 0000000000..225d6f125a
> > --- /dev/null
> > +++ b/doc/android/index.rst
> > @@ -0,0 +1,14 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +Android-specific doc
> > +====================
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   ab
> > +   avb2
> > +   bcb
> > +   boot-image
>
> This produces a build warning for 'make htmldocs':
>
> doc/android/index.rst:6:
> WARNING: toctree contains reference to nonexisting document
> 'android/boot-image'
>
> No other errors are reported.
>
> Best regards
>
> Heinrich
>
>
> > +   fastboot-protocol
> > +   fastboot
> > diff --git a/doc/index.rst b/doc/index.rst
> > index 206a04590f..cd98be6cc5 100644
> > --- a/doc/index.rst
> > +++ b/doc/index.rst
> > @@ -86,6 +86,18 @@ organized in a vendor subdirectory.
> >
> >      board/index
> >
> > +Android-specific doc
> > +--------------------
> > +
> > +These books provide information about booting the Android OS from U-Boot,
> > +manipulating Android images from U-Boot shell and discusses other
> > +Android-specific features available in U-Boot.
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +
> > +   android/index
> > +
> >   Indices and tables
> >   ==================
> >
> > diff --git a/test/py/tests/test_android/test_avb.py b/test/py/tests/test_android/test_avb.py
> > index 20ccaf6712..a04a7ff264 100644
> > --- a/test/py/tests/test_android/test_avb.py
> > +++ b/test/py/tests/test_android/test_avb.py
> > @@ -8,7 +8,7 @@
> >   This tests Android Verified Boot 2.0 support in U-boot:
> >
> >   For additional details about how to build proper vbmeta partition
> > -check doc/android/avb2.txt
> > +check doc/android/avb2.rst
> >
> >   For configuration verification:
> >   - Corrupt boot partition and check for failure
> >
>


More information about the U-Boot mailing list