blob: 431191c473f267e05b4df4774c9de49c020834b1 [file] [log] [blame]
Alex Kiernana59e9132018-05-29 15:30:56 +00001================
Sebastian Siewior9d4471e2014-05-05 15:08:10 -05002Android Fastboot
Alex Kiernana59e9132018-05-29 15:30:56 +00003================
Sebastian Siewior9d4471e2014-05-05 15:08:10 -05004
5Overview
6========
Sebastian Siewior9d4471e2014-05-05 15:08:10 -05007
Alex Kiernana59e9132018-05-29 15:30:56 +00008The 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.
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050028
29Client installation
30===================
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050031
Alex Kiernana59e9132018-05-29 15:30:56 +000032The 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:
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050036
Alex Kiernana59e9132018-05-29 15:30:56 +000037https://developer.android.com/studio/releases/platform-tools
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050038
39Board specific
40==============
Alex Kiernana59e9132018-05-29 15:30:56 +000041
42USB configuration
43-----------------
44
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050045The fastboot gadget relies on the USB download gadget, so the following
46options must be configured:
47
Alex Kiernana59e9132018-05-29 15:30:56 +000048::
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.
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050058
Alex Kiernana59e9132018-05-29 15:30:56 +000059General configuration
60---------------------
Barnes, Clifton A1f9f3212014-07-22 11:23:56 -040061
Alex Kiernana59e9132018-05-29 15:30:56 +000062The 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``.
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050068
Alex Kiernana59e9132018-05-29 15:30:56 +000069Fastboot environment variables
70==============================
71
72Partition aliases
73-----------------
Sebastian Siewior9d4471e2014-05-05 15:08:10 -050074
Michael Scottced33492015-03-11 10:02:31 -070075Fastboot 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
Alex Kiernana59e9132018-05-29 15:30:56 +000078partition 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>``.
Michael Scottced33492015-03-11 10:02:31 -0700107
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200108Partition Names
109===============
Alex Kiernana59e9132018-05-29 15:30:56 +0000110
111The Fastboot implementation in U-Boot allows to write images into disk
112partitions. Target partitions are referred on the host computer by
113their names.
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200114
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
Alex Kiernana59e9132018-05-29 15:30:56 +0000120 <device type><device index letter><partition index>
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200121
Alex Kiernana59e9132018-05-29 15:30:56 +0000122Example: ``hda3``, ``sdb1``, ``usbda1``
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200123
124The device type is as follows:
125
Alex Kiernana59e9132018-05-29 15:30:56 +0000126 * 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``
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200132
Alex Kiernana59e9132018-05-29 15:30:56 +0000133The device index starts from ``a`` and refers to the interface (e.g. USB
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200134controller, SD/MMC controller) or disk index. The partition index starts
Alex Kiernana59e9132018-05-29 15:30:56 +0000135from ``1`` and describes the partition number on the particular device.
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200136
137Writing Partition Table
138=======================
Alex Kiernana59e9132018-05-29 15:30:56 +0000139
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200140Fastboot 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
Alex Kiernana59e9132018-05-29 15:30:56 +0000145::
146
147 CONFIG_FASTBOOT_GPT_NAME
148 CONFIG_FASTBOOT_MBR_NAME
Petr Kulhavy9f174c92016-09-09 10:27:16 +0200149
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500150In Action
151=========
Alex Kiernana59e9132018-05-29 15:30:56 +0000152
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
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500167
168On the client side you can fetch the bootloader version for instance:
Alex Kiernana59e9132018-05-29 15:30:56 +0000169
170::
171
172 $ fastboot getvar bootloader-version
173 bootloader-version: U-Boot 2014.04-00005-gd24cabc
174 finished. total time: 0.000s
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500175
176or initiate a reboot:
Alex Kiernana59e9132018-05-29 15:30:56 +0000177
178::
179
180 $ fastboot reboot
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500181
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
Alex Kiernana59e9132018-05-29 15:30:56 +0000185the an image in Android format *or* pass a binary kernel and let the
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500186fastboot client wrap the Android suite around it. On OMAP for instance you
187take zImage kernel and pass it to the fastboot client:
188
Alex Kiernana59e9132018-05-29 15:30:56 +0000189::
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
Sebastian Siewior9d4471e2014-05-05 15:08:10 -0500213
Alex Kiernana59e9132018-05-29 15:30:56 +0000214 Starting kernel ...