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 4096 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## Flashing Logic 169 170Fastboot binary will follow directions listed out fastboot-info.txt 171build artifact for fastboot flashall && fastboot update comamnds. 172This build artifact will live inside of ANDROID_PRODUCT_OUT && 173target_files_package && updatepackage. 174 175 176The currently defined commands are: 177 178 flash %s Flash a given partition. Optional arguments include 179 --slot-other, {filename_path}, --apply-vbmeta 180 181 reboot %s Reboot to either bootloader or fastbootd 182 183 update-super Updates the super partition 184 185 if-wipe Conditionally run some other functionality if 186 wipe is specified 187 188 erase %s Erase a given partition (can only be used in conjunction) 189 with if-wipe -> eg. if-wipe erase cache 190 191Flashing Optimization: 192 193 After generating the list of tasks to execute, Fastboot will try and 194 optimize the flashing of the dynamic partitions by constructing an 195 optimized flash super task. Fastboot will explicitly pattern match the 196 following commands and try and concatenate it into this task. (doing so 197 will allow us to avoid the reboot into userspace fastbootd which takes 198 significant time) 199 200 //Optimizable Block 201 reboot fastboot 202 update-super ---> generate optimized flash super task 203 $FOR EACH {dynamic partition} 204 flash {dynamic partition} 205 206## Client Variables 207 208The "getvar:%s" command is used to read client variables which 209represent various information about the device and the software 210on it. 211 212The various currently defined names are: 213 214 version Version of FastBoot protocol supported. 215 It should be "0.4" for this document. 216 217 version-bootloader Version string for the Bootloader. 218 219 version-baseband Version string of the Baseband Software 220 221 product Name of the product 222 223 serialno Product serial number 224 225 secure If the value is "yes", this is a secure 226 bootloader requiring a signature before 227 it will install or boot images. 228 229 is-userspace If the value is "yes", the device is running 230 fastbootd. Otherwise, it is running fastboot 231 in the bootloader. 232 233Names starting with a lowercase character are reserved by this 234specification. OEM-specific names should not start with lowercase 235characters. 236 237## Logical Partitions 238 239There are a number of commands to interact with logical partitions: 240 241 update-super:%s:%s Write the previously downloaded image to a super 242 partition. Unlike the "flash" command, this has 243 special rules. The image must have been created by 244 the lpmake command, and must not be a sparse image. 245 If the last argument is "wipe", then all existing 246 logical partitions are deleted. If no final argument 247 is specified, the partition tables are merged. Any 248 partition in the new image that does not exist in the 249 old image is created with a zero size. 250 251 In all cases, this will cause the temporary "scratch" 252 partition to be deleted if it exists. 253 254 create-logical-partition:%s:%d 255 Create a logical partition with the given name and 256 size, in the super partition. 257 258 delete-logical-partition:%s 259 Delete a logical partition with the given name. 260 261 resize-logical-partition:%s:%d 262 Change the size of the named logical partition. 263 264In addition, there is a variable to test whether a partition is logical: 265 266 is-logical:%s If the value is "yes", the partition is logical. 267 Otherwise the partition is physical. 268 269## TCP Protocol v1 270 271The TCP protocol is designed to be a simple way to use the fastboot protocol 272over ethernet if USB is not available. 273 274The device will open a TCP server on port 5554 and wait for a fastboot client 275to connect. 276 277### Handshake 278Upon connecting, both sides will send a 4-byte handshake message to ensure they 279are speaking the same protocol. This consists of the ASCII characters "FB" 280followed by a 2-digit base-10 ASCII version number. For example, the version 1 281handshake message will be [FB01]. 282 283If either side detects a malformed handshake, it should disconnect. 284 285The protocol version to use must be the minimum of the versions sent by each 286side; if either side cannot speak this protocol version, it should disconnect. 287 288### Fastboot Data 289Once the handshake is complete, fastboot data will be sent as follows: 290 291 [data_size][data] 292 293Where data\_size is an unsigned 8-byte big-endian binary value, and data is the 294fastboot packet. The 8-byte length is intended to provide future-proofing even 295though currently fastboot packets have a 4-byte maximum length. 296 297### Example 298In this example the fastboot host queries the device for two variables, 299"version" and "none". 300 301 Host <connect to the device on port 5555> 302 Host FB01 303 Device FB01 304 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version 305 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4 306 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none 307 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable 308 Host <disconnect> 309 310 311## UDP Protocol v1 312 313The UDP protocol is more complex than TCP since we must implement reliability 314to ensure no packets are lost, but the general concept of wrapping the fastboot 315protocol is the same. 316 317Overview: 318 1. As with TCP, the device will listen on UDP port 5554. 319 2. Maximum UDP packet size is negotiated during initialization. 320 3. The host drives all communication; the device may only send a packet as a 321 response to a host packet. 322 4. If the host does not receive a response in 500ms it will re-transmit. 323 324### UDP Packet format 325 326 +----------+----+-------+-------+--------------------+ 327 | Byte # | 0 | 1 | 2 - 3 | 4+ | 328 +----------+----+-------+-------+--------------------+ 329 | Contents | ID | Flags | Seq # | Data | 330 +----------+----+-------+-------+--------------------+ 331 332 ID Packet ID: 333 0x00: Error. 334 0x01: Query. 335 0x02: Initialization. 336 0x03: Fastboot. 337 338 Packet types are described in more detail below. 339 340 Flags Packet flags: 0 0 0 0 0 0 0 C 341 C=1 indicates a continuation packet; the data is too large and will 342 continue in the next packet. 343 344 Remaining bits are reserved for future use and must be set to 0. 345 346 Seq # 2-byte packet sequence number (big-endian). The host will increment 347 this by 1 with each new packet, and the device must provide the 348 corresponding sequence number in the response packets. 349 350 Data Packet data, not present in all packets. 351 352### Packet Types 353 354 Query 355 The host sends a query packet once on startup to sync with the device. 356 The host will not know the current sequence number, so the device must 357 respond to all query packets regardless of sequence number. 358 359 The response data field should contain a 2-byte big-endian value 360 giving the next expected sequence number. 361 362 Init 363 The host sends an init packet once the query response is returned. The 364 device must abort any in-progress operation and prepare for a new 365 fastboot session. This message is meant to allow recovery if a 366 previous session failed, e.g. due to network error or user Ctrl+C. 367 368 The data field contains two big-endian 2-byte values, a protocol 369 version and the max UDP packet size (including the 4-byte header). 370 Both the host and device will send these values, and in each case 371 the minimum of the sent values must be used. 372 373 Fastboot 374 These packets wrap the fastboot protocol. To write, the host will 375 send a packet with fastboot data, and the device will reply with an 376 empty packet as an ACK. To read, the host will send an empty packet, 377 and the device will reply with fastboot data. The device may not give 378 any data in the ACK packet. 379 380 Error 381 The device may respond to any packet with an error packet to indicate 382 a UDP protocol error. The data field should contain an ASCII string 383 describing the error. This is the only case where a device is allowed 384 to return a packet ID other than the one sent by the host. 385 386### Packet Size 387The maximum packet size is negotiated by the host and device in the Init packet. 388Devices must support at least 512-byte packets, but packet size has a direct 389correlation with download speed, so devices are strongly suggested to support at 390least 1024-byte packets. On a local network with 0.5ms round-trip time this will 391provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly 392less. 393 394Query and Initialization packets, which are sent before size negotiation is 395complete, must always be 512 bytes or less. 396 397### Packet Re-Transmission 398The host will re-transmit any packet that does not receive a response. The 399requirement of exactly one device response packet per host packet is how we 400achieve reliability and in-order delivery of packets. 401 402For simplicity of implementation, there is no windowing of multiple 403unacknowledged packets in this version of the protocol. The host will continue 404to send the same packet until a response is received. Windowing functionality 405may be implemented in future versions if necessary to increase performance. 406 407The first Query packet will only be attempted a small number of times, but 408subsequent packets will attempt to retransmit for at least 1 minute before 409giving up. This means a device may safely ignore host UDP packets for up to 1 410minute during long operations, e.g. writing to flash. 411 412### Continuation Packets 413Any packet may set the continuation flag to indicate that the data is 414incomplete. Large data such as downloading an image may require many 415continuation packets. The receiver should respond to a continuation packet with 416an empty packet to acknowledge receipt. See examples below. 417 418### Summary 419The host starts with a Query packet, then an Initialization packet, after 420which only Fastboot packets are sent. Fastboot packets may contain data from 421the host for writes, or from the device for reads, but not both. 422 423Given a next expected sequence number S and a received packet P, the device 424behavior should be: 425 426 if P is a Query packet: 427 * respond with a Query packet with S in the data field 428 else if P has sequence == S: 429 * process P and take any required action 430 * create a response packet R with the same ID and sequence as P, containing 431 any response data required. 432 * transmit R and save it in case of re-transmission 433 * increment S 434 else if P has sequence == S - 1: 435 * re-transmit the saved response packet R from above 436 else: 437 * ignore the packet 438 439### Examples 440 441In the examples below, S indicates the starting client sequence number. 442 443 Host Client 444 ====================================================================== 445 [Initialization, S = 0x55AA] 446 [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.] 447 [Resulting values to use: version = 1, max packet size = 1024] 448 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 449 ---------------------------------------------------------------------- 450 0x01 0x00 0x00 0x00 451 0x01 0x00 0x00 0x00 0x55 0xAA 452 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00 453 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00 454 455 ---------------------------------------------------------------------- 456 [fastboot "getvar" commands, S = 0x0001] 457 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 458 ---------------------------------------------------------------------- 459 0x03 0x00 0x00 0x01 getvar:version 460 0x03 0x00 0x00 0x01 461 0x03 0x00 0x00 0x02 462 0x03 0x00 0x00 0x02 OKAY0.4 463 0x03 0x00 0x00 0x03 getvar:none 464 0x03 0x00 0x00 0x03 465 0x03 0x00 0x00 0x04 466 0x03 0x00 0x00 0x04 FAILUnknown var 467 468 ---------------------------------------------------------------------- 469 [fastboot "INFO" responses, S = 0x0000] 470 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 471 ---------------------------------------------------------------------- 472 0x03 0x00 0x00 0x00 <command> 473 0x03 0x00 0x00 0x00 474 0x03 0x00 0x00 0x01 475 0x03 0x00 0x00 0x01 INFOWait1 476 0x03 0x00 0x00 0x02 477 0x03 0x00 0x00 0x02 INFOWait2 478 0x03 0x00 0x00 0x03 479 0x03 0x00 0x00 0x03 OKAY 480 481 ---------------------------------------------------------------------- 482 [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF] 483 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 484 ---------------------------------------------------------------------- 485 0x03 0x00 0xFF 0xFF download:0000834 486 0x03 0x00 0xFF 0xFF 487 0x03 0x00 0x00 0x00 488 0x03 0x00 0x00 0x00 DATA0000834 489 0x03 0x01 0x00 0x01 <1020 bytes> 490 0x03 0x00 0x00 0x01 491 0x03 0x01 0x00 0x02 <1020 bytes> 492 0x03 0x00 0x00 0x02 493 0x03 0x00 0x00 0x03 <60 bytes> 494 0x03 0x00 0x00 0x03 495 0x03 0x00 0x00 0x04 496 0x03 0x00 0x00 0x04 OKAY 497 498 ---------------------------------------------------------------------- 499 [Unknown ID error, S = 0x0000] 500 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 501 ---------------------------------------------------------------------- 502 0x10 0x00 0x00 0x00 503 0x00 0x00 0x00 0x00 <error message> 504 505 ---------------------------------------------------------------------- 506 [Host packet loss and retransmission, S = 0x0000] 507 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 508 ---------------------------------------------------------------------- 509 0x03 0x00 0x00 0x00 getvar:version [lost] 510 0x03 0x00 0x00 0x00 getvar:version [lost] 511 0x03 0x00 0x00 0x00 getvar:version 512 0x03 0x00 0x00 0x00 513 0x03 0x00 0x00 0x01 514 0x03 0x00 0x00 0x01 OKAY0.4 515 516 ---------------------------------------------------------------------- 517 [Client packet loss and retransmission, S = 0x0000] 518 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 519 ---------------------------------------------------------------------- 520 0x03 0x00 0x00 0x00 getvar:version 521 0x03 0x00 0x00 0x00 [lost] 522 0x03 0x00 0x00 0x00 getvar:version 523 0x03 0x00 0x00 0x00 [lost] 524 0x03 0x00 0x00 0x00 getvar:version 525 0x03 0x00 0x00 0x00 526 0x03 0x00 0x00 0x01 527 0x03 0x00 0x00 0x01 OKAY0.4 528 529 ---------------------------------------------------------------------- 530 [Host packet delayed, S = 0x0000] 531 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 532 ---------------------------------------------------------------------- 533 0x03 0x00 0x00 0x00 getvar:version [delayed] 534 0x03 0x00 0x00 0x00 getvar:version 535 0x03 0x00 0x00 0x00 536 0x03 0x00 0x00 0x01 537 0x03 0x00 0x00 0x01 OKAY0.4 538 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored] 539