diff options
Diffstat (limited to 'roms/u-boot/doc/android')
| -rw-r--r-- | roms/u-boot/doc/android/ab.rst | 72 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/avb2.rst | 133 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/bcb.rst | 100 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/boot-image.rst | 155 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/fastboot-protocol.rst | 178 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/fastboot.rst | 234 | ||||
| -rw-r--r-- | roms/u-boot/doc/android/index.rst | 14 |
7 files changed, 886 insertions, 0 deletions
diff --git a/roms/u-boot/doc/android/ab.rst b/roms/u-boot/doc/android/ab.rst new file mode 100644 index 000000000..961895c32 --- /dev/null +++ b/roms/u-boot/doc/android/ab.rst @@ -0,0 +1,72 @@ +.. 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 diff --git a/roms/u-boot/doc/android/avb2.rst b/roms/u-boot/doc/android/avb2.rst new file mode 100644 index 000000000..a07211957 --- /dev/null +++ b/roms/u-boot/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/roms/u-boot/doc/android/bcb.rst b/roms/u-boot/doc/android/bcb.rst new file mode 100644 index 000000000..886160830 --- /dev/null +++ b/roms/u-boot/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/roms/u-boot/doc/android/boot-image.rst b/roms/u-boot/doc/android/boot-image.rst new file mode 100644 index 000000000..fa8f2a47e --- /dev/null +++ b/roms/u-boot/doc/android/boot-image.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Sam Protsenko <joe.skb7@gmail.com> + +Android Boot Image +================== + +Overview +-------- + +Android Boot Image is used to boot Android OS. It usually contains kernel image +(like ``zImage`` file) and ramdisk. Sometimes it can contain additional +binaries. This image is built as a part of AOSP (called ``boot.img``), and being +flashed into ``boot`` partition on eMMC. Bootloader then reads that image from +``boot`` partition to RAM and boots the kernel from it. Kernel than starts +``init`` process from the ramdisk. It should be mentioned that recovery image +(``recovery.img``) also has Android Boot Image format. + +Android Boot Image format is described at [1]_. At the moment it can have one of +next image headers: + +* v0: it's called *legacy* boot image header; used in devices launched before + Android 9; contains kernel image, ramdisk and second stage bootloader + (usually unused) +* v1: used in devices launched with Android 9; adds ``recovery_dtbo`` field, + which should be used for non-A/B devices in ``recovery.img`` (see [2]_ for + details) +* v2: used in devices launched with Android 10; adds ``dtb`` field, which + references payload containing DTB blobs (either concatenated one after the + other, or in Android DTBO image format) + +v2, v1 and v0 formats are backward compatible. + +The Android Boot Image format is represented by +:c:type:`struct andr_img_hdr <andr_img_hdr>` in U-Boot, and can be seen in +``include/android_image.h``. U-Boot supports booting Android Boot Image and also +has associated command + +Booting +------- + +U-Boot is able to boot the Android OS from Android Boot Image using ``bootm`` +command. In order to use Android Boot Image format support, next option should +be enabled:: + + CONFIG_ANDROID_BOOT_IMAGE=y + +Then one can use next ``bootm`` command call to run Android: + +.. code-block:: bash + + => bootm $loadaddr $loadaddr $fdtaddr + +where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` - +address in RAM where DTB blob was loaded. + +And parameters are, correspondingly: + + 1. Where kernel image is located in RAM + 2. Where ramdisk is located in RAM (can be ``"-"`` if not applicable) + 3. Where DTB blob is located in RAM + +``bootm`` command will figure out that image located in ``$loadaddr`` has +Android Boot Image format, will parse that and boot the kernel from it, +providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to +kernel via DTB. + +DTB and DTBO blobs +------------------ + +``bootm`` command can't just use DTB blob from Android Boot Image (``dtb`` +field), because: + +* there is no DTB area in Android Boot Image before v2 +* there may be several DTB blobs in DTB area (e.g. for different SoCs) +* some DTBO blobs may have to be merged in DTB blobs before booting + (e.g. for different boards) + +So user has to prepare DTB blob manually and provide it in a 3rd parameter +of ``bootm`` command. Next commands can be used to do so: + +1. ``abootimg``: manipulates Anroid Boot Image, allows one to extract + meta-information and payloads from it +2. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract + DTB/DTBO blobs from it + +In order to use those, please enable next config options:: + + CONFIG_CMD_ABOOTIMG=y + CONFIG_CMD_ADTIMG=y + +For example, let's assume we have next Android partitions on eMMC: + +* ``boot``: contains Android Boot Image v2 (including DTB blobs) +* ``dtbo``: contains DTBO blobs + +Then next command sequence can be used to boot Android: + +.. code-block:: bash + + => mmc dev 1 + + # Read boot image to RAM (into $loadaddr) + => part start mmc 1 boot boot_start + => part size mmc 1 boot boot_size + => mmc read $loadaddr $boot_start $boot_size + + # Read DTBO image to RAM (into $dtboaddr) + => part start mmc 1 dtbo dtbo_start + => part size mmc 1 dtbo dtbo_size + => mmc read $dtboaddr $dtbo_start $dtbo_size + + # Copy required DTB blob (into $fdtaddr) + => abootimg get dtb --index=0 dtb0_start dtb0_size + => cp.b $dtb0_start $fdtaddr $dtb0_size + + # Merge required DTBO blobs into DTB blob + => fdt addr $fdtaddr 0x100000 + => adtimg addr $dtboaddr + => adtimg get dt --index=0 $dtbo0_addr + => fdt apply $dtbo0_addr + + # Boot Android + => bootm $loadaddr $loadaddr $fdtaddr + +This sequence should be used for Android 10 boot. Of course, the whole Android +boot procedure includes much more actions, like: + +* obtaining reboot reason from BCB (see [4]_) +* implementing recovery boot +* implementing fastboot boot +* implementing A/B slotting (see [5]_) +* implementing AVB2.0 (see [6]_) + +But Android Boot Image booting is the most crucial part in Android boot scheme. + +All Android bootloader requirements documentation is available at [7]_. Some +overview on the whole Android 10 boot process can be found at [8]_. + +C API for working with Android Boot Image format +------------------------------------------------ + +.. kernel-doc:: common/image-android.c + :internal: + +References +---------- + +.. [1] https://source.android.com/devices/bootloader/boot-image-header +.. [2] https://source.android.com/devices/bootloader/recovery-image +.. [3] https://source.android.com/devices/architecture/dto/partitions +.. [4] :doc:`bcb` +.. [5] :doc:`ab` +.. [6] :doc:`avb2` +.. [7] https://source.android.com/devices/bootloader +.. [8] https://connect.linaro.org/resources/san19/san19-217/ diff --git a/roms/u-boot/doc/android/fastboot-protocol.rst b/roms/u-boot/doc/android/fastboot-protocol.rst new file mode 100644 index 000000000..e8cbd7f24 --- /dev/null +++ b/roms/u-boot/doc/android/fastboot-protocol.rst @@ -0,0 +1,178 @@ +.. 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. + + "ucmd" execute any bootloader command and wait until it + finishs. + + "acmd" execute any bootloader command, do not wait. + +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. diff --git a/roms/u-boot/doc/android/fastboot.rst b/roms/u-boot/doc/android/fastboot.rst new file mode 100644 index 000000000..7611f0703 --- /dev/null +++ b/roms/u-boot/doc/android/fastboot.rst @@ -0,0 +1,234 @@ +.. 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) +- ``ucmd`` (if enabled) +- ``acmd`` (if enabled) + +The following OEM commands are supported (if enabled): + +- ``oem format`` - this executes ``gpt write mmc %x $partitions`` +- ``oem partconf`` - this executes ``mmc partconf %x <arg> 0`` to configure eMMC + with <arg> = boot_ack boot_partition +- ``oem bootbus`` - this executes ``mmc bootbus %x %s`` to configure eMMC + +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 + +Raw partition descriptors +^^^^^^^^^^^^^^^^^^^^^^^^^ + +In cases where no partition table is present, a raw partition descriptor can be +defined, specifying the offset, size, and optionally the MMC hardware partition +number for a given partition name. + +This is useful when using fastboot to flash files (e.g. SPL or U-Boot) to a +specific offset in the eMMC boot partition, without having to update the entire +boot partition. + +To define a raw partition descriptor, add an environment variable similar to:: + + fastboot_raw_partition_<raw partition name>=<offset> <size> [mmcpart <num>] + +for example:: + + fastboot_raw_partition_boot=0x100 0x1f00 mmcpart 1 + +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. + +Alternatively, partition types may be specified using :ref:`U-Boot's partition +syntax <partitions>`. This allows specifying partitions like ``0.1``, +``0#boot``, or ``:3``. The interface is always ``mmc``. + +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 diff --git a/roms/u-boot/doc/android/index.rst b/roms/u-boot/doc/android/index.rst new file mode 100644 index 000000000..225d6f125 --- /dev/null +++ b/roms/u-boot/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 + fastboot-protocol + fastboot |