fastboot_protocol.txt revision 6f1cd0b2ad7a16d4ec0b5324f992cae33dc34f34
1 2FastBoot Version 0.4++ 3---------------------- 4 5The fastboot protocol is a mechanism for communicating with bootloaders 6over USB. It is designed to be very straightforward to implement, to 7allow it to be used across a wide range of devices and from hosts running 8Linux, Windows, or OSX. 9 10 11Basic Requirements 12------------------ 13 14* Two bulk endpoints (in, out) are required 15* Max packet size must be 64 bytes for full-speed and 512 bytes for 16 high-speed USB 17* The protocol is entirely host-driven and synchronous (unlike the 18 multi-channel, bi-directional, asynchronous ADB protocol) 19 20 21Transport and Framing 22--------------------- 23 241. Host sends a command, which is an ascii string in a single 25 packet no greater than 64 bytes. 26 272. 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 44 DATA00000000 where the 8 digit hexidecimal number represents 45 the total data size to transfer. 46 473. 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 534. 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 645. Success. Stop. 65 66 67Example Session 68--------------- 69 70Host: "getvar:nonexistant" request some undefined variable 71 72Client: "OKAY" return value "" 73 74Host: "download:00001234" request to send 0x1234 bytes of data 75 76Client: "DATA00001234" ready to accept data 77 78Host: < 0x1234 bytes > send data 79 80Client: "OKAY" success 81 82Host: "flash:bootloader" request to flash the data to the bootloader 83 84Client: "INFOerasing flash" indicate status / progress 85 "INFOwriting flash" 86 "OKAY" indicate success 87 88Host: "powerdown" send a command 89 90Client: "FAILunknown command" indicate failure 91 92 93Command Reference 94----------------- 95 96* Command parameters are indicated by printf-style escape sequences. 97 98* Commands are ascii strings and sent without the quotes (which are 99 for illustration only here) and without a trailing 0 byte. 100 101* Commands that begin with a lowercase letter are reserved for this 102 specification. OEM-specific commands should not begin with a 103 lowercase letter, to prevent incompatibilities with future specs. 104 105 "getvar:%s" Read a config/version variable from the bootloader. 106 The variable contents will be returned after the 107 OKAY response. 108 109 "download:%08x" Write data to memory which will be later used 110 by "boot", "ramdisk", "flash", etc. The client 111 will reply with "DATA%08x" if it has enough 112 space in RAM or "FAIL" if not. The size of 113 the download is remembered. 114 115 "verify:%08x" Send a digital signature to verify the downloaded 116 data. Required if the bootloader is "secure" 117 otherwise "flash" and "boot" will be ignored. 118 119 "flash:%s" Write the previously downloaded image to the 120 named partition (if possible). 121 122 "preflash:%s" Optionally prepare for a download + flash. 123 E.g. flash directly during download. To deal with a 124 failed "flash" followed by a "boot", we send 125 "preflash:". 126 127 "erase:%s" Erase the indicated partition (clear to 0xFFs) 128 129 "boot" The previously downloaded data is a boot.img 130 and should be booted according to the normal 131 procedure for a boot.img 132 133 "continue" Continue booting as normal (if possible) 134 135 "reboot" Reboot the device. 136 137 "reboot-bootloader" Reboot back into the bootloader. 138 Useful for upgrade processes that require upgrading 139 the bootloader and then upgrading other partitions 140 using the new bootloader. 141 142 "powerdown" Power off the device. 143 144* Note about sparse files 145 Large files can be split up using libsparse, and sent to the bootloader 146 as repeated chunks of "download:%08x" + "flash:%s". 147 148Client Variables 149---------------- 150 151The "getvar:%s" command is used to read client variables which 152represent various information about the device and the software 153on it. 154 155The various currently defined names are: 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 169Names starting with a lowercase character are reserved by this 170specification. OEM-specific names should not start with lowercase 171characters. 172 173 174