+++ /dev/null
-================
-Android Fastboot
-================
-
-Overview
-========
-
-The protocol that is used over USB and UDP is described in the
-``README.android-fastboot-protocol`` file in the same directory.
-
-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 bootloader-version
- bootloader-version: U-Boot 2014.04-00005-gd24cabc
- finished. total time: 0.000s
-
-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
-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; \
-
-
-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
+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; \
+
+
+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
+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
+================
+Android Fastboot
+================
+
+Overview
+========
+
+The protocol that is used over USB and UDP is described in the
+``README.android-fastboot-protocol`` file in the same directory.
+
+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 bootloader-version
+ bootloader-version: U-Boot 2014.04-00005-gd24cabc
+ finished. total time: 0.000s
+
+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 ...
projects / oweals / u-boot.git / commitdiff