1 FastBoot Version 0.4 2 ---------------------- 3 4 The fastboot protocol is a mechanism for communicating with bootloaders 5 over USB or ethernet. It is designed to be very straightforward to implement, 6 to allow it to be used across a wide range of devices and from hosts running 7 Linux, Windows, or OSX. 8 9 10 Basic Requirements 11 ------------------ 12 13 * USB 14 * Two bulk endpoints (in, out) are required 15 * Max packet size must be 64 bytes for full-speed, 512 bytes for 16 high-speed and 1024 bytes for Super Speed USB. 17 * The protocol is entirely host-driven and synchronous (unlike the 18 multi-channel, bi-directional, asynchronous ADB protocol) 19 20 * TCP or UDP 21 * Device must be reachable via IP. 22 * Device will act as the server, fastboot will be the client. 23 * Fastboot data is wrapped in a simple protocol; see below for details. 24 25 26 Transport and Framing 27 --------------------- 28 29 1. Host sends a command, which is an ascii string in a single 30 packet no greater than 64 bytes. 31 32 2. Client response with a single packet no greater than 64 bytes. 33 The first four bytes of the response are "OKAY", "FAIL", "DATA", 34 or "INFO". Additional bytes may contain an (ascii) informative 35 message. 36 37 a. INFO -> the remaining 60 bytes are an informative message 38 (providing progress or diagnostic messages). They should 39 be displayed and then step #2 repeats 40 41 b. FAIL -> the requested command failed. The remaining 60 bytes 42 of the response (if present) provide a textual failure message 43 to present to the user. Stop. 44 45 c. OKAY -> the requested command completed successfully. Go to #5 46 47 d. DATA -> the requested command is ready for the data phase. 48 A DATA response packet will be 12 bytes long, in the form of 49 DATA00000000 where the 8 digit hexadecimal number represents 50 the total data size to transfer. 51 52 3. Data phase. Depending on the command, the host or client will 53 send the indicated amount of data. Short packets are always 54 acceptable and zero-length packets are ignored. This phase continues 55 until the client has sent or received the number of bytes indicated 56 in the "DATA" response above. 57 58 4. Client responds with a single packet no greater than 64 bytes. 59 The first four bytes of the response are "OKAY", "FAIL", or "INFO". 60 Similar to #2: 61 62 a. INFO -> display the remaining 60 bytes and return to #4 63 64 b. FAIL -> display the remaining 60 bytes (if present) as a failure 65 reason and consider the command failed. Stop. 66 67 c. OKAY -> success. Go to #5 68 69 5. Success. Stop. 70 71 72 Example Session 73 --------------- 74 75 Host: "getvar:version" request version variable 76 77 Client: "OKAY0.4" return version "0.4" 78 79 Host: "getvar:nonexistant" request some undefined variable 80 81 Client: "OKAY" return value "" 82 83 Host: "download:00001234" request to send 0x1234 bytes of data 84 85 Client: "DATA00001234" ready to accept data 86 87 Host: < 0x1234 bytes > send data 88 89 Client: "OKAY" success 90 91 Host: "flash:bootloader" request to flash the data to the bootloader 92 93 Client: "INFOerasing flash" indicate status / progress 94 "INFOwriting flash" 95 "OKAY" indicate success 96 97 Host: "powerdown" send a command 98 99 Client: "FAILunknown command" indicate failure 100 101 102 Command Reference 103 ----------------- 104 105 * Command parameters are indicated by printf-style escape sequences. 106 107 * Commands are ascii strings and sent without the quotes (which are 108 for illustration only here) and without a trailing 0 byte. 109 110 * Commands that begin with a lowercase letter are reserved for this 111 specification. OEM-specific commands should not begin with a 112 lowercase letter, to prevent incompatibilities with future specs. 113 114 "getvar:%s" Read a config/version variable from the bootloader. 115 The variable contents will be returned after the 116 OKAY response. 117 118 "download:%08x" Write data to memory which will be later used 119 by "boot", "ramdisk", "flash", etc. The client 120 will reply with "DATA%08x" if it has enough 121 space in RAM or "FAIL" if not. The size of 122 the download is remembered. 123 124 "verify:%08x" Send a digital signature to verify the downloaded 125 data. Required if the bootloader is "secure" 126 otherwise "flash" and "boot" will be ignored. 127 128 "flash:%s" Write the previously downloaded image to the 129 named partition (if possible). 130 131 "erase:%s" Erase the indicated partition (clear to 0xFFs) 132 133 "boot" The previously downloaded data is a boot.img 134 and should be booted according to the normal 135 procedure for a boot.img 136 137 "continue" Continue booting as normal (if possible) 138 139 "reboot" Reboot the device. 140 141 "reboot-bootloader" Reboot back into the bootloader. 142 Useful for upgrade processes that require upgrading 143 the bootloader and then upgrading other partitions 144 using the new bootloader. 145 146 "powerdown" Power off the device. 147 148 149 150 Client Variables 151 ---------------- 152 153 The "getvar:%s" command is used to read client variables which 154 represent various information about the device and the software 155 on it. 156 157 The various currently defined names are: 158 159 version Version of FastBoot protocol supported. 160 It should be "0.4" for this document. 161 162 version-bootloader Version string for the Bootloader. 163 164 version-baseband Version string of the Baseband Software 165 166 product Name of the product 167 168 serialno Product serial number 169 170 secure If the value is "yes", this is a secure 171 bootloader requiring a signature before 172 it will install or boot images. 173 174 Names starting with a lowercase character are reserved by this 175 specification. OEM-specific names should not start with lowercase 176 characters. 177 178 179 TCP Protocol v1 180 --------------- 181 182 The TCP protocol is designed to be a simple way to use the fastboot protocol 183 over ethernet if USB is not available. 184 185 The device will open a TCP server on port 5554 and wait for a fastboot client 186 to connect. 187 188 -- Handshake -- 189 Upon connecting, both sides will send a 4-byte handshake message to ensure they 190 are speaking the same protocol. This consists of the ASCII characters "FB" 191 followed by a 2-digit base-10 ASCII version number. For example, the version 1 192 handshake message will be [FB01]. 193 194 If either side detects a malformed handshake, it should disconnect. 195 196 The protocol version to use must be the minimum of the versions sent by each 197 side; if either side cannot speak this protocol version, it should disconnect. 198 199 -- Fastboot Data -- 200 Once the handshake is complete, fastboot data will be sent as follows: 201 202 [data_size][data] 203 204 Where data_size is an unsigned 8-byte big-endian binary value, and data is the 205 fastboot packet. The 8-byte length is intended to provide future-proofing even 206 though currently fastboot packets have a 4-byte maximum length. 207 208 -- Example -- 209 In this example the fastboot host queries the device for two variables, 210 "version" and "none". 211 212 Host <connect to the device on port 5555> 213 Host FB01 214 Device FB01 215 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version 216 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4 217 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none 218 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x04]OKAY 219 Host <disconnect> 220 221 222 UDP Protocol v1 223 --------------- 224 225 The UDP protocol is more complex than TCP since we must implement reliability 226 to ensure no packets are lost, but the general concept of wrapping the fastboot 227 protocol is the same. 228 229 Overview: 230 1. As with TCP, the device will listen on UDP port 5554. 231 2. Maximum UDP packet size is negotiated during initialization. 232 3. The host drives all communication; the device may only send a packet as a 233 response to a host packet. 234 4. If the host does not receive a response in 500ms it will re-transmit. 235 236 -- UDP Packet format -- 237 +----------+----+-------+-------+--------------------+ 238 | Byte # | 0 | 1 | 2 - 3 | 4+ | 239 +----------+----+-------+-------+--------------------+ 240 | Contents | ID | Flags | Seq # | Data | 241 +----------+----+-------+-------+--------------------+ 242 243 ID Packet ID: 244 0x00: Error. 245 0x01: Query. 246 0x02: Initialization. 247 0x03: Fastboot. 248 249 Packet types are described in more detail below. 250 251 Flags Packet flags: 0 0 0 0 0 0 0 C 252 C=1 indicates a continuation packet; the data is too large and will 253 continue in the next packet. 254 255 Remaining bits are reserved for future use and must be set to 0. 256 257 Seq # 2-byte packet sequence number (big-endian). The host will increment 258 this by 1 with each new packet, and the device must provide the 259 corresponding sequence number in the response packets. 260 261 Data Packet data, not present in all packets. 262 263 -- Packet Types -- 264 Query The host sends a query packet once on startup to sync with the device. 265 The host will not know the current sequence number, so the device must 266 respond to all query packets regardless of sequence number. 267 268 The response data field should contain a 2-byte big-endian value 269 giving the next expected sequence number. 270 271 Init The host sends an init packet once the query response is returned. The 272 device must abort any in-progress operation and prepare for a new 273 fastboot session. This message is meant to allow recovery if a 274 previous session failed, e.g. due to network error or user Ctrl+C. 275 276 The data field contains two big-endian 2-byte values, a protocol 277 version and the max UDP packet size (including the 4-byte header). 278 Both the host and device will send these values, and in each case 279 the minimum of the sent values must be used. 280 281 Fastboot These packets wrap the fastboot protocol. To write, the host will 282 send a packet with fastboot data, and the device will reply with an 283 empty packet as an ACK. To read, the host will send an empty packet, 284 and the device will reply with fastboot data. The device may not give 285 any data in the ACK packet. 286 287 Error The device may respond to any packet with an error packet to indicate 288 a UDP protocol error. The data field should contain an ASCII string 289 describing the error. This is the only case where a device is allowed 290 to return a packet ID other than the one sent by the host. 291 292 -- Packet Size -- 293 The maximum packet size is negotiated by the host and device in the Init packet. 294 Devices must support at least 512-byte packets, but packet size has a direct 295 correlation with download speed, so devices are strongly suggested to support at 296 least 1024-byte packets. On a local network with 0.5ms round-trip time this will 297 provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly 298 less. 299 300 Query and Initialization packets, which are sent before size negotiation is 301 complete, must always be 512 bytes or less. 302 303 -- Packet Re-Transmission -- 304 The host will re-transmit any packet that does not receive a response. The 305 requirement of exactly one device response packet per host packet is how we 306 achieve reliability and in-order delivery of packets. 307 308 For simplicity of implementation, there is no windowing of multiple 309 unacknowledged packets in this version of the protocol. The host will continue 310 to send the same packet until a response is received. Windowing functionality 311 may be implemented in future versions if necessary to increase performance. 312 313 The first Query packet will only be attempted a small number of times, but 314 subsequent packets will attempt to retransmit for at least 1 minute before 315 giving up. This means a device may safely ignore host UDP packets for up to 1 316 minute during long operations, e.g. writing to flash. 317 318 -- Continuation Packets -- 319 Any packet may set the continuation flag to indicate that the data is 320 incomplete. Large data such as downloading an image may require many 321 continuation packets. The receiver should respond to a continuation packet with 322 an empty packet to acknowledge receipt. See examples below. 323 324 -- Summary -- 325 The host starts with a Query packet, then an Initialization packet, after 326 which only Fastboot packets are sent. Fastboot packets may contain data from 327 the host for writes, or from the device for reads, but not both. 328 329 Given a next expected sequence number S and a received packet P, the device 330 behavior should be: 331 if P is a Query packet: 332 * respond with a Query packet with S in the data field 333 else if P has sequence == S: 334 * process P and take any required action 335 * create a response packet R with the same ID and sequence as P, containing 336 any response data required. 337 * transmit R and save it in case of re-transmission 338 * increment S 339 else if P has sequence == S - 1: 340 * re-transmit the saved response packet R from above 341 else: 342 * ignore the packet 343 344 -- Examples -- 345 In the examples below, S indicates the starting client sequence number. 346 347 Host Client 348 ====================================================================== 349 [Initialization, S = 0x55AA] 350 [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.] 351 [Resulting values to use: version = 1, max packet size = 1024] 352 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 353 ---------------------------------------------------------------------- 354 0x01 0x00 0x00 0x00 355 0x01 0x00 0x00 0x00 0x55 0xAA 356 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00 357 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00 358 359 ---------------------------------------------------------------------- 360 [fastboot "getvar" commands, S = 0x0001] 361 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 362 ---------------------------------------------------------------------- 363 0x03 0x00 0x00 0x01 getvar:version 364 0x03 0x00 0x00 0x01 365 0x03 0x00 0x00 0x02 366 0x03 0x00 0x00 0x02 OKAY0.4 367 0x03 0x00 0x00 0x03 getvar:foo 368 0x03 0x00 0x00 0x03 369 0x03 0x00 0x00 0x04 370 0x03 0x00 0x00 0x04 OKAY 371 372 ---------------------------------------------------------------------- 373 [fastboot "INFO" responses, S = 0x0000] 374 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 375 ---------------------------------------------------------------------- 376 0x03 0x00 0x00 0x00 <command> 377 0x03 0x00 0x00 0x00 378 0x03 0x00 0x00 0x01 379 0x03 0x00 0x00 0x01 INFOWait1 380 0x03 0x00 0x00 0x02 381 0x03 0x00 0x00 0x02 INFOWait2 382 0x03 0x00 0x00 0x03 383 0x03 0x00 0x00 0x03 OKAY 384 385 ---------------------------------------------------------------------- 386 [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF] 387 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 388 ---------------------------------------------------------------------- 389 0x03 0x00 0xFF 0xFF download:0000834 390 0x03 0x00 0xFF 0xFF 391 0x03 0x00 0x00 0x00 392 0x03 0x00 0x00 0x00 DATA0000834 393 0x03 0x01 0x00 0x01 <1020 bytes> 394 0x03 0x00 0x00 0x01 395 0x03 0x01 0x00 0x02 <1020 bytes> 396 0x03 0x00 0x00 0x02 397 0x03 0x00 0x00 0x03 <60 bytes> 398 0x03 0x00 0x00 0x03 399 0x03 0x00 0x00 0x04 400 0x03 0x00 0x00 0x04 OKAY 401 402 ---------------------------------------------------------------------- 403 [Unknown ID error, S = 0x0000] 404 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 405 ---------------------------------------------------------------------- 406 0x10 0x00 0x00 0x00 407 0x00 0x00 0x00 0x00 <error message> 408 409 ---------------------------------------------------------------------- 410 [Host packet loss and retransmission, S = 0x0000] 411 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 412 ---------------------------------------------------------------------- 413 0x03 0x00 0x00 0x00 getvar:version [lost] 414 0x03 0x00 0x00 0x00 getvar:version [lost] 415 0x03 0x00 0x00 0x00 getvar:version 416 0x03 0x00 0x00 0x00 417 0x03 0x00 0x00 0x01 418 0x03 0x00 0x00 0x01 OKAY0.4 419 420 ---------------------------------------------------------------------- 421 [Client 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 425 0x03 0x00 0x00 0x00 [lost] 426 0x03 0x00 0x00 0x00 getvar:version 427 0x03 0x00 0x00 0x00 [lost] 428 0x03 0x00 0x00 0x00 getvar:version 429 0x03 0x00 0x00 0x00 430 0x03 0x00 0x00 0x01 431 0x03 0x00 0x00 0x01 OKAY0.4 432 433 ---------------------------------------------------------------------- 434 [Host packet delayed, S = 0x0000] 435 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 436 ---------------------------------------------------------------------- 437 0x03 0x00 0x00 0x00 getvar:version [delayed] 438 0x03 0x00 0x00 0x00 getvar:version 439 0x03 0x00 0x00 0x00 440 0x03 0x00 0x00 0x01 441 0x03 0x00 0x00 0x01 OKAY0.4 442 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored] 443
