blob: e8cbd7f24ea0edc0b233119bf5f6629293a8c376 [file] [log] [blame]
Sam Protsenko586a1bf2020-01-24 17:53:44 +02001.. SPDX-License-Identifier: GPL-2.0+
2
3FastBoot Version 0.4
4====================
Sebastian Siewior3aab70a2014-05-05 15:08:10 -05005
6The fastboot protocol is a mechanism for communicating with bootloaders
7over USB. It is designed to be very straightforward to implement, to
8allow it to be used across a wide range of devices and from hosts running
9Linux, Windows, or OSX.
10
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050011Basic 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
Sam Protsenko586a1bf2020-01-24 17:53:44 +020070.. code-block:: none
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050071
Sam Protsenko586a1bf2020-01-24 17:53:44 +020072 Host: "getvar:version" request version variable
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050073
Sam Protsenko586a1bf2020-01-24 17:53:44 +020074 Client: "OKAY0.4" return version "0.4"
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050075
Sam Protsenko586a1bf2020-01-24 17:53:44 +020076 Host: "getvar:nonexistant" request some undefined variable
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050077
Sam Protsenko586a1bf2020-01-24 17:53:44 +020078 Client: "OKAY" return value ""
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050079
Sam Protsenko586a1bf2020-01-24 17:53:44 +020080 Host: "download:00001234" request to send 0x1234 bytes of data
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050081
Sam Protsenko586a1bf2020-01-24 17:53:44 +020082 Client: "DATA00001234" ready to accept data
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050083
Sam Protsenko586a1bf2020-01-24 17:53:44 +020084 Host: < 0x1234 bytes > send data
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050085
Sam Protsenko586a1bf2020-01-24 17:53:44 +020086 Client: "OKAY" success
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050087
Sam Protsenko586a1bf2020-01-24 17:53:44 +020088 Host: "flash:bootloader" request to flash the data to the bootloader
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050089
Sam Protsenko586a1bf2020-01-24 17:53:44 +020090 Client: "INFOerasing flash" indicate status / progress
91 "INFOwriting flash"
92 "OKAY" indicate success
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050093
Sam Protsenko586a1bf2020-01-24 17:53:44 +020094 Host: "powerdown" send a command
95
96 Client: "FAILunknown command" indicate failure
Sebastian Siewior3aab70a2014-05-05 15:08:10 -050097
98
99Command Reference
100-----------------
101
102* Command parameters are indicated by printf-style escape sequences.
103
104* Commands are ascii strings and sent without the quotes (which are
105 for illustration only here) and without a trailing 0 byte.
106
107* Commands that begin with a lowercase letter are reserved for this
108 specification. OEM-specific commands should not begin with a
109 lowercase letter, to prevent incompatibilities with future specs.
110
Sam Protsenko586a1bf2020-01-24 17:53:44 +0200111.. code-block:: none
112
Sebastian Siewior3aab70a2014-05-05 15:08:10 -0500113 "getvar:%s" Read a config/version variable from the bootloader.
114 The variable contents will be returned after the
115 OKAY response.
116
117 "download:%08x" Write data to memory which will be later used
118 by "boot", "ramdisk", "flash", etc. The client
119 will reply with "DATA%08x" if it has enough
120 space in RAM or "FAIL" if not. The size of
121 the download is remembered.
122
123 "verify:%08x" Send a digital signature to verify the downloaded
124 data. Required if the bootloader is "secure"
125 otherwise "flash" and "boot" will be ignored.
126
127 "flash:%s" Write the previously downloaded image to the
128 named partition (if possible).
129
130 "erase:%s" Erase the indicated partition (clear to 0xFFs)
131
132 "boot" The previously downloaded data is a boot.img
133 and should be booted according to the normal
134 procedure for a boot.img
135
136 "continue" Continue booting as normal (if possible)
137
138 "reboot" Reboot the device.
139
140 "reboot-bootloader" Reboot back into the bootloader.
141 Useful for upgrade processes that require upgrading
142 the bootloader and then upgrading other partitions
143 using the new bootloader.
144
145 "powerdown" Power off the device.
146
Heiko Schocherbc820d52021-02-10 09:29:03 +0100147 "ucmd" execute any bootloader command and wait until it
148 finishs.
149
150 "acmd" execute any bootloader command, do not wait.
151
Sebastian Siewior3aab70a2014-05-05 15:08:10 -0500152Client Variables
153----------------
154
Sam Protsenko586a1bf2020-01-24 17:53:44 +0200155The ``getvar:%s`` command is used to read client variables which
Sebastian Siewior3aab70a2014-05-05 15:08:10 -0500156represent various information about the device and the software
157on it.
158
Sam Protsenko586a1bf2020-01-24 17:53:44 +0200159The various currently defined names are::
Sebastian Siewior3aab70a2014-05-05 15:08:10 -0500160
161 version Version of FastBoot protocol supported.
162 It should be "0.3" for this document.
163
164 version-bootloader Version string for the Bootloader.
165
166 version-baseband Version string of the Baseband Software
167
168 product Name of the product
169
170 serialno Product serial number
171
172 secure If the value is "yes", this is a secure
173 bootloader requiring a signature before
174 it will install or boot images.
175
176Names starting with a lowercase character are reserved by this
177specification. OEM-specific names should not start with lowercase
178characters.