1================
2Android Fastboot
3================
4
5Overview
6========
7
8The protocol that is used over USB and UDP is described in the
9``README.android-fastboot-protocol`` file in the same directory.
10
11The 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
23The following OEM commands are supported (if enabled):
24
25- oem format - this executes ``gpt write mmc %x $partitions``
26
27Support for both eMMC and NAND devices is included.
28
29Client installation
30===================
31
32The counterpart to this is the fastboot client which can be found in
33Android's ``platform/system/core`` repository in the fastboot
34folder. It runs on Windows, Linux and OSX. The fastboot client is
35part of the Android SDK Platform-Tools and can be downloaded from:
36
37https://developer.android.com/studio/releases/platform-tools
38
39Board specific
40==============
41
42USB configuration
43-----------------
44
45The fastboot gadget relies on the USB download gadget, so the following
46options 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
55NOTE: The ``CONFIG_USB_GADGET_VENDOR_NUM`` must be one of the numbers
56supported by the fastboot client. The list of vendor IDs supported can
57be found in the fastboot client source code.
58
59General configuration
60---------------------
61
62The fastboot protocol requires a large memory buffer for
63downloads. This buffer should be as large as possible for a
64platform. The location of the buffer and size are set with
65``CONFIG_FASTBOOT_BUF_ADDR`` and ``CONFIG_FASTBOOT_BUF_SIZE``. These
66may be overridden on the fastboot command line using ``-l`` and
67``-s``.
68
69Fastboot environment variables
70==============================
71
72Partition aliases
73-----------------
74
75Fastboot partition aliases can also be defined for devices where GPT
76limitations prevent user-friendly partition names such as "boot", "system"
77and "cache".  Or, where the actual partition name doesn't match a standard
78partition name used commonly with fastboot.
79
80The current implementation checks aliases when accessing partitions by
81name (flash_write and erase functions).  To define a partition alias
82add an environment variable similar to:
83
84``fastboot_partition_alias_<alias partition name>=<actual partition name>``
85
86for example:
87
88``fastboot_partition_alias_boot=LNX``
89
90Variable overrides
91------------------
92
93Variables retrived through ``getvar`` can be overridden by defining
94environment variables of the form ``fastboot.<variable>``. These are
95looked up first so can be used to override values which would
96otherwise be returned. Using this mechanism you can also return types
97for NAND filesystems, as the fully parameterised variable is looked
98up, e.g.
99
100``fastboot.partition-type:boot=jffs2``
101
102Boot command
103------------
104
105When executing the fastboot ``boot`` command, if ``fastboot_bootcmd`` is set then
106that will be executed in place of ``bootm <CONFIG_FASTBOOT_BUF_ADDR>``.
107
108Partition Names
109===============
110
111The Fastboot implementation in U-Boot allows to write images into disk
112partitions. Target partitions are referred on the host computer by
113their names.
114
115For GPT/EFI the respective partition name is used.
116
117For MBR the partitions are referred by generic names according to the
118following schema:
119
120  <device type><device index letter><partition index>
121
122Example: ``hda3``, ``sdb1``, ``usbda1``
123
124The 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
133The device index starts from ``a`` and refers to the interface (e.g. USB
134controller, SD/MMC controller) or disk index. The partition index starts
135from ``1`` and describes the partition number on the particular device.
136
137Writing Partition Table
138=======================
139
140Fastboot also allows to write the partition table to the media. This can be
141done by writing the respective partition table image to a special target
142"gpt" or "mbr". These names can be customized by defining the following
143configuration options:
144
145::
146
147   CONFIG_FASTBOOT_GPT_NAME
148   CONFIG_FASTBOOT_MBR_NAME
149
150In Action
151=========
152
153Enter into fastboot by executing the fastboot command in U-Boot for either USB:
154
155::
156
157   => fastboot usb 0
158
159or 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
168On 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
176or initiate a reboot:
177
178::
179
180   $ fastboot reboot
181
182and once the client comes back, the board should reset.
183
184You can also specify a kernel image to boot. You have to either specify
185the an image in Android format *or* pass a binary kernel and let the
186fastboot client wrap the Android suite around it. On OMAP for instance you
187take 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
200and 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