| |
| 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 |
| * Device must be reachable via IP. |
| * Device will act as the TCP 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.3" 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 <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][0x04]OKAY |
| Host <disconnect> |