• Home
Name
Date
Size
#Lines
LOC

..--

.clang-formatD03-May-2024251 1211

Android.mkD03-May-20243.9 KiB13688

README.mdD03-May-202419.6 KiB464350

bootimg_utils.cppD03-May-20243 KiB7837

bootimg_utils.hD03-May-20241.9 KiB4412

engine.cppD03-May-202411.3 KiB417318

fastboot.cppD03-May-202467.5 KiB1,8891,561

fastboot.hD03-May-20243.4 KiB8441

fs.cppD03-May-20246.6 KiB203171

fs.hD03-May-2024366 149

protocol.cppD03-May-202410.3 KiB359271

socket.cppD03-May-20249.3 KiB291194

socket.hD03-May-20245.7 KiB13039

socket_mock.cppD03-May-20244.9 KiB15295

socket_mock.hD03-May-20243.5 KiB10236

socket_test.cppD03-May-202413.7 KiB386259

tcp.cppD03-May-20246.5 KiB200126

tcp.hD03-May-20242.2 KiB6015

tcp_test.cppD03-May-20247.4 KiB228147

transport.hD03-May-20241.5 KiB4915

udp.cppD03-May-202413.7 KiB392257

udp.hD03-May-20242.8 KiB8229

udp_test.cppD03-May-202420.6 KiB532362

usb.hD03-May-20242 KiB6121

usb_linux.cppD03-May-202414.3 KiB499344

usb_osx.cppD03-May-202416.6 KiB575367

usb_windows.cppD03-May-202411.2 KiB365238

usbtest.cppD03-May-20245.8 KiB213159

util.cppD03-May-20242 KiB7034

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