doc/README.android-fastboot

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