| Fastboot |
| -------- |
| |
| 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, macOS, or Windows. |
| |
| |
| ## 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 4096 bytes. |
| |
| 2. Client response with a single packet no greater than 256 bytes. |
| The first four bytes of the response are "OKAY", "FAIL", "DATA", |
| "INFO" or "TEXT". Additional bytes may contain an (ascii) informative |
| message. |
| |
| a. INFO -> the remaining 252 bytes are an informative message |
| (providing progress or diagnostic messages). They should |
| be displayed and then step #2 repeats. The print format is: |
| "(bootloader) " + InfoMessagePayload + '\n' |
| |
| b. TEXT -> the remaining 252 bytes are arbitrary. They should |
| be displayed and then step #2 repeats. |
| It differs from info in that no formatting is applied. |
| The payload is printed as-is with no newline at the end. |
| Payload is expected to be NULL terminated. |
| |
| c. FAIL -> the requested command failed. The remaining 252 bytes |
| of the response (if present) provide a textual failure message |
| to present to the user. Stop. |
| |
| d. OKAY -> the requested command completed successfully. Go to #5 |
| |
| e. 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 256 bytes. |
| The first four bytes of the response are "OKAY", "FAIL", |
| "INFO" or "TEXT". Similar to #2: |
| |
| a. INFO -> display the formatted remaining 252 bytes and return to #4 |
| |
| b. TEXT -> display the unformatted remaining 252 bytes and return to #4 |
| |
| c. FAIL -> display the remaining 252 bytes (if present) as a failure |
| reason and consider the command failed. Stop. |
| |
| d. 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: "FAILUnknown variable" getvar failure; see getvar details below |
| |
| 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. |
| |
| The various currently defined commands are: |
| |
| getvar:%s Read a config/version variable from the bootloader. |
| The variable contents will be returned after the |
| OKAY response. If the variable is unknown, the bootloader |
| should return a FAIL response, optionally with an error |
| message. |
| |
| Previous versions of this document indicated that getvar |
| should return an empty OKAY response for unknown |
| variables, so older devices might exhibit this behavior, |
| but new implementations should return FAIL instead. |
| |
| 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. |
| |
| upload Read data from memory which was staged by the last |
| command, e.g. an oem command. The client will reply |
| with "DATA%08x" if it is ready to send %08x bytes of |
| data. If no data was staged in the last command, |
| the client must reply with "FAIL". After the client |
| successfully sends %08x bytes, the client shall send |
| a single packet starting with "OKAY". Clients |
| should not support "upload" unless it supports an |
| oem command that requires "upload" capabilities. |
| |
| 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. |
| |
| |
| ## Flashing Logic |
| |
| Fastboot binary will follow directions listed out fastboot-info.txt |
| build artifact for fastboot flashall && fastboot update comamnds. |
| This build artifact will live inside of ANDROID_PRODUCT_OUT && |
| target_files_package && updatepackage. |
| |
| |
| The currently defined commands are: |
| |
| flash %s Flash a given partition. Optional arguments include |
| --slot-other, {filename_path}, --apply-vbmeta |
| |
| reboot %s Reboot to either bootloader or fastbootd |
| |
| update-super Updates the super partition |
| |
| if-wipe Conditionally run some other functionality if |
| wipe is specified |
| |
| erase %s Erase a given partition (can only be used in conjunction) |
| with if-wipe -> eg. if-wipe erase cache |
| |
| Flashing Optimization: |
| |
| After generating the list of tasks to execute, Fastboot will try and |
| optimize the flashing of the dynamic partitions by constructing an |
| optimized flash super task. Fastboot will explicitly pattern match the |
| following commands and try and concatenate it into this task. (doing so |
| will allow us to avoid the reboot into userspace fastbootd which takes |
| significant time) |
| |
| //Optimizable Block |
| reboot fastboot |
| update-super ---> generate optimized flash super task |
| $FOR EACH {dynamic partition} |
| flash {dynamic partition} |
| |
| ## 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. |
| |
| is-userspace If the value is "yes", the device is running |
| fastbootd. Otherwise, it is running fastboot |
| in the bootloader. |
| |
| Names starting with a lowercase character are reserved by this |
| specification. OEM-specific names should not start with lowercase |
| characters. |
| |
| ## Logical Partitions |
| |
| There are a number of commands to interact with logical partitions: |
| |
| update-super:%s:%s Write the previously downloaded image to a super |
| partition. Unlike the "flash" command, this has |
| special rules. The image must have been created by |
| the lpmake command, and must not be a sparse image. |
| If the last argument is "wipe", then all existing |
| logical partitions are deleted. If no final argument |
| is specified, the partition tables are merged. Any |
| partition in the new image that does not exist in the |
| old image is created with a zero size. |
| |
| In all cases, this will cause the temporary "scratch" |
| partition to be deleted if it exists. |
| |
| create-logical-partition:%s:%d |
| Create a logical partition with the given name and |
| size, in the super partition. |
| |
| delete-logical-partition:%s |
| Delete a logical partition with the given name. |
| |
| resize-logical-partition:%s:%d |
| Change the size of the named logical partition. |
| |
| In addition, there is a variable to test whether a partition is logical: |
| |
| is-logical:%s If the value is "yes", the partition is logical. |
| Otherwise the partition is physical. |
| |
| ## 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 <connect to the device on port 5555> |
| 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][0x14]FAILUnknown variable |
| Host <disconnect> |
| |
| |
| ## 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:none |
| 0x03 0x00 0x00 0x03 |
| 0x03 0x00 0x00 0x04 |
| 0x03 0x00 0x00 0x04 FAILUnknown var |
| |
| ---------------------------------------------------------------------- |
| [fastboot "INFO" responses, S = 0x0000] |
| ID Flags SeqH SeqL Data ID Flags SeqH SeqL Data |
| ---------------------------------------------------------------------- |
| 0x03 0x00 0x00 0x00 <command> |
| 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 <error message> |
| |
| ---------------------------------------------------------------------- |
| [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] |
