1FastBoot  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.
171