[PATCH] doc: android: Convert to Sphinx format

Heinrich Schuchardt xypron.glpk at gmx.de
Tue Jan 14 19:34:34 CET 2020


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