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