FastBoot Version 0.4 ---------------------- The fastboot protocol is a mechanism for communicating with bootloaders over USB or ethernet. It is designed to be very straightforward to implement, to allow it to be used across a wide range of devices and from hosts running Linux, Windows, or OSX. Basic Requirements ------------------ * USB * Two bulk endpoints (in, out) are required * Max packet size must be 64 bytes for full-speed, 512 bytes for high-speed and 1024 bytes for Super Speed USB. * The protocol is entirely host-driven and synchronous (unlike the multi-channel, bi-directional, asynchronous ADB protocol) * TCP or UDP * Device must be reachable via IP. * Device will act as the server, fastboot will be the client. * Fastboot data is wrapped in a simple protocol; see below for details. Transport and Framing --------------------- 1. Host sends a command, which is an ascii string in a single packet no greater than 64 bytes. 2. Client response with a single packet no greater than 64 bytes. The first four bytes of the response are "OKAY", "FAIL", "DATA", or "INFO". Additional bytes may contain an (ascii) informative message. a. INFO -> the remaining 60 bytes are an informative message (providing progress or diagnostic messages). They should be displayed and then step #2 repeats b. FAIL -> the requested command failed. The remaining 60 bytes of the response (if present) provide a textual failure message to present to the user. Stop. c. OKAY -> the requested command completed successfully. Go to #5 d. DATA -> the requested command is ready for the data phase. A DATA response packet will be 12 bytes long, in the form of DATA00000000 where the 8 digit hexadecimal number represents the total data size to transfer. 3. Data phase. Depending on the command, the host or client will send the indicated amount of data. Short packets are always acceptable and zero-length packets are ignored. This phase continues until the client has sent or received the number of bytes indicated in the "DATA" response above. 4. Client responds with a single packet no greater than 64 bytes. The first four bytes of the response are "OKAY", "FAIL", or "INFO". Similar to #2: a. INFO -> display the remaining 60 bytes and return to #4 b. FAIL -> display the remaining 60 bytes (if present) as a failure reason and consider the command failed. Stop. c. OKAY -> success. Go to #5 5. Success. Stop. Example Session --------------- Host: "getvar:version" request version variable Client: "OKAY0.4" return version "0.4" Host: "getvar:nonexistant" request some undefined variable Client: "OKAY" return value "" Host: "download:00001234" request to send 0x1234 bytes of data Client: "DATA00001234" ready to accept data Host: < 0x1234 bytes > send data Client: "OKAY" success Host: "flash:bootloader" request to flash the data to the bootloader Client: "INFOerasing flash" indicate status / progress "INFOwriting flash" "OKAY" indicate success Host: "powerdown" send a command Client: "FAILunknown command" indicate failure Command Reference ----------------- * Command parameters are indicated by printf-style escape sequences. * Commands are ascii strings and sent without the quotes (which are for illustration only here) and without a trailing 0 byte. * Commands that begin with a lowercase letter are reserved for this specification. OEM-specific commands should not begin with a lowercase letter, to prevent incompatibilities with future specs. "getvar:%s" Read a config/version variable from the bootloader. The variable contents will be returned after the OKAY response. "download:%08x" Write data to memory which will be later used by "boot", "ramdisk", "flash", etc. The client will reply with "DATA%08x" if it has enough space in RAM or "FAIL" if not. The size of the download is remembered. "verify:%08x" Send a digital signature to verify the downloaded data. Required if the bootloader is "secure" otherwise "flash" and "boot" will be ignored. "flash:%s" Write the previously downloaded image to the named partition (if possible). "erase:%s" Erase the indicated partition (clear to 0xFFs) "boot" The previously downloaded data is a boot.img and should be booted according to the normal procedure for a boot.img "continue" Continue booting as normal (if possible) "reboot" Reboot the device. "reboot-bootloader" Reboot back into the bootloader. Useful for upgrade processes that require upgrading the bootloader and then upgrading other partitions using the new bootloader. "powerdown" Power off the device. Client Variables ---------------- The "getvar:%s" command is used to read client variables which represent various information about the device and the software on it. The various currently defined names are: version Version of FastBoot protocol supported. It should be "0.4" for this document. version-bootloader Version string for the Bootloader. version-baseband Version string of the Baseband Software product Name of the product serialno Product serial number secure If the value is "yes", this is a secure bootloader requiring a signature before it will install or boot images. Names starting with a lowercase character are reserved by this specification. OEM-specific names should not start with lowercase characters. TCP Protocol v1 --------------- The TCP protocol is designed to be a simple way to use the fastboot protocol over ethernet if USB is not available. The device will open a TCP server on port 5554 and wait for a fastboot client to connect. -- Handshake -- Upon connecting, both sides will send a 4-byte handshake message to ensure they are speaking the same protocol. This consists of the ASCII characters "FB" followed by a 2-digit base-10 ASCII version number. For example, the version 1 handshake message will be [FB01]. If either side detects a malformed handshake, it should disconnect. The protocol version to use must be the minimum of the versions sent by each side; if either side cannot speak this protocol version, it should disconnect. -- Fastboot Data -- Once the handshake is complete, fastboot data will be sent as follows: [data_size][data] Where data_size is an unsigned 8-byte big-endian binary value, and data is the fastboot packet. The 8-byte length is intended to provide future-proofing even though currently fastboot packets have a 4-byte maximum length. -- Example -- In this example the fastboot host queries the device for two variables, "version" and "none". Host Host FB01 Device FB01 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4 Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x04]OKAY Host UDP Protocol v1 --------------- The UDP protocol is more complex than TCP since we must implement reliability to ensure no packets are lost, but the general concept of wrapping the fastboot protocol is the same. Overview: 1. As with TCP, the device will listen on UDP port 5554. 2. Maximum UDP packet size is negotiated during initialization. 3. The host drives all communication; the device may only send a packet as a response to a host packet. 4. If the host does not receive a response in 500ms it will re-transmit. -- UDP Packet format -- +----------+----+-------+-------+--------------------+ | Byte # | 0 | 1 | 2 - 3 | 4+ | +----------+----+-------+-------+--------------------+ | Contents | ID | Flags | Seq # | Data | +----------+----+-------+-------+--------------------+ ID Packet ID: 0x00: Error. 0x01: Query. 0x02: Initialization. 0x03: Fastboot. Packet types are described in more detail below. Flags Packet flags: 0 0 0 0 0 0 0 C C=1 indicates a continuation packet; the data is too large and will continue in the next packet. Remaining bits are reserved for future use and must be set to 0. Seq # 2-byte packet sequence number (big-endian). The host will increment this by 1 with each new packet, and the device must provide the corresponding sequence number in the response packets. Data Packet data, not present in all packets. -- Packet Types -- Query The host sends a query packet once on startup to sync with the device. The host will not know the current sequence number, so the device must respond to all query packets regardless of sequence number. The response data field should contain a 2-byte big-endian value giving the next expected sequence number. Init The host sends an init packet once the query response is returned. The device must abort any in-progress operation and prepare for a new fastboot session. This message is meant to allow recovery if a previous session failed, e.g. due to network error or user Ctrl+C. The data field contains two big-endian 2-byte values, a protocol version and the max UDP packet size (including the 4-byte header). Both the host and device will send these values, and in each case the minimum of the sent values must be used. Fastboot These packets wrap the fastboot protocol. To write, the host will send a packet with fastboot data, and the device will reply with an empty packet as an ACK. To read, the host will send an empty packet, and the device will reply with fastboot data. The device may not give any data in the ACK packet. Error The device may respond to any packet with an error packet to indicate a UDP protocol error. The data field should contain an ASCII string describing the error. This is the only case where a device is allowed to return a packet ID other than the one sent by the host. -- Packet Size -- The maximum packet size is negotiated by the host and device in the Init packet. Devices must support at least 512-byte packets, but packet size has a direct correlation with download speed, so devices are strongly suggested to support at least 1024-byte packets. On a local network with 0.5ms round-trip time this will provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly less. Query and Initialization packets, which are sent before size negotiation is complete, must always be 512 bytes or less. -- Packet Re-Transmission -- The host will re-transmit any packet that does not receive a response. The requirement of exactly one device response packet per host packet is how we achieve reliability and in-order delivery of packets. For simplicity of implementation, there is no windowing of multiple unacknowledged packets in this version of the protocol. The host will continue to send the same packet until a response is received. Windowing functionality may be implemented in future versions if necessary to increase performance. The first Query packet will only be attempted a small number of times, but subsequent packets will attempt to retransmit for at least 1 minute before giving up. This means a device may safely ignore host UDP packets for up to 1 minute during long operations, e.g. writing to flash. -- Continuation Packets -- Any packet may set the continuation flag to indicate that the data is incomplete. Large data such as downloading an image may require many continuation packets. The receiver should respond to a continuation packet with an empty packet to acknowledge receipt. See examples below. -- Summary -- The host starts with a Query packet, then an Initialization packet, after which only Fastboot packets are sent. Fastboot packets may contain data from the host for writes, or from the device for reads, but not both. Given a next expected sequence number S and a received packet P, the device behavior should be: if P is a Query packet: * respond with a Query packet with S in the data field else if P has sequence == S: * process P and take any required action * create a response packet R with the same ID and sequence as P, containing any response data required. * transmit R and save it in case of re-transmission * increment S else if P has sequence == S - 1: * re-transmit the saved response packet R from above else: * ignore the packet -- Examples -- In the examples below, S indicates the starting client sequence number. Host Client ====================================================================== [Initialization, S = 0x55AA] [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.] [Resulting values to use: version = 1, max packet size = 1024] ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data ---------------------------------------------------------------------- 0x01 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x55 0xAA 0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00 0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00 ---------------------------------------------------------------------- [fastboot "getvar" commands, S = 0x0001] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0x00 0x01 getvar:version 0x03 0x00 0x00 0x01 0x03 0x00 0x00 0x02 0x03 0x00 0x00 0x02 OKAY0.4 0x03 0x00 0x00 0x03 getvar:foo 0x03 0x00 0x00 0x03 0x03 0x00 0x00 0x04 0x03 0x00 0x00 0x04 OKAY ---------------------------------------------------------------------- [fastboot "INFO" responses, S = 0x0000] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x01 0x03 0x00 0x00 0x01 INFOWait1 0x03 0x00 0x00 0x02 0x03 0x00 0x00 0x02 INFOWait2 0x03 0x00 0x00 0x03 0x03 0x00 0x00 0x03 OKAY ---------------------------------------------------------------------- [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF] ID Flag SeqH SeqL Data ID Flag SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0xFF 0xFF download:0000834 0x03 0x00 0xFF 0xFF 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x00 DATA0000834 0x03 0x01 0x00 0x01 <1020 bytes> 0x03 0x00 0x00 0x01 0x03 0x01 0x00 0x02 <1020 bytes> 0x03 0x00 0x00 0x02 0x03 0x00 0x00 0x03 <60 bytes> 0x03 0x00 0x00 0x03 0x03 0x00 0x00 0x04 0x03 0x00 0x00 0x04 OKAY ---------------------------------------------------------------------- [Unknown ID error, S = 0x0000] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x10 0x00 0x00 0x00 0x00 0x00 0x00 0x00 ---------------------------------------------------------------------- [Host packet loss and retransmission, S = 0x0000] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0x00 0x00 getvar:version [lost] 0x03 0x00 0x00 0x00 getvar:version [lost] 0x03 0x00 0x00 0x00 getvar:version 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x01 0x03 0x00 0x00 0x01 OKAY0.4 ---------------------------------------------------------------------- [Client packet loss and retransmission, S = 0x0000] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0x00 0x00 getvar:version 0x03 0x00 0x00 0x00 [lost] 0x03 0x00 0x00 0x00 getvar:version 0x03 0x00 0x00 0x00 [lost] 0x03 0x00 0x00 0x00 getvar:version 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x01 0x03 0x00 0x00 0x01 OKAY0.4 ---------------------------------------------------------------------- [Host packet delayed, S = 0x0000] ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data ---------------------------------------------------------------------- 0x03 0x00 0x00 0x00 getvar:version [delayed] 0x03 0x00 0x00 0x00 getvar:version 0x03 0x00 0x00 0x00 0x03 0x00 0x00 0x01 0x03 0x00 0x00 0x01 OKAY0.4 0x03 0x00 0x00 0x00 getvar:version [arrives late with old seq#, is ignored]