1 .. SPDX-License-Identifier: GPL-2.0+
6 The fastboot protocol is a mechanism for communicating with bootloaders
7 over USB. It is designed to be very straightforward to implement, to
8 allow it to be used across a wide range of devices and from hosts running
9 Linux, Windows, or OSX.
14 * Two bulk endpoints (in, out) are required
15 * Max packet size must be 64 bytes for full-speed and 512 bytes for
17 * The protocol is entirely host-driven and synchronous (unlike the
18 multi-channel, bi-directional, asynchronous ADB protocol)
24 1. Host sends a command, which is an ascii string in a single
25 packet no greater than 64 bytes.
27 2. 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
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
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.
40 c. OKAY -> the requested command completed successfully. Go to #5
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.
47 3. 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.
53 4. Client responds with a single packet no greater than 64 bytes.
54 The first four bytes of the response are "OKAY", "FAIL", or "INFO".
57 a. INFO -> display the remaining 60 bytes and return to #4
59 b. FAIL -> display the remaining 60 bytes (if present) as a failure
60 reason and consider the command failed. Stop.
62 c. OKAY -> success. Go to #5
72 Host: "getvar:version" request version variable
74 Client: "OKAY0.4" return version "0.4"
76 Host: "getvar:nonexistant" request some undefined variable
78 Client: "OKAY" return value ""
80 Host: "download:00001234" request to send 0x1234 bytes of data
82 Client: "DATA00001234" ready to accept data
84 Host: < 0x1234 bytes > send data
86 Client: "OKAY" success
88 Host: "flash:bootloader" request to flash the data to the bootloader
90 Client: "INFOerasing flash" indicate status / progress
92 "OKAY" indicate success
94 Host: "powerdown" send a command
96 Client: "FAILunknown command" indicate failure
102 * Command parameters are indicated by printf-style escape sequences.
104 * Commands are ascii strings and sent without the quotes (which are
105 for illustration only here) and without a trailing 0 byte.
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.
113 "getvar:%s" Read a config/version variable from the bootloader.
114 The variable contents will be returned after the
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.
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.
127 "flash:%s" Write the previously downloaded image to the
128 named partition (if possible).
130 "erase:%s" Erase the indicated partition (clear to 0xFFs)
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
136 "continue" Continue booting as normal (if possible)
138 "reboot" Reboot the device.
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.
145 "powerdown" Power off the device.
147 "ucmd" execute any bootloader command and wait until it
150 "acmd" execute any bootloader command, do not wait.
155 The ``getvar:%s`` command is used to read client variables which
156 represent various information about the device and the software
159 The various currently defined names are::
161 version Version of FastBoot protocol supported.
162 It should be "0.3" for this document.
164 version-bootloader Version string for the Bootloader.
166 version-baseband Version string of the Baseband Software
168 product Name of the product
170 serialno Product serial number
172 secure If the value is "yes", this is a secure
173 bootloader requiring a signature before
174 it will install or boot images.
176 Names starting with a lowercase character are reserved by this
177 specification. OEM-specific names should not start with lowercase