doc/android/fastboot.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Android Fastboot
   4 ================
   5
   6 Overview
   7 --------
   8
   9 The protocol that is used over USB and UDP is described in [1]_.
  10
  11 The current implementation supports the following standard commands:
  12
  13 - ``boot``
  14 - ``continue``
  15 - ``download``
  16 - ``erase`` (if enabled)
  17 - ``flash`` (if enabled)
  18 - ``getvar``
  19 - ``reboot``
  20 - ``reboot-bootloader``
  21 - ``set_active`` (only a stub implementation which always succeeds)
  22
  23 The following OEM commands are supported (if enabled):
  24
  25 - ``oem format`` - this executes ``gpt write mmc %x $partitions``
  26 - ``oem partconf`` - this executes ``mmc partconf %x <arg> 0`` to configure eMMC
  27   with <arg> = boot_ack boot_partition
  28 - ``oem bootbus``  - this executes ``mmc bootbus %x %s`` to configure eMMC
  29
  30 Support for both eMMC and NAND devices is included.
  31
  32 Client installation
  33 -------------------
  34
  35 The counterpart to this is the fastboot client which can be found in
  36 Android's ``platform/system/core`` repository in the fastboot
  37 folder. It runs on Windows, Linux and OSX. The fastboot client is
  38 part of the Android SDK Platform-Tools and can be downloaded from [2]_.
  39
  40 Board specific
  41 --------------
  42
  43 USB configuration
  44 ^^^^^^^^^^^^^^^^^
  45
  46 The fastboot gadget relies on the USB download gadget, so the following
  47 options must be configured:
  48
  49 ::
  50
  51    CONFIG_USB_GADGET_DOWNLOAD
  52    CONFIG_USB_GADGET_VENDOR_NUM
  53    CONFIG_USB_GADGET_PRODUCT_NUM
  54    CONFIG_USB_GADGET_MANUFACTURER
  55
  56 NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers
  57 supported by the fastboot client. The list of vendor IDs supported can
  58 be found in the fastboot client source code.
  59
  60 General configuration
  61 ^^^^^^^^^^^^^^^^^^^^^
  62
  63 The fastboot protocol requires a large memory buffer for
  64 downloads. This buffer should be as large as possible for a
  65 platform. The location of the buffer and size are set with
  66 ``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These
  67 may be overridden on the fastboot command line using ``-l`` and
  68 ``-s``.
  69
  70 Fastboot environment variables
  71 ------------------------------
  72
  73 Partition aliases
  74 ^^^^^^^^^^^^^^^^^
  75
  76 Fastboot partition aliases can also be defined for devices where GPT
  77 limitations prevent user-friendly partition names such as ``boot``, ``system``
  78 and ``cache``.  Or, where the actual partition name doesn't match a standard
  79 partition name used commonly with fastboot.
  80
  81 The current implementation checks aliases when accessing partitions by
  82 name (flash_write and erase functions).  To define a partition alias
  83 add an environment variable similar to::
  84
  85     fastboot_partition_alias_<alias partition name>=<actual partition name>
  86
  87 for example::
  88
  89     fastboot_partition_alias_boot=LNX
  90
  91 Raw partition descriptors
  92 ^^^^^^^^^^^^^^^^^^^^^^^^^
  93
  94 In cases where no partition table is present, a raw partition descriptor can be
  95 defined, specifying the offset, size, and optionally the MMC hardware partition
  96 number for a given partition name.
  97
  98 This is useful when using fastboot to flash files (e.g. SPL or U-Boot) to a
  99 specific offset in the eMMC boot partition, without having to update the entire
 100 boot partition.
 101
 102 To define a raw partition descriptor, add an environment variable similar to::
 103
 104     fastboot_raw_partition_<raw partition name>=<offset> <size> [mmcpart <num>]
 105
 106 for example::
 107
 108     fastboot_raw_partition_boot=0x100 0x1f00 mmcpart 1
 109
 110 Variable overrides
 111 ^^^^^^^^^^^^^^^^^^
 112
 113 Variables retrived through ``getvar`` can be overridden by defining
 114 environment variables of the form ``fastboot.<variable>``. These are
 115 looked up first so can be used to override values which would
 116 otherwise be returned. Using this mechanism you can also return types
 117 for NAND filesystems, as the fully parameterised variable is looked
 118 up, e.g.::
 119
 120     fastboot.partition-type:boot=jffs2
 121
 122 Boot command
 123 ^^^^^^^^^^^^
 124
 125 When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set
 126 then that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
 127
 128 Partition Names
 129 ---------------
 130
 131 The Fastboot implementation in U-Boot allows to write images into disk
 132 partitions. Target partitions are referred on the host computer by
 133 their names.
 134
 135 For GPT/EFI the respective partition name is used.
 136
 137 For MBR the partitions are referred by generic names according to the
 138 following schema::
 139
 140     <device type><device index letter><partition index>
 141
 142 Example: ``hda3``, ``sdb1``, ``usbda1``.
 143
 144 The device type is as follows:
 145
 146   * IDE, ATAPI and SATA disks: ``hd``
 147   * SCSI disks: ``sd``
 148   * USB media: ``usbd``
 149   * MMC and SD cards: ``mmcsd``
 150   * Disk on chip: ``docd``
 151   * other: ``xx``
 152
 153 The device index starts from ``a`` and refers to the interface (e.g. USB
 154 controller, SD/MMC controller) or disk index. The partition index starts
 155 from ``1`` and describes the partition number on the particular device.
 156
 157 Writing Partition Table
 158 -----------------------
 159
 160 Fastboot also allows to write the partition table to the media. This can be
 161 done by writing the respective partition table image to a special target
 162 "gpt" or "mbr". These names can be customized by defining the following
 163 configuration options:
 164
 165 ::
 166
 167    CONFIG_FASTBOOT_GPT_NAME
 168    CONFIG_FASTBOOT_MBR_NAME
 169
 170 In Action
 171 ---------
 172
 173 Enter into fastboot by executing the fastboot command in U-Boot for either USB::
 174
 175    => fastboot usb 0
 176
 177 or UDP::
 178
 179    => fastboot udp
 180    link up on port 0, speed 100, full duplex
 181    Using ethernet@4a100000 device
 182    Listening for fastboot command on 192.168.0.102
 183
 184 On the client side you can fetch the bootloader version for instance::
 185
 186    $ fastboot getvar version-bootloader
 187    version-bootloader: U-Boot 2019.07-rc4-00240-g00c9f2a2ec
 188    Finished. Total time: 0.005s
 189
 190 or initiate a reboot::
 191
 192    $ fastboot reboot
 193
 194 and once the client comes back, the board should reset.
 195
 196 You can also specify a kernel image to boot. You have to either specify
 197 the an image in Android format *or* pass a binary kernel and let the
 198 fastboot client wrap the Android suite around it. On OMAP for instance you
 199 take zImage kernel and pass it to the fastboot client::
 200
 201    $ fastboot -b 0x80000000 -c "console=ttyO2 earlyprintk root=/dev/ram0 mem=128M" boot zImage
 202    creating boot image...
 203    creating boot image - 1847296 bytes
 204    downloading 'boot.img'...
 205    OKAY [  2.766s]
 206    booting...
 207    OKAY [ -0.000s]
 208    finished. total time: 2.766s
 209
 210 and on the U-Boot side you should see::
 211
 212    Starting download of 1847296 bytes
 213    ........................................................
 214    downloading of 1847296 bytes finished
 215    Booting kernel..
 216    ## Booting Android Image at 0x81000000 ...
 217    Kernel load addr 0x80008000 size 1801 KiB
 218    Kernel command line: console=ttyO2 earlyprintk root=/dev/ram0 mem=128M
 219       Loading Kernel Image ... OK
 220    OK
 221
 222    Starting kernel ...
 223
 224 References
 225 ----------
 226
 227 .. [1] :doc:`fastboot-protocol`
 228 .. [2] https://developer.android.com/studio/releases/platform-tools