Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
.clang-format | D | 03-May-2024 | 251 | 12 | 11 | |
Android.mk | D | 03-May-2024 | 3.9 KiB | 136 | 88 | |
README.md | D | 03-May-2024 | 19.6 KiB | 464 | 350 | |
bootimg_utils.cpp | D | 03-May-2024 | 3 KiB | 78 | 37 | |
bootimg_utils.h | D | 03-May-2024 | 1.9 KiB | 44 | 12 | |
engine.cpp | D | 03-May-2024 | 11.3 KiB | 417 | 318 | |
fastboot.cpp | D | 03-May-2024 | 67.5 KiB | 1,889 | 1,561 | |
fastboot.h | D | 03-May-2024 | 3.4 KiB | 84 | 41 | |
fs.cpp | D | 03-May-2024 | 6.6 KiB | 203 | 171 | |
fs.h | D | 03-May-2024 | 366 | 14 | 9 | |
protocol.cpp | D | 03-May-2024 | 10.3 KiB | 359 | 271 | |
socket.cpp | D | 03-May-2024 | 9.3 KiB | 291 | 194 | |
socket.h | D | 03-May-2024 | 5.7 KiB | 130 | 39 | |
socket_mock.cpp | D | 03-May-2024 | 4.9 KiB | 152 | 95 | |
socket_mock.h | D | 03-May-2024 | 3.5 KiB | 102 | 36 | |
socket_test.cpp | D | 03-May-2024 | 13.7 KiB | 386 | 259 | |
tcp.cpp | D | 03-May-2024 | 6.5 KiB | 200 | 126 | |
tcp.h | D | 03-May-2024 | 2.2 KiB | 60 | 15 | |
tcp_test.cpp | D | 03-May-2024 | 7.4 KiB | 228 | 147 | |
transport.h | D | 03-May-2024 | 1.5 KiB | 49 | 15 | |
udp.cpp | D | 03-May-2024 | 13.7 KiB | 392 | 257 | |
udp.h | D | 03-May-2024 | 2.8 KiB | 82 | 29 | |
udp_test.cpp | D | 03-May-2024 | 20.6 KiB | 532 | 362 | |
usb.h | D | 03-May-2024 | 2 KiB | 61 | 21 | |
usb_linux.cpp | D | 03-May-2024 | 14.3 KiB | 499 | 344 | |
usb_osx.cpp | D | 03-May-2024 | 16.6 KiB | 575 | 367 | |
usb_windows.cpp | D | 03-May-2024 | 11.2 KiB | 365 | 238 | |
usbtest.cpp | D | 03-May-2024 | 5.8 KiB | 213 | 159 | |
util.cpp | D | 03-May-2024 | 2 KiB | 70 | 34 |
README.md
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 verify:%08x Send a digital signature to verify the downloaded 140 data. Required if the bootloader is "secure" 141 otherwise "flash" and "boot" will be ignored. 142 143 flash:%s Write the previously downloaded image to the 144 named partition (if possible). 145 146 erase:%s Erase the indicated partition (clear to 0xFFs) 147 148 boot The previously downloaded data is a boot.img 149 and should be booted according to the normal 150 procedure for a boot.img 151 152 continue Continue booting as normal (if possible) 153 154 reboot Reboot the device. 155 156 reboot-bootloader 157 Reboot back into the bootloader. 158 Useful for upgrade processes that require upgrading 159 the bootloader and then upgrading other partitions 160 using the new bootloader. 161 162 powerdown Power off the device. 163 164 165 166## Client Variables 167 168The "getvar:%s" command is used to read client variables which 169represent various information about the device and the software 170on it. 171 172The various currently defined names are: 173 174 version Version of FastBoot protocol supported. 175 It should be "0.4" for this document. 176 177 version-bootloader Version string for the Bootloader. 178 179 version-baseband Version string of the Baseband Software 180 181 product Name of the product 182 183 serialno Product serial number 184 185 secure If the value is "yes", this is a secure 186 bootloader requiring a signature before 187 it will install or boot images. 188 189Names starting with a lowercase character are reserved by this 190specification. OEM-specific names should not start with lowercase 191characters. 192 193 194## TCP Protocol v1 195 196The TCP protocol is designed to be a simple way to use the fastboot protocol 197over ethernet if USB is not available. 198 199The device will open a TCP server on port 5554 and wait for a fastboot client 200to connect. 201 202### Handshake 203Upon connecting, both sides will send a 4-byte handshake message to ensure they 204are speaking the same protocol. This consists of the ASCII characters "FB" 205followed by a 2-digit base-10 ASCII version number. For example, the version 1 206handshake message will be [FB01]. 207 208If either side detects a malformed handshake, it should disconnect. 209 210The protocol version to use must be the minimum of the versions sent by each 211side; if either side cannot speak this protocol version, it should disconnect. 212 213### Fastboot Data 214Once the handshake is complete, fastboot data will be sent as follows: 215 216 [data_size][data] 217 218Where data\_size is an unsigned 8-byte big-endian binary value, and data is the 219fastboot packet. The 8-byte length is intended to provide future-proofing even 220though currently fastboot packets have a 4-byte maximum length. 221 222### Example 223In this example the fastboot host queries the device for two variables, 224"version" and "none". 225 226 Host <connect to the device on port 5555> 227 Host FB01 228 Device FB01 229 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version 230 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4 231 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none 232 Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable 233 Host <disconnect> 234 235 236## UDP Protocol v1 237 238The UDP protocol is more complex than TCP since we must implement reliability 239to ensure no packets are lost, but the general concept of wrapping the fastboot 240protocol is the same. 241 242Overview: 243 1. As with TCP, the device will listen on UDP port 5554. 244 2. Maximum UDP packet size is negotiated during initialization. 245 3. The host drives all communication; the device may only send a packet as a 246 response to a host packet. 247 4. If the host does not receive a response in 500ms it will re-transmit. 248 249### UDP Packet format 250 251 +----------+----+-------+-------+--------------------+ 252 | Byte # | 0 | 1 | 2 - 3 | 4+ | 253 +----------+----+-------+-------+--------------------+ 254 | Contents | ID | Flags | Seq # | Data | 255 +----------+----+-------+-------+--------------------+ 256 257 ID Packet ID: 258 0x00: Error. 259 0x01: Query. 260 0x02: Initialization. 261 0x03: Fastboot. 262 263 Packet types are described in more detail below. 264 265 Flags Packet flags: 0 0 0 0 0 0 0 C 266 C=1 indicates a continuation packet; the data is too large and will 267 continue in the next packet. 268 269 Remaining bits are reserved for future use and must be set to 0. 270 271 Seq # 2-byte packet sequence number (big-endian). The host will increment 272 this by 1 with each new packet, and the device must provide the 273 corresponding sequence number in the response packets. 274 275 Data Packet data, not present in all packets. 276 277### Packet Types 278 279 Query 280 The host sends a query packet once on startup to sync with the device. 281 The host will not know the current sequence number, so the device must 282 respond to all query packets regardless of sequence number. 283 284 The response data field should contain a 2-byte big-endian value 285 giving the next expected sequence number. 286 287 Init 288 The host sends an init packet once the query response is returned. The 289 device must abort any in-progress operation and prepare for a new 290 fastboot session. This message is meant to allow recovery if a 291 previous session failed, e.g. due to network error or user Ctrl+C. 292 293 The data field contains two big-endian 2-byte values, a protocol 294 version and the max UDP packet size (including the 4-byte header). 295 Both the host and device will send these values, and in each case 296 the minimum of the sent values must be used. 297 298 Fastboot 299 These packets wrap the fastboot protocol. To write, the host will 300 send a packet with fastboot data, and the device will reply with an 301 empty packet as an ACK. To read, the host will send an empty packet, 302 and the device will reply with fastboot data. The device may not give 303 any data in the ACK packet. 304 305 Error 306 The device may respond to any packet with an error packet to indicate 307 a UDP protocol error. The data field should contain an ASCII string 308 describing the error. This is the only case where a device is allowed 309 to return a packet ID other than the one sent by the host. 310 311### Packet Size 312The maximum packet size is negotiated by the host and device in the Init packet. 313Devices must support at least 512-byte packets, but packet size has a direct 314correlation with download speed, so devices are strongly suggested to support at 315least 1024-byte packets. On a local network with 0.5ms round-trip time this will 316provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly 317less. 318 319Query and Initialization packets, which are sent before size negotiation is 320complete, must always be 512 bytes or less. 321 322### Packet Re-Transmission 323The host will re-transmit any packet that does not receive a response. The 324requirement of exactly one device response packet per host packet is how we 325achieve reliability and in-order delivery of packets. 326 327For simplicity of implementation, there is no windowing of multiple 328unacknowledged packets in this version of the protocol. The host will continue 329to send the same packet until a response is received. Windowing functionality 330may be implemented in future versions if necessary to increase performance. 331 332The first Query packet will only be attempted a small number of times, but 333subsequent packets will attempt to retransmit for at least 1 minute before 334giving up. This means a device may safely ignore host UDP packets for up to 1 335minute during long operations, e.g. writing to flash. 336 337### Continuation Packets 338Any packet may set the continuation flag to indicate that the data is 339incomplete. Large data such as downloading an image may require many 340continuation packets. The receiver should respond to a continuation packet with 341an empty packet to acknowledge receipt. See examples below. 342 343### Summary 344The host starts with a Query packet, then an Initialization packet, after 345which only Fastboot packets are sent. Fastboot packets may contain data from 346the host for writes, or from the device for reads, but not both. 347 348Given a next expected sequence number S and a received packet P, the device 349behavior should be: 350 351 if P is a Query packet: 352 * respond with a Query packet with S in the data field 353 else if P has sequence == S: 354 * process P and take any required action 355 * create a response packet R with the same ID and sequence as P, containing 356 any response data required. 357 * transmit R and save it in case of re-transmission 358 * increment S 359 else if P has sequence == S - 1: 360 * re-transmit the saved response packet R from above 361 else: 362 * ignore the packet 363 364### Examples 365 366In the examples below, S indicates the starting client sequence number. 367 368 Host Client 369 ====================================================================== 370 [Initialization, S = 0x55AA] 371 [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.] 372 [Resulting values to use: version = 1, max packet size = 1024] 373 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 374 ---------------------------------------------------------------------- 375 0x01 0x00 0x00 0x00 376 0x01 0x00 0x00 0x00 0x55 0xAA 377 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00 378 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00 379 380 ---------------------------------------------------------------------- 381 [fastboot "getvar" commands, S = 0x0001] 382 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 383 ---------------------------------------------------------------------- 384 0x03 0x00 0x00 0x01 getvar:version 385 0x03 0x00 0x00 0x01 386 0x03 0x00 0x00 0x02 387 0x03 0x00 0x00 0x02 OKAY0.4 388 0x03 0x00 0x00 0x03 getvar:none 389 0x03 0x00 0x00 0x03 390 0x03 0x00 0x00 0x04 391 0x03 0x00 0x00 0x04 FAILUnknown var 392 393 ---------------------------------------------------------------------- 394 [fastboot "INFO" responses, S = 0x0000] 395 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 396 ---------------------------------------------------------------------- 397 0x03 0x00 0x00 0x00 <command> 398 0x03 0x00 0x00 0x00 399 0x03 0x00 0x00 0x01 400 0x03 0x00 0x00 0x01 INFOWait1 401 0x03 0x00 0x00 0x02 402 0x03 0x00 0x00 0x02 INFOWait2 403 0x03 0x00 0x00 0x03 404 0x03 0x00 0x00 0x03 OKAY 405 406 ---------------------------------------------------------------------- 407 [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF] 408 ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data 409 ---------------------------------------------------------------------- 410 0x03 0x00 0xFF 0xFF download:0000834 411 0x03 0x00 0xFF 0xFF 412 0x03 0x00 0x00 0x00 413 0x03 0x00 0x00 0x00 DATA0000834 414 0x03 0x01 0x00 0x01 <1020 bytes> 415 0x03 0x00 0x00 0x01 416 0x03 0x01 0x00 0x02 <1020 bytes> 417 0x03 0x00 0x00 0x02 418 0x03 0x00 0x00 0x03 <60 bytes> 419 0x03 0x00 0x00 0x03 420 0x03 0x00 0x00 0x04 421 0x03 0x00 0x00 0x04 OKAY 422 423 ---------------------------------------------------------------------- 424 [Unknown ID error, S = 0x0000] 425 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 426 ---------------------------------------------------------------------- 427 0x10 0x00 0x00 0x00 428 0x00 0x00 0x00 0x00 <error message> 429 430 ---------------------------------------------------------------------- 431 [Host packet loss and retransmission, S = 0x0000] 432 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 433 ---------------------------------------------------------------------- 434 0x03 0x00 0x00 0x00 getvar:version [lost] 435 0x03 0x00 0x00 0x00 getvar:version [lost] 436 0x03 0x00 0x00 0x00 getvar:version 437 0x03 0x00 0x00 0x00 438 0x03 0x00 0x00 0x01 439 0x03 0x00 0x00 0x01 OKAY0.4 440 441 ---------------------------------------------------------------------- 442 [Client packet loss and retransmission, S = 0x0000] 443 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 444 ---------------------------------------------------------------------- 445 0x03 0x00 0x00 0x00 getvar:version 446 0x03 0x00 0x00 0x00 [lost] 447 0x03 0x00 0x00 0x00 getvar:version 448 0x03 0x00 0x00 0x00 [lost] 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 454 ---------------------------------------------------------------------- 455 [Host packet delayed, S = 0x0000] 456 ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data 457 ---------------------------------------------------------------------- 458 0x03 0x00 0x00 0x00 getvar:version [delayed] 459 0x03 0x00 0x00 0x00 getvar:version 460 0x03 0x00 0x00 0x00 461 0x03 0x00 0x00 0x01 462 0x03 0x00 0x00 0x01 OKAY0.4 463 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored] 464