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] 454