1.. SPDX-License-Identifier: GPL-2.0+
2
3FastBoot Version 0.4
4====================
5
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
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
70.. code-block:: none
71
72    Host:    "getvar:version"        request version variable
73
74    Client:  "OKAY0.4"               return version "0.4"
75
76    Host:    "getvar:nonexistant"    request some undefined variable
77
78    Client:  "OKAY"                  return value ""
79
80    Host:    "download:00001234"     request to send 0x1234 bytes of data
81
82    Client:  "DATA00001234"          ready to accept data
83
84    Host:    < 0x1234 bytes >        send data
85
86    Client:  "OKAY"                  success
87
88    Host:    "flash:bootloader"      request to flash the data to the bootloader
89
90    Client:  "INFOerasing flash"     indicate status / progress
91             "INFOwriting flash"
92             "OKAY"                  indicate success
93
94    Host:    "powerdown"             send a command
95
96    Client:  "FAILunknown command"   indicate failure
97
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
111.. code-block:: none
112
113 "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
147  "ucmd"               execute any bootloader command and wait until it
148                       finishs.
149
150  "acmd"               execute any bootloader command, do not wait.
151
152Client Variables
153----------------
154
155The ``getvar:%s`` command is used to read client variables which
156represent various information about the device and the software
157on it.
158
159The various currently defined names are::
160
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.
179