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