Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 1 | FastBoot Version 0.4 |
| 2 | ---------------------- |
| 3 | |
| 4 | The fastboot protocol is a mechanism for communicating with bootloaders |
David Pursell | 2ec418a | 2016-01-20 08:32:08 -0800 | [diff] [blame] | 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 |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 7 | Linux, Windows, or OSX. |
| 8 | |
| 9 | |
| 10 | Basic Requirements |
| 11 | ------------------ |
| 12 | |
David Pursell | 2ec418a | 2016-01-20 08:32:08 -0800 | [diff] [blame] | 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 | |
David Pursell | 4601c97 | 2016-02-05 15:35:09 -0800 | [diff] [blame] | 20 | * TCP or UDP |
David Pursell | 2ec418a | 2016-01-20 08:32:08 -0800 | [diff] [blame] | 21 | * Device must be reachable via IP. |
David Pursell | 4601c97 | 2016-02-05 15:35:09 -0800 | [diff] [blame] | 22 | * Device will act as the server, fastboot will be the client. |
David Pursell | 2ec418a | 2016-01-20 08:32:08 -0800 | [diff] [blame] | 23 | * Fastboot data is wrapped in a simple protocol; see below for details. |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 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 |
Elliott Hughes | fc79767 | 2015-04-07 20:12:50 -0700 | [diff] [blame] | 49 | DATA00000000 where the 8 digit hexadecimal number represents |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 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. |
Elliott Hughes | d505cd8 | 2016-02-03 14:30:01 -0800 | [diff] [blame] | 160 | It should be "0.4" for this document. |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 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 | |
David Pursell | 2ec418a | 2016-01-20 08:32:08 -0800 | [diff] [blame] | 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> |
David Pursell | 4601c97 | 2016-02-05 15:35:09 -0800 | [diff] [blame] | 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] |