[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