[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