Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 1 | |
| 2 | FastBoot Version 0.4 |
| 3 | ---------------------- |
| 4 | |
| 5 | The fastboot protocol is a mechanism for communicating with bootloaders |
| 6 | over USB. It is designed to be very straightforward to implement, to |
| 7 | allow it to be used across a wide range of devices and from hosts running |
| 8 | Linux, Windows, or OSX. |
| 9 | |
| 10 | |
| 11 | Basic Requirements |
| 12 | ------------------ |
| 13 | |
| 14 | * Two bulk endpoints (in, out) are required |
Channagoud Kadabi | b211773 | 2014-11-05 16:59:27 -0800 | [diff] [blame] | 15 | * Max packet size must be 64 bytes for full-speed, 512 bytes for |
| 16 | high-speed and 1024 bytes for Super Speed USB. |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 17 | * The protocol is entirely host-driven and synchronous (unlike the |
| 18 | multi-channel, bi-directional, asynchronous ADB protocol) |
| 19 | |
| 20 | |
| 21 | Transport and Framing |
| 22 | --------------------- |
| 23 | |
| 24 | 1. Host sends a command, which is an ascii string in a single |
| 25 | packet no greater than 64 bytes. |
| 26 | |
| 27 | 2. Client response with a single packet no greater than 64 bytes. |
| 28 | The first four bytes of the response are "OKAY", "FAIL", "DATA", |
| 29 | or "INFO". Additional bytes may contain an (ascii) informative |
| 30 | message. |
| 31 | |
| 32 | a. INFO -> the remaining 60 bytes are an informative message |
| 33 | (providing progress or diagnostic messages). They should |
| 34 | be displayed and then step #2 repeats |
| 35 | |
| 36 | b. FAIL -> the requested command failed. The remaining 60 bytes |
| 37 | of the response (if present) provide a textual failure message |
| 38 | to present to the user. Stop. |
| 39 | |
| 40 | c. OKAY -> the requested command completed successfully. Go to #5 |
| 41 | |
| 42 | d. DATA -> the requested command is ready for the data phase. |
| 43 | 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] | 44 | DATA00000000 where the 8 digit hexadecimal number represents |
Scott Anderson | 9bfecb0 | 2012-12-06 09:34:34 -0800 | [diff] [blame] | 45 | the total data size to transfer. |
| 46 | |
| 47 | 3. Data phase. Depending on the command, the host or client will |
| 48 | send the indicated amount of data. Short packets are always |
| 49 | acceptable and zero-length packets are ignored. This phase continues |
| 50 | until the client has sent or received the number of bytes indicated |
| 51 | in the "DATA" response above. |
| 52 | |
| 53 | 4. Client responds with a single packet no greater than 64 bytes. |
| 54 | The first four bytes of the response are "OKAY", "FAIL", or "INFO". |
| 55 | Similar to #2: |
| 56 | |
| 57 | a. INFO -> display the remaining 60 bytes and return to #4 |
| 58 | |
| 59 | b. FAIL -> display the remaining 60 bytes (if present) as a failure |
| 60 | reason and consider the command failed. Stop. |
| 61 | |
| 62 | c. OKAY -> success. Go to #5 |
| 63 | |
| 64 | 5. Success. Stop. |
| 65 | |
| 66 | |
| 67 | Example Session |
| 68 | --------------- |
| 69 | |
| 70 | Host: "getvar:version" request version variable |
| 71 | |
| 72 | Client: "OKAY0.4" return version "0.4" |
| 73 | |
| 74 | Host: "getvar:nonexistant" request some undefined variable |
| 75 | |
| 76 | Client: "OKAY" return value "" |
| 77 | |
| 78 | Host: "download:00001234" request to send 0x1234 bytes of data |
| 79 | |
| 80 | Client: "DATA00001234" ready to accept data |
| 81 | |
| 82 | Host: < 0x1234 bytes > send data |
| 83 | |
| 84 | Client: "OKAY" success |
| 85 | |
| 86 | Host: "flash:bootloader" request to flash the data to the bootloader |
| 87 | |
| 88 | Client: "INFOerasing flash" indicate status / progress |
| 89 | "INFOwriting flash" |
| 90 | "OKAY" indicate success |
| 91 | |
| 92 | Host: "powerdown" send a command |
| 93 | |
| 94 | Client: "FAILunknown command" indicate failure |
| 95 | |
| 96 | |
| 97 | Command Reference |
| 98 | ----------------- |
| 99 | |
| 100 | * Command parameters are indicated by printf-style escape sequences. |
| 101 | |
| 102 | * Commands are ascii strings and sent without the quotes (which are |
| 103 | for illustration only here) and without a trailing 0 byte. |
| 104 | |
| 105 | * Commands that begin with a lowercase letter are reserved for this |
| 106 | specification. OEM-specific commands should not begin with a |
| 107 | lowercase letter, to prevent incompatibilities with future specs. |
| 108 | |
| 109 | "getvar:%s" Read a config/version variable from the bootloader. |
| 110 | The variable contents will be returned after the |
| 111 | OKAY response. |
| 112 | |
| 113 | "download:%08x" Write data to memory which will be later used |
| 114 | by "boot", "ramdisk", "flash", etc. The client |
| 115 | will reply with "DATA%08x" if it has enough |
| 116 | space in RAM or "FAIL" if not. The size of |
| 117 | the download is remembered. |
| 118 | |
| 119 | "verify:%08x" Send a digital signature to verify the downloaded |
| 120 | data. Required if the bootloader is "secure" |
| 121 | otherwise "flash" and "boot" will be ignored. |
| 122 | |
| 123 | "flash:%s" Write the previously downloaded image to the |
| 124 | named partition (if possible). |
| 125 | |
| 126 | "erase:%s" Erase the indicated partition (clear to 0xFFs) |
| 127 | |
| 128 | "boot" The previously downloaded data is a boot.img |
| 129 | and should be booted according to the normal |
| 130 | procedure for a boot.img |
| 131 | |
| 132 | "continue" Continue booting as normal (if possible) |
| 133 | |
| 134 | "reboot" Reboot the device. |
| 135 | |
| 136 | "reboot-bootloader" Reboot back into the bootloader. |
| 137 | Useful for upgrade processes that require upgrading |
| 138 | the bootloader and then upgrading other partitions |
| 139 | using the new bootloader. |
| 140 | |
| 141 | "powerdown" Power off the device. |
| 142 | |
| 143 | |
| 144 | |
| 145 | Client Variables |
| 146 | ---------------- |
| 147 | |
| 148 | The "getvar:%s" command is used to read client variables which |
| 149 | represent various information about the device and the software |
| 150 | on it. |
| 151 | |
| 152 | The various currently defined names are: |
| 153 | |
| 154 | version Version of FastBoot protocol supported. |
| 155 | It should be "0.3" for this document. |
| 156 | |
| 157 | version-bootloader Version string for the Bootloader. |
| 158 | |
| 159 | version-baseband Version string of the Baseband Software |
| 160 | |
| 161 | product Name of the product |
| 162 | |
| 163 | serialno Product serial number |
| 164 | |
| 165 | secure If the value is "yes", this is a secure |
| 166 | bootloader requiring a signature before |
| 167 | it will install or boot images. |
| 168 | |
| 169 | Names starting with a lowercase character are reserved by this |
| 170 | specification. OEM-specific names should not start with lowercase |
| 171 | characters. |
| 172 | |
| 173 | |