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