README.md
1Fastboot
2--------
3
4The fastboot protocol is a mechanism for communicating with bootloaders
5over USB or ethernet. It is designed to be very straightforward to implement,
6to allow it to be used across a wide range of devices and from hosts running
7Linux, macOS, or Windows.
8
9
10## Basic Requirements
11
12* USB
13 * Two bulk endpoints (in, out) are required
14 * Max packet size must be 64 bytes for full-speed, 512 bytes for
15 high-speed and 1024 bytes for Super Speed USB.
16 * The protocol is entirely host-driven and synchronous (unlike the
17 multi-channel, bi-directional, asynchronous ADB protocol)
18
19* TCP or UDP
20 * Device must be reachable via IP.
21 * Device will act as the server, fastboot will be the client.
22 * Fastboot data is wrapped in a simple protocol; see below for details.
23
24
25## Transport and Framing
26
271. Host sends a command, which is an ascii string in a single
28 packet no greater than 64 bytes.
29
302. Client response with a single packet no greater than 64 bytes.
31 The first four bytes of the response are "OKAY", "FAIL", "DATA",
32 or "INFO". Additional bytes may contain an (ascii) informative
33 message.
34
35 a. INFO -> the remaining 60 bytes are an informative message
36 (providing progress or diagnostic messages). They should
37 be displayed and then step #2 repeats
38
39 b. FAIL -> the requested command failed. The remaining 60 bytes
40 of the response (if present) provide a textual failure message
41 to present to the user. Stop.
42
43 c. OKAY -> the requested command completed successfully. Go to #5
44
45 d. DATA -> the requested command is ready for the data phase.
46 A DATA response packet will be 12 bytes long, in the form of
47 DATA00000000 where the 8 digit hexadecimal number represents
48 the total data size to transfer.
49
503. Data phase. Depending on the command, the host or client will
51 send the indicated amount of data. Short packets are always
52 acceptable and zero-length packets are ignored. This phase continues
53 until the client has sent or received the number of bytes indicated
54 in the "DATA" response above.
55
564. Client responds with a single packet no greater than 64 bytes.
57 The first four bytes of the response are "OKAY", "FAIL", or "INFO".
58 Similar to #2:
59
60 a. INFO -> display the remaining 60 bytes and return to #4
61
62 b. FAIL -> display the remaining 60 bytes (if present) as a failure
63 reason and consider the command failed. Stop.
64
65 c. OKAY -> success. Go to #5
66
675. Success. Stop.
68
69
70## Example Session
71
72 Host: "getvar:version" request version variable
73
74 Client: "OKAY0.4" return version "0.4"
75
76 Host: "getvar:nonexistant" request some undefined variable
77
78 Client: "FAILUnknown variable" getvar failure; see getvar details below
79
80 Host: "download:00001234" request to send 0x1234 bytes of data
81
82 Client: "DATA00001234" ready to accept data
83
84 Host: < 0x1234 bytes > send data
85
86 Client: "OKAY" success
87
88 Host: "flash:bootloader" request to flash the data to the bootloader
89
90 Client: "INFOerasing flash" indicate status / progress
91 "INFOwriting flash"
92 "OKAY" indicate success
93
94 Host: "powerdown" send a command
95
96 Client: "FAILunknown command" indicate failure
97
98
99## Command Reference
100
101* Command parameters are indicated by printf-style escape sequences.
102
103* Commands are ascii strings and sent without the quotes (which are
104 for illustration only here) and without a trailing 0 byte.
105
106* Commands that begin with a lowercase letter are reserved for this
107 specification. OEM-specific commands should not begin with a
108 lowercase letter, to prevent incompatibilities with future specs.
109
110The various currently defined commands are:
111
112 getvar:%s Read a config/version variable from the bootloader.
113 The variable contents will be returned after the
114 OKAY response. If the variable is unknown, the bootloader
115 should return a FAIL response, optionally with an error
116 message.
117
118 Previous versions of this document indicated that getvar
119 should return an empty OKAY response for unknown
120 variables, so older devices might exhibit this behavior,
121 but new implementations should return FAIL instead.
122
123 download:%08x Write data to memory which will be later used
124 by "boot", "ramdisk", "flash", etc. The client
125 will reply with "DATA%08x" if it has enough
126 space in RAM or "FAIL" if not. The size of
127 the download is remembered.
128
129 upload Read data from memory which was staged by the last
130 command, e.g. an oem command. The client will reply
131 with "DATA%08x" if it is ready to send %08x bytes of
132 data. If no data was staged in the last command,
133 the client must reply with "FAIL". After the client
134 successfully sends %08x bytes, the client shall send
135 a single packet starting with "OKAY". Clients
136 should not support "upload" unless it supports an
137 oem command that requires "upload" capabilities.
138
139 flash:%s Write the previously downloaded image to the
140 named partition (if possible).
141
142 erase:%s Erase the indicated partition (clear to 0xFFs)
143
144 boot The previously downloaded data is a boot.img
145 and should be booted according to the normal
146 procedure for a boot.img
147
148 continue Continue booting as normal (if possible)
149
150 reboot Reboot the device.
151
152 reboot-bootloader
153 Reboot back into the bootloader.
154 Useful for upgrade processes that require upgrading
155 the bootloader and then upgrading other partitions
156 using the new bootloader.
157
158
159
160## Client Variables
161
162The "getvar:%s" command is used to read client variables which
163represent various information about the device and the software
164on it.
165
166The various currently defined names are:
167
168 version Version of FastBoot protocol supported.
169 It should be "0.4" for this document.
170
171 version-bootloader Version string for the Bootloader.
172
173 version-baseband Version string of the Baseband Software
174
175 product Name of the product
176
177 serialno Product serial number
178
179 secure If the value is "yes", this is a secure
180 bootloader requiring a signature before
181 it will install or boot images.
182
183 is-userspace If the value is "yes", the device is running
184 fastbootd. Otherwise, it is running fastboot
185 in the bootloader.
186
187Names starting with a lowercase character are reserved by this
188specification. OEM-specific names should not start with lowercase
189characters.
190
191## Logical Partitions
192
193There are a number of commands to interact with logical partitions:
194
195 update-super:%s:%s Write the previously downloaded image to a super
196 partition. Unlike the "flash" command, this has
197 special rules. The image must have been created by
198 the lpmake command, and must not be a sparse image.
199 If the last argument is "wipe", then all existing
200 logical partitions are deleted. If no final argument
201 is specified, the partition tables are merged. Any
202 partition in the new image that does not exist in the
203 old image is created with a zero size.
204
205 In all cases, this will cause the temporary "scratch"
206 partition to be deleted if it exists.
207
208 create-logical-partition:%s:%d
209 Create a logical partition with the given name and
210 size, in the super partition.
211
212 delete-logical-partition:%s
213 Delete a logical partition with the given name.
214
215 resize-logical-partition:%s:%d
216 Change the size of the named logical partition.
217
218In addition, there is a variable to test whether a partition is logical:
219
220 is-logical:%s If the value is "yes", the partition is logical.
221 Otherwise the partition is physical.
222
223## TCP Protocol v1
224
225The TCP protocol is designed to be a simple way to use the fastboot protocol
226over ethernet if USB is not available.
227
228The device will open a TCP server on port 5554 and wait for a fastboot client
229to connect.
230
231### Handshake
232Upon connecting, both sides will send a 4-byte handshake message to ensure they
233are speaking the same protocol. This consists of the ASCII characters "FB"
234followed by a 2-digit base-10 ASCII version number. For example, the version 1
235handshake message will be [FB01].
236
237If either side detects a malformed handshake, it should disconnect.
238
239The protocol version to use must be the minimum of the versions sent by each
240side; if either side cannot speak this protocol version, it should disconnect.
241
242### Fastboot Data
243Once the handshake is complete, fastboot data will be sent as follows:
244
245 [data_size][data]
246
247Where data\_size is an unsigned 8-byte big-endian binary value, and data is the
248fastboot packet. The 8-byte length is intended to provide future-proofing even
249though currently fastboot packets have a 4-byte maximum length.
250
251### Example
252In this example the fastboot host queries the device for two variables,
253"version" and "none".
254
255 Host <connect to the device on port 5555>
256 Host FB01
257 Device FB01
258 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version
259 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
260 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
261 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable
262 Host <disconnect>
263
264
265## UDP Protocol v1
266
267The UDP protocol is more complex than TCP since we must implement reliability
268to ensure no packets are lost, but the general concept of wrapping the fastboot
269protocol is the same.
270
271Overview:
272 1. As with TCP, the device will listen on UDP port 5554.
273 2. Maximum UDP packet size is negotiated during initialization.
274 3. The host drives all communication; the device may only send a packet as a
275 response to a host packet.
276 4. If the host does not receive a response in 500ms it will re-transmit.
277
278### UDP Packet format
279
280 +----------+----+-------+-------+--------------------+
281 | Byte # | 0 | 1 | 2 - 3 | 4+ |
282 +----------+----+-------+-------+--------------------+
283 | Contents | ID | Flags | Seq # | Data |
284 +----------+----+-------+-------+--------------------+
285
286 ID Packet ID:
287 0x00: Error.
288 0x01: Query.
289 0x02: Initialization.
290 0x03: Fastboot.
291
292 Packet types are described in more detail below.
293
294 Flags Packet flags: 0 0 0 0 0 0 0 C
295 C=1 indicates a continuation packet; the data is too large and will
296 continue in the next packet.
297
298 Remaining bits are reserved for future use and must be set to 0.
299
300 Seq # 2-byte packet sequence number (big-endian). The host will increment
301 this by 1 with each new packet, and the device must provide the
302 corresponding sequence number in the response packets.
303
304 Data Packet data, not present in all packets.
305
306### Packet Types
307
308 Query
309 The host sends a query packet once on startup to sync with the device.
310 The host will not know the current sequence number, so the device must
311 respond to all query packets regardless of sequence number.
312
313 The response data field should contain a 2-byte big-endian value
314 giving the next expected sequence number.
315
316 Init
317 The host sends an init packet once the query response is returned. The
318 device must abort any in-progress operation and prepare for a new
319 fastboot session. This message is meant to allow recovery if a
320 previous session failed, e.g. due to network error or user Ctrl+C.
321
322 The data field contains two big-endian 2-byte values, a protocol
323 version and the max UDP packet size (including the 4-byte header).
324 Both the host and device will send these values, and in each case
325 the minimum of the sent values must be used.
326
327 Fastboot
328 These packets wrap the fastboot protocol. To write, the host will
329 send a packet with fastboot data, and the device will reply with an
330 empty packet as an ACK. To read, the host will send an empty packet,
331 and the device will reply with fastboot data. The device may not give
332 any data in the ACK packet.
333
334 Error
335 The device may respond to any packet with an error packet to indicate
336 a UDP protocol error. The data field should contain an ASCII string
337 describing the error. This is the only case where a device is allowed
338 to return a packet ID other than the one sent by the host.
339
340### Packet Size
341The maximum packet size is negotiated by the host and device in the Init packet.
342Devices must support at least 512-byte packets, but packet size has a direct
343correlation with download speed, so devices are strongly suggested to support at
344least 1024-byte packets. On a local network with 0.5ms round-trip time this will
345provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly
346less.
347
348Query and Initialization packets, which are sent before size negotiation is
349complete, must always be 512 bytes or less.
350
351### Packet Re-Transmission
352The host will re-transmit any packet that does not receive a response. The
353requirement of exactly one device response packet per host packet is how we
354achieve reliability and in-order delivery of packets.
355
356For simplicity of implementation, there is no windowing of multiple
357unacknowledged packets in this version of the protocol. The host will continue
358to send the same packet until a response is received. Windowing functionality
359may be implemented in future versions if necessary to increase performance.
360
361The first Query packet will only be attempted a small number of times, but
362subsequent packets will attempt to retransmit for at least 1 minute before
363giving up. This means a device may safely ignore host UDP packets for up to 1
364minute during long operations, e.g. writing to flash.
365
366### Continuation Packets
367Any packet may set the continuation flag to indicate that the data is
368incomplete. Large data such as downloading an image may require many
369continuation packets. The receiver should respond to a continuation packet with
370an empty packet to acknowledge receipt. See examples below.
371
372### Summary
373The host starts with a Query packet, then an Initialization packet, after
374which only Fastboot packets are sent. Fastboot packets may contain data from
375the host for writes, or from the device for reads, but not both.
376
377Given a next expected sequence number S and a received packet P, the device
378behavior should be:
379
380 if P is a Query packet:
381 * respond with a Query packet with S in the data field
382 else if P has sequence == S:
383 * process P and take any required action
384 * create a response packet R with the same ID and sequence as P, containing
385 any response data required.
386 * transmit R and save it in case of re-transmission
387 * increment S
388 else if P has sequence == S - 1:
389 * re-transmit the saved response packet R from above
390 else:
391 * ignore the packet
392
393### Examples
394
395In the examples below, S indicates the starting client sequence number.
396
397 Host Client
398 ======================================================================
399 [Initialization, S = 0x55AA]
400 [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.]
401 [Resulting values to use: version = 1, max packet size = 1024]
402 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data
403 ----------------------------------------------------------------------
404 0x01 0x00 0x00 0x00
405 0x01 0x00 0x00 0x00 0x55 0xAA
406 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00
407 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00
408
409 ----------------------------------------------------------------------
410 [fastboot "getvar" commands, S = 0x0001]
411 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
412 ----------------------------------------------------------------------
413 0x03 0x00 0x00 0x01 getvar:version
414 0x03 0x00 0x00 0x01
415 0x03 0x00 0x00 0x02
416 0x03 0x00 0x00 0x02 OKAY0.4
417 0x03 0x00 0x00 0x03 getvar:none
418 0x03 0x00 0x00 0x03
419 0x03 0x00 0x00 0x04
420 0x03 0x00 0x00 0x04 FAILUnknown var
421
422 ----------------------------------------------------------------------
423 [fastboot "INFO" responses, S = 0x0000]
424 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
425 ----------------------------------------------------------------------
426 0x03 0x00 0x00 0x00 <command>
427 0x03 0x00 0x00 0x00
428 0x03 0x00 0x00 0x01
429 0x03 0x00 0x00 0x01 INFOWait1
430 0x03 0x00 0x00 0x02
431 0x03 0x00 0x00 0x02 INFOWait2
432 0x03 0x00 0x00 0x03
433 0x03 0x00 0x00 0x03 OKAY
434
435 ----------------------------------------------------------------------
436 [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF]
437 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data
438 ----------------------------------------------------------------------
439 0x03 0x00 0xFF 0xFF download:0000834
440 0x03 0x00 0xFF 0xFF
441 0x03 0x00 0x00 0x00
442 0x03 0x00 0x00 0x00 DATA0000834
443 0x03 0x01 0x00 0x01 <1020 bytes>
444 0x03 0x00 0x00 0x01
445 0x03 0x01 0x00 0x02 <1020 bytes>
446 0x03 0x00 0x00 0x02
447 0x03 0x00 0x00 0x03 <60 bytes>
448 0x03 0x00 0x00 0x03
449 0x03 0x00 0x00 0x04
450 0x03 0x00 0x00 0x04 OKAY
451
452 ----------------------------------------------------------------------
453 [Unknown ID error, S = 0x0000]
454 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
455 ----------------------------------------------------------------------
456 0x10 0x00 0x00 0x00
457 0x00 0x00 0x00 0x00 <error message>
458
459 ----------------------------------------------------------------------
460 [Host packet loss and retransmission, S = 0x0000]
461 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
462 ----------------------------------------------------------------------
463 0x03 0x00 0x00 0x00 getvar:version [lost]
464 0x03 0x00 0x00 0x00 getvar:version [lost]
465 0x03 0x00 0x00 0x00 getvar:version
466 0x03 0x00 0x00 0x00
467 0x03 0x00 0x00 0x01
468 0x03 0x00 0x00 0x01 OKAY0.4
469
470 ----------------------------------------------------------------------
471 [Client packet loss and retransmission, S = 0x0000]
472 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
473 ----------------------------------------------------------------------
474 0x03 0x00 0x00 0x00 getvar:version
475 0x03 0x00 0x00 0x00 [lost]
476 0x03 0x00 0x00 0x00 getvar:version
477 0x03 0x00 0x00 0x00 [lost]
478 0x03 0x00 0x00 0x00 getvar:version
479 0x03 0x00 0x00 0x00
480 0x03 0x00 0x00 0x01
481 0x03 0x00 0x00 0x01 OKAY0.4
482
483 ----------------------------------------------------------------------
484 [Host packet delayed, S = 0x0000]
485 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
486 ----------------------------------------------------------------------
487 0x03 0x00 0x00 0x00 getvar:version [delayed]
488 0x03 0x00 0x00 0x00 getvar:version
489 0x03 0x00 0x00 0x00
490 0x03 0x00 0x00 0x01
491 0x03 0x00 0x00 0x01 OKAY0.4
492 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored]
493