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