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