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@gmail.com>
Signed-off-by: Lokesh Vutla <lokeshvutla@ti.com>
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
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
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_FLASH
bool "flinfo, erase, protect"
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Android A/B updates
+===================
+
+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]_.
+
+A/B enablement
+--------------
+
+The A/B updates support can be activated by specifying next options in
+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``.
+
+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
+booting up.
+
+Command usage
+-------------
+
+.. code-block:: none
+
+ ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]>
+
+for example::
+
+ => ab_select slot_name mmc 1:4
+
+or::
+
+ => ab_select slot_name mmc 1#misc
+
+Result::
+
+ => printenv slot_name
+ slot_name=a
+
+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=``
+
+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.
+
+References
+----------
+
+.. [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
+++ /dev/null
-Android A/B updates
-===================
-
-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].
-
-A/B enablement
---------------
-
-The A/B updates support can be activated by specifying next options in
-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.
-
-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
-booting up.
-
-Command usage
--------------
-
- ab_select <slot_var_name> <interface> <dev[:part_number|#part_name]>
-
-for example:
-
- => ab_select slot_name mmc 1:4
-
-or
-
- => ab_select slot_name mmc 1#misc
-
-Result:
-
- => printenv slot_name
- slot_name=a
-
-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=
-
-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.
-
-References
-----------
-
-[1] https://source.android.com/devices/tech/ota/ab
-[2] bootable/recovery/bootloader_message/include/bootloader_message/bootloader_message.h
--- /dev/null
+.. 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/
+++ /dev/null
-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
--- /dev/null
+.. 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
+++ /dev/null
-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
--- /dev/null
+.. 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
+------------------
+
+* Two bulk endpoints (in, out) are required
+* Max packet size must be 64 bytes for full-speed and 512 bytes for
+ high-speed USB
+* The protocol is entirely host-driven and synchronous (unlike the
+ multi-channel, bi-directional, asynchronous ADB protocol)
+
+
+Transport and Framing
+---------------------
+
+1. Host sends a command, which is an ascii string in a single
+ packet no greater than 64 bytes.
+
+2. Client response with a single packet no greater than 64 bytes.
+ The first four bytes of the response are "OKAY", "FAIL", "DATA",
+ or "INFO". Additional bytes may contain an (ascii) informative
+ message.
+
+ a. INFO -> the remaining 60 bytes are an informative message
+ (providing progress or diagnostic messages). They should
+ be displayed and then step #2 repeats
+
+ b. FAIL -> the requested command failed. The remaining 60 bytes
+ of the response (if present) provide a textual failure message
+ to present to the user. Stop.
+
+ c. OKAY -> the requested command completed successfully. Go to #5
+
+ d. DATA -> the requested command is ready for the data phase.
+ A DATA response packet will be 12 bytes long, in the form of
+ DATA00000000 where the 8 digit hexidecimal number represents
+ the total data size to transfer.
+
+3. Data phase. Depending on the command, the host or client will
+ send the indicated amount of data. Short packets are always
+ acceptable and zero-length packets are ignored. This phase continues
+ until the client has sent or received the number of bytes indicated
+ in the "DATA" response above.
+
+4. Client responds with a single packet no greater than 64 bytes.
+ The first four bytes of the response are "OKAY", "FAIL", or "INFO".
+ Similar to #2:
+
+ a. INFO -> display the remaining 60 bytes and return to #4
+
+ b. FAIL -> display the remaining 60 bytes (if present) as a failure
+ reason and consider the command failed. Stop.
+
+ c. OKAY -> success. Go to #5
+
+5. Success. Stop.
+
+
+Example Session
+---------------
+
+.. code-block:: none
+
+ Host: "getvar:version" request version variable
+
+ Client: "OKAY0.4" return version "0.4"
+
+ Host: "getvar:nonexistant" request some undefined variable
+
+ Client: "OKAY" return value ""
+
+ Host: "download:00001234" request to send 0x1234 bytes of data
+
+ Client: "DATA00001234" ready to accept data
+
+ Host: < 0x1234 bytes > send data
+
+ Client: "OKAY" success
+
+ Host: "flash:bootloader" request to flash the data to the bootloader
+
+ Client: "INFOerasing flash" indicate status / progress
+ "INFOwriting flash"
+ "OKAY" indicate success
+
+ Host: "powerdown" send a command
+
+ Client: "FAILunknown command" indicate failure
+
+
+Command Reference
+-----------------
+
+* Command parameters are indicated by printf-style escape sequences.
+
+* Commands are ascii strings and sent without the quotes (which are
+ for illustration only here) and without a trailing 0 byte.
+
+* Commands that begin with a lowercase letter are reserved for this
+ 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.
+
+ "download:%08x" Write data to memory which will be later used
+ by "boot", "ramdisk", "flash", etc. The client
+ will reply with "DATA%08x" if it has enough
+ space in RAM or "FAIL" if not. The size of
+ the download is remembered.
+
+ "verify:%08x" Send a digital signature to verify the downloaded
+ data. Required if the bootloader is "secure"
+ otherwise "flash" and "boot" will be ignored.
+
+ "flash:%s" Write the previously downloaded image to the
+ named partition (if possible).
+
+ "erase:%s" Erase the indicated partition (clear to 0xFFs)
+
+ "boot" The previously downloaded data is a boot.img
+ and should be booted according to the normal
+ procedure for a boot.img
+
+ "continue" Continue booting as normal (if possible)
+
+ "reboot" Reboot the device.
+
+ "reboot-bootloader" Reboot back into the bootloader.
+ Useful for upgrade processes that require upgrading
+ the bootloader and then upgrading other partitions
+ using the new bootloader.
+
+ "powerdown" Power off the device.
+
+Client Variables
+----------------
+
+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::
+
+ version Version of FastBoot protocol supported.
+ It should be "0.3" for this document.
+
+ version-bootloader Version string for the Bootloader.
+
+ version-baseband Version string of the Baseband Software
+
+ product Name of the product
+
+ serialno Product serial number
+
+ secure If the value is "yes", this is a secure
+ bootloader requiring a signature before
+ it will install or boot images.
+
+Names starting with a lowercase character are reserved by this
+specification. OEM-specific names should not start with lowercase
+characters.
+++ /dev/null
-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
-------------------
-
-* Two bulk endpoints (in, out) are required
-* Max packet size must be 64 bytes for full-speed and 512 bytes for
- high-speed USB
-* The protocol is entirely host-driven and synchronous (unlike the
- multi-channel, bi-directional, asynchronous ADB protocol)
-
-
-Transport and Framing
----------------------
-
-1. Host sends a command, which is an ascii string in a single
- packet no greater than 64 bytes.
-
-2. Client response with a single packet no greater than 64 bytes.
- The first four bytes of the response are "OKAY", "FAIL", "DATA",
- or "INFO". Additional bytes may contain an (ascii) informative
- message.
-
- a. INFO -> the remaining 60 bytes are an informative message
- (providing progress or diagnostic messages). They should
- be displayed and then step #2 repeats
-
- b. FAIL -> the requested command failed. The remaining 60 bytes
- of the response (if present) provide a textual failure message
- to present to the user. Stop.
-
- c. OKAY -> the requested command completed successfully. Go to #5
-
- d. DATA -> the requested command is ready for the data phase.
- A DATA response packet will be 12 bytes long, in the form of
- DATA00000000 where the 8 digit hexidecimal number represents
- the total data size to transfer.
-
-3. Data phase. Depending on the command, the host or client will
- send the indicated amount of data. Short packets are always
- acceptable and zero-length packets are ignored. This phase continues
- until the client has sent or received the number of bytes indicated
- in the "DATA" response above.
-
-4. Client responds with a single packet no greater than 64 bytes.
- The first four bytes of the response are "OKAY", "FAIL", or "INFO".
- Similar to #2:
-
- a. INFO -> display the remaining 60 bytes and return to #4
-
- b. FAIL -> display the remaining 60 bytes (if present) as a failure
- reason and consider the command failed. Stop.
-
- c. OKAY -> success. Go to #5
-
-5. Success. Stop.
-
-
-Example Session
----------------
-
-Host: "getvar:version" request version variable
-
-Client: "OKAY0.4" return version "0.4"
-
-Host: "getvar:nonexistant" request some undefined variable
-
-Client: "OKAY" return value ""
-
-Host: "download:00001234" request to send 0x1234 bytes of data
-
-Client: "DATA00001234" ready to accept data
-
-Host: < 0x1234 bytes > send data
-
-Client: "OKAY" success
-
-Host: "flash:bootloader" request to flash the data to the bootloader
-
-Client: "INFOerasing flash" indicate status / progress
- "INFOwriting flash"
- "OKAY" indicate success
-
-Host: "powerdown" send a command
-
-Client: "FAILunknown command" indicate failure
-
-
-Command Reference
------------------
-
-* Command parameters are indicated by printf-style escape sequences.
-
-* Commands are ascii strings and sent without the quotes (which are
- for illustration only here) and without a trailing 0 byte.
-
-* Commands that begin with a lowercase letter are reserved for this
- specification. OEM-specific commands should not begin with a
- lowercase letter, to prevent incompatibilities with future specs.
-
- "getvar:%s" Read a config/version variable from the bootloader.
- The variable contents will be returned after the
- OKAY response.
-
- "download:%08x" Write data to memory which will be later used
- by "boot", "ramdisk", "flash", etc. The client
- will reply with "DATA%08x" if it has enough
- space in RAM or "FAIL" if not. The size of
- the download is remembered.
-
- "verify:%08x" Send a digital signature to verify the downloaded
- data. Required if the bootloader is "secure"
- otherwise "flash" and "boot" will be ignored.
-
- "flash:%s" Write the previously downloaded image to the
- named partition (if possible).
-
- "erase:%s" Erase the indicated partition (clear to 0xFFs)
-
- "boot" The previously downloaded data is a boot.img
- and should be booted according to the normal
- procedure for a boot.img
-
- "continue" Continue booting as normal (if possible)
-
- "reboot" Reboot the device.
-
- "reboot-bootloader" Reboot back into the bootloader.
- Useful for upgrade processes that require upgrading
- the bootloader and then upgrading other partitions
- using the new bootloader.
-
- "powerdown" Power off the device.
-
-
-
-Client Variables
-----------------
-
-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:
-
- version Version of FastBoot protocol supported.
- It should be "0.3" for this document.
-
- version-bootloader Version string for the Bootloader.
-
- version-baseband Version string of the Baseband Software
-
- product Name of the product
-
- serialno Product serial number
-
- secure If the value is "yes", this is a secure
- bootloader requiring a signature before
- it will install or boot images.
-
-Names starting with a lowercase character are reserved by this
-specification. OEM-specific names should not start with lowercase
-characters.
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Android Fastboot
+================
+
+Overview
+--------
+
+The protocol that is used over USB and UDP is described in [1]_.
+
+The current implementation supports the following standard commands:
+
+- ``boot``
+- ``continue``
+- ``download``
+- ``erase`` (if enabled)
+- ``flash`` (if enabled)
+- ``getvar``
+- ``reboot``
+- ``reboot-bootloader``
+- ``set_active`` (only a stub implementation which always succeeds)
+
+The following OEM commands are supported (if enabled):
+
+- ``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 [2]_.
+
+Board specific
+--------------
+
+USB configuration
+^^^^^^^^^^^^^^^^^
+
+The fastboot gadget relies on the USB download gadget, so the following
+options must be configured:
+
+::
+
+ CONFIG_USB_GADGET_DOWNLOAD
+ CONFIG_USB_GADGET_VENDOR_NUM
+ CONFIG_USB_GADGET_PRODUCT_NUM
+ CONFIG_USB_GADGET_MANUFACTURER
+
+NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers
+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
+platform. The location of the buffer and size are set with
+``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These
+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
+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::
+
+ fastboot_partition_alias_<alias partition name>=<actual partition name>
+
+for example::
+
+ 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.::
+
+ 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>``.
+
+Partition Names
+---------------
+
+The Fastboot implementation in U-Boot allows to write images into disk
+partitions. Target partitions are referred on the host computer by
+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::
+
+ <device type><device index letter><partition index>
+
+Example: ``hda3``, ``sdb1``, ``usbda1``.
+
+The device type is as follows:
+
+ * IDE, ATAPI and SATA disks: ``hd``
+ * SCSI disks: ``sd``
+ * USB media: ``usbd``
+ * MMC and SD cards: ``mmcsd``
+ * Disk on chip: ``docd``
+ * other: ``xx``
+
+The device index starts from ``a`` and refers to the interface (e.g. USB
+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
+"gpt" or "mbr". These names can be customized by defining the following
+configuration options:
+
+::
+
+ CONFIG_FASTBOOT_GPT_NAME
+ CONFIG_FASTBOOT_MBR_NAME
+
+In Action
+---------
+
+Enter into fastboot by executing the fastboot command in U-Boot for either USB::
+
+ => fastboot usb 0
+
+or UDP::
+
+ => fastboot udp
+ link up on port 0, speed 100, full duplex
+ Using ethernet@4a100000 device
+ Listening for fastboot command on 192.168.0.102
+
+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::
+
+ $ fastboot reboot
+
+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::
+
+ $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage
+ creating boot image...
+ creating boot image - 1847296 bytes
+ downloading 'boot.img'...
+ OKAY [ 2.766s]
+ booting...
+ OKAY [ -0.000s]
+ finished. total time: 2.766s
+
+and on the U-Boot side you should see::
+
+ Starting download of 1847296 bytes
+ ........................................................
+ downloading of 1847296 bytes finished
+ Booting kernel..
+ ## Booting Android Image at 0x81000000 ...
+ Kernel load addr 0x80008000 size 1801 KiB
+ Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
+ Loading Kernel Image ... OK
+ OK
+
+ Starting kernel ...
+
+References
+----------
+
+.. [1] :doc:`fastboot-protocol`
+.. [2] https://developer.android.com/studio/releases/platform-tools
+++ /dev/null
-================
-Android Fastboot
-================
-
-Overview
-========
-
-The protocol that is used over USB and UDP is described in
-``doc/android/fastboot-protocol.txt``.
-
-The current implementation supports the following standard commands:
-
-- ``boot``
-- ``continue``
-- ``download``
-- ``erase`` (if enabled)
-- ``flash`` (if enabled)
-- ``getvar``
-- ``reboot``
-- ``reboot-bootloader``
-- ``set_active`` (only a stub implementation which always succeeds)
-
-The following OEM commands are supported (if enabled):
-
-- 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
-
-Board specific
-==============
-
-USB configuration
------------------
-
-The fastboot gadget relies on the USB download gadget, so the following
-options must be configured:
-
-::
-
- CONFIG_USB_GADGET_DOWNLOAD
- CONFIG_USB_GADGET_VENDOR_NUM
- CONFIG_USB_GADGET_PRODUCT_NUM
- CONFIG_USB_GADGET_MANUFACTURER
-
-NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers
-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
-platform. The location of the buffer and size are set with
-``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These
-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
-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:
-
-``fastboot_partition_alias_<alias partition name>=<actual partition name>``
-
-for example:
-
-``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.
-
-``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>``.
-
-Partition Names
-===============
-
-The Fastboot implementation in U-Boot allows to write images into disk
-partitions. Target partitions are referred on the host computer by
-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:
-
- <device type><device index letter><partition index>
-
-Example: ``hda3``, ``sdb1``, ``usbda1``
-
-The device type is as follows:
-
- * IDE, ATAPI and SATA disks: ``hd``
- * SCSI disks: ``sd``
- * USB media: ``usbd``
- * MMC and SD cards: ``mmcsd``
- * Disk on chip: ``docd``
- * other: ``xx``
-
-The device index starts from ``a`` and refers to the interface (e.g. USB
-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
-"gpt" or "mbr". These names can be customized by defining the following
-configuration options:
-
-::
-
- CONFIG_FASTBOOT_GPT_NAME
- CONFIG_FASTBOOT_MBR_NAME
-
-In Action
-=========
-
-Enter into fastboot by executing the fastboot command in U-Boot for either USB:
-
-::
-
- => fastboot usb 0
-
-or UDP:
-
-::
-
- => fastboot udp
- link up on port 0, speed 100, full duplex
- Using ethernet@4a100000 device
- Listening for fastboot command on 192.168.0.102
-
-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:
-
-::
-
- $ fastboot reboot
-
-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:
-
-::
-
- $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage
- creating boot image...
- creating boot image - 1847296 bytes
- downloading 'boot.img'...
- OKAY [ 2.766s]
- booting...
- OKAY [ -0.000s]
- finished. total time: 2.766s
-
-and on the U-Boot side you should see:
-
-::
-
- Starting download of 1847296 bytes
- ........................................................
- downloading of 1847296 bytes finished
- Booting kernel..
- ## Booting Android Image at 0x81000000 ...
- Kernel load addr 0x80008000 size 1801 KiB
- Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
- Loading Kernel Image ... OK
- OK
-
- Starting kernel ...
--- /dev/null
+.. SPDX-License-Identifier: GPL-2.0+
+
+Android-specific doc
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ ab
+ avb2
+ bcb
+ boot-image
+ fastboot-protocol
+ fastboot
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
==================
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
projects / oweals / u-boot.git / commitdiff