Home | History | Annotate | Download | only in doc 
      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 ...
    215