blob: e9e7166a2660c4c6e0a6dddae6706e6df7a72949 [file] [log] [blame]
Sebastian Siewior3aab70a2014-05-05 15:08:10 -05001FastBoot Version 0.4
2----------------------
3
4The fastboot protocol is a mechanism for communicating with bootloaders
5over USB. It is designed to be very straightforward to implement, to
6allow it to be used across a wide range of devices and from hosts running
7Linux, Windows, or OSX.
8
9
10Basic 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
20Transport and Framing
21---------------------
22
231. Host sends a command, which is an ascii string in a single
24 packet no greater than 64 bytes.
25
262. 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
463. 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
524. 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
635. Success. Stop.
64
65
66Example Session
67---------------
68
69Host: "getvar:version" request version variable
70
71Client: "OKAY0.4" return version "0.4"
72
73Host: "getvar:nonexistant" request some undefined variable
74
75Client: "OKAY" return value ""
76
77Host: "download:00001234" request to send 0x1234 bytes of data
78
79Client: "DATA00001234" ready to accept data
80
81Host: < 0x1234 bytes > send data
82
83Client: "OKAY" success
84
85Host: "flash:bootloader" request to flash the data to the bootloader
86
87Client: "INFOerasing flash" indicate status / progress
88 "INFOwriting flash"
89 "OKAY" indicate success
90
91Host: "powerdown" send a command
92
93Client: "FAILunknown command" indicate failure
94
95
96Command 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
144Client Variables
145----------------
146
147The "getvar:%s" command is used to read client variables which
148represent various information about the device and the software
149on it.
150
151The 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
168Names starting with a lowercase character are reserved by this
169specification. OEM-specific names should not start with lowercase
170characters.