Gitiles
Code Review Sign In
gerrit.witaqua.org / system_core / 84cb36e02d61c63183843b3f08d13396cc44bc71 / . / fastboot / README.md
blob: 022d34b91f93490e1f8472a28175525c6185dda2 [file] [log] [blame] [view]
Elliott Hughes84cb36e2017-01-13 15:52:44 -0800[diff] [blame^]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 verify:%08x Send a digital signature to verify the downloaded
130 data. Required if the bootloader is "secure"
131 otherwise "flash" and "boot" will be ignored.
132
133 flash:%s Write the previously downloaded image to the
134 named partition (if possible).
135
136 erase:%s Erase the indicated partition (clear to 0xFFs)
137
138 boot The previously downloaded data is a boot.img
139 and should be booted according to the normal
140 procedure for a boot.img
141
142 continue Continue booting as normal (if possible)
143
144 reboot Reboot the device.
145
146 reboot-bootloader
147 Reboot back into the bootloader.
148 Useful for upgrade processes that require upgrading
149 the bootloader and then upgrading other partitions
150 using the new bootloader.
151
152 powerdown Power off the device.
153
154
155
156## Client Variables
157
158The "getvar:%s" command is used to read client variables which
159represent various information about the device and the software
160on it.
161
162The various currently defined names are:
163
164 version Version of FastBoot protocol supported.
165 It should be "0.4" for this document.
166
167 version-bootloader Version string for the Bootloader.
168
169 version-baseband Version string of the Baseband Software
170
171 product Name of the product
172
173 serialno Product serial number
174
175 secure If the value is "yes", this is a secure
176 bootloader requiring a signature before
177 it will install or boot images.
178
179Names starting with a lowercase character are reserved by this
180specification. OEM-specific names should not start with lowercase
181characters.
182
183
184## TCP Protocol v1
185
186The TCP protocol is designed to be a simple way to use the fastboot protocol
187over ethernet if USB is not available.
188
189The device will open a TCP server on port 5554 and wait for a fastboot client
190to connect.
191
192### Handshake
193Upon connecting, both sides will send a 4-byte handshake message to ensure they
194are speaking the same protocol. This consists of the ASCII characters "FB"
195followed by a 2-digit base-10 ASCII version number. For example, the version 1
196handshake message will be [FB01].
197
198If either side detects a malformed handshake, it should disconnect.
199
200The protocol version to use must be the minimum of the versions sent by each
201side; if either side cannot speak this protocol version, it should disconnect.
202
203### Fastboot Data
204Once the handshake is complete, fastboot data will be sent as follows:
205
206 [data_size][data]
207
208Where data\_size is an unsigned 8-byte big-endian binary value, and data is the
209fastboot packet. The 8-byte length is intended to provide future-proofing even
210though currently fastboot packets have a 4-byte maximum length.
211
212### Example
213In this example the fastboot host queries the device for two variables,
214"version" and "none".
215
216 Host <connect to the device on port 5555>
217 Host FB01
218 Device FB01
219 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version
220 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
221 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
222 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable
223 Host <disconnect>
224
225
226## UDP Protocol v1
227
228The UDP protocol is more complex than TCP since we must implement reliability
229to ensure no packets are lost, but the general concept of wrapping the fastboot
230protocol is the same.
231
232Overview:
233 1. As with TCP, the device will listen on UDP port 5554.
234 2. Maximum UDP packet size is negotiated during initialization.
235 3. The host drives all communication; the device may only send a packet as a
236 response to a host packet.
237 4. If the host does not receive a response in 500ms it will re-transmit.
238
239### UDP Packet format
240
241 +----------+----+-------+-------+--------------------+
242 | Byte # | 0 | 1 | 2 - 3 | 4+ |
243 +----------+----+-------+-------+--------------------+
244 | Contents | ID | Flags | Seq # | Data |
245 +----------+----+-------+-------+--------------------+
246
247 ID Packet ID:
248 0x00: Error.
249 0x01: Query.
250 0x02: Initialization.
251 0x03: Fastboot.
252
253 Packet types are described in more detail below.
254
255 Flags Packet flags: 0 0 0 0 0 0 0 C
256 C=1 indicates a continuation packet; the data is too large and will
257 continue in the next packet.
258
259 Remaining bits are reserved for future use and must be set to 0.
260
261 Seq # 2-byte packet sequence number (big-endian). The host will increment
262 this by 1 with each new packet, and the device must provide the
263 corresponding sequence number in the response packets.
264
265 Data Packet data, not present in all packets.
266
267### Packet Types
268
269 Query
270 The host sends a query packet once on startup to sync with the device.
271 The host will not know the current sequence number, so the device must
272 respond to all query packets regardless of sequence number.
273
274 The response data field should contain a 2-byte big-endian value
275 giving the next expected sequence number.
276
277 Init
278 The host sends an init packet once the query response is returned. The
279 device must abort any in-progress operation and prepare for a new
280 fastboot session. This message is meant to allow recovery if a
281 previous session failed, e.g. due to network error or user Ctrl+C.
282
283 The data field contains two big-endian 2-byte values, a protocol
284 version and the max UDP packet size (including the 4-byte header).
285 Both the host and device will send these values, and in each case
286 the minimum of the sent values must be used.
287
288 Fastboot
289 These packets wrap the fastboot protocol. To write, the host will
290 send a packet with fastboot data, and the device will reply with an
291 empty packet as an ACK. To read, the host will send an empty packet,
292 and the device will reply with fastboot data. The device may not give
293 any data in the ACK packet.
294
295 Error
296 The device may respond to any packet with an error packet to indicate
297 a UDP protocol error. The data field should contain an ASCII string
298 describing the error. This is the only case where a device is allowed
299 to return a packet ID other than the one sent by the host.
300
301### Packet Size
302The maximum packet size is negotiated by the host and device in the Init packet.
303Devices must support at least 512-byte packets, but packet size has a direct
304correlation with download speed, so devices are strongly suggested to support at
305least 1024-byte packets. On a local network with 0.5ms round-trip time this will
306provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly
307less.
308
309Query and Initialization packets, which are sent before size negotiation is
310complete, must always be 512 bytes or less.
311
312### Packet Re-Transmission
313The host will re-transmit any packet that does not receive a response. The
314requirement of exactly one device response packet per host packet is how we
315achieve reliability and in-order delivery of packets.
316
317For simplicity of implementation, there is no windowing of multiple
318unacknowledged packets in this version of the protocol. The host will continue
319to send the same packet until a response is received. Windowing functionality
320may be implemented in future versions if necessary to increase performance.
321
322The first Query packet will only be attempted a small number of times, but
323subsequent packets will attempt to retransmit for at least 1 minute before
324giving up. This means a device may safely ignore host UDP packets for up to 1
325minute during long operations, e.g. writing to flash.
326
327### Continuation Packets
328Any packet may set the continuation flag to indicate that the data is
329incomplete. Large data such as downloading an image may require many
330continuation packets. The receiver should respond to a continuation packet with
331an empty packet to acknowledge receipt. See examples below.
332
333### Summary
334The host starts with a Query packet, then an Initialization packet, after
335which only Fastboot packets are sent. Fastboot packets may contain data from
336the host for writes, or from the device for reads, but not both.
337
338Given a next expected sequence number S and a received packet P, the device
339behavior should be:
340
341 if P is a Query packet:
342 * respond with a Query packet with S in the data field
343 else if P has sequence == S:
344 * process P and take any required action
345 * create a response packet R with the same ID and sequence as P, containing
346 any response data required.
347 * transmit R and save it in case of re-transmission
348 * increment S
349 else if P has sequence == S - 1:
350 * re-transmit the saved response packet R from above
351 else:
352 * ignore the packet
353
354### Examples
355
356In the examples below, S indicates the starting client sequence number.
357
358 Host Client
359 ======================================================================
360 [Initialization, S = 0x55AA]
361 [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.]
362 [Resulting values to use: version = 1, max packet size = 1024]
363 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data
364 ----------------------------------------------------------------------
365 0x01 0x00 0x00 0x00
366 0x01 0x00 0x00 0x00 0x55 0xAA
367 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00
368 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00
369
370 ----------------------------------------------------------------------
371 [fastboot "getvar" commands, S = 0x0001]
372 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
373 ----------------------------------------------------------------------
374 0x03 0x00 0x00 0x01 getvar:version
375 0x03 0x00 0x00 0x01
376 0x03 0x00 0x00 0x02
377 0x03 0x00 0x00 0x02 OKAY0.4
378 0x03 0x00 0x00 0x03 getvar:none
379 0x03 0x00 0x00 0x03
380 0x03 0x00 0x00 0x04
381 0x03 0x00 0x00 0x04 FAILUnknown var
382
383 ----------------------------------------------------------------------
384 [fastboot "INFO" responses, S = 0x0000]
385 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
386 ----------------------------------------------------------------------
387 0x03 0x00 0x00 0x00 <command>
388 0x03 0x00 0x00 0x00
389 0x03 0x00 0x00 0x01
390 0x03 0x00 0x00 0x01 INFOWait1
391 0x03 0x00 0x00 0x02
392 0x03 0x00 0x00 0x02 INFOWait2
393 0x03 0x00 0x00 0x03
394 0x03 0x00 0x00 0x03 OKAY
395
396 ----------------------------------------------------------------------
397 [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF]
398 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data
399 ----------------------------------------------------------------------
400 0x03 0x00 0xFF 0xFF download:0000834
401 0x03 0x00 0xFF 0xFF
402 0x03 0x00 0x00 0x00
403 0x03 0x00 0x00 0x00 DATA0000834
404 0x03 0x01 0x00 0x01 <1020 bytes>
405 0x03 0x00 0x00 0x01
406 0x03 0x01 0x00 0x02 <1020 bytes>
407 0x03 0x00 0x00 0x02
408 0x03 0x00 0x00 0x03 <60 bytes>
409 0x03 0x00 0x00 0x03
410 0x03 0x00 0x00 0x04
411 0x03 0x00 0x00 0x04 OKAY
412
413 ----------------------------------------------------------------------
414 [Unknown ID error, S = 0x0000]
415 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
416 ----------------------------------------------------------------------
417 0x10 0x00 0x00 0x00
418 0x00 0x00 0x00 0x00 <error message>
419
420 ----------------------------------------------------------------------
421 [Host packet loss and retransmission, S = 0x0000]
422 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
423 ----------------------------------------------------------------------
424 0x03 0x00 0x00 0x00 getvar:version [lost]
425 0x03 0x00 0x00 0x00 getvar:version [lost]
426 0x03 0x00 0x00 0x00 getvar:version
427 0x03 0x00 0x00 0x00
428 0x03 0x00 0x00 0x01
429 0x03 0x00 0x00 0x01 OKAY0.4
430
431 ----------------------------------------------------------------------
432 [Client packet loss and retransmission, S = 0x0000]
433 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
434 ----------------------------------------------------------------------
435 0x03 0x00 0x00 0x00 getvar:version
436 0x03 0x00 0x00 0x00 [lost]
437 0x03 0x00 0x00 0x00 getvar:version
438 0x03 0x00 0x00 0x00 [lost]
439 0x03 0x00 0x00 0x00 getvar:version
440 0x03 0x00 0x00 0x00
441 0x03 0x00 0x00 0x01
442 0x03 0x00 0x00 0x01 OKAY0.4
443
444 ----------------------------------------------------------------------
445 [Host packet delayed, S = 0x0000]
446 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data
447 ----------------------------------------------------------------------
448 0x03 0x00 0x00 0x00 getvar:version [delayed]
449 0x03 0x00 0x00 0x00 getvar:version
450 0x03 0x00 0x00 0x00
451 0x03 0x00 0x00 0x01
452 0x03 0x00 0x00 0x01 OKAY0.4
453 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored]