Home | History | Annotate | only in /system/core/fastboot
Up to higher level directory
NameDateSize
.clang-format05-Oct-2017210
Android.mk05-Oct-20173.8K
bootimg_utils.cpp05-Oct-20173K
bootimg_utils.h05-Oct-20171.9K
engine.cpp05-Oct-201710K
fastboot.cpp05-Oct-201763.4K
fastboot.h05-Oct-20173.1K
fs.cpp05-Oct-20172.1K
fs.h05-Oct-2017359
protocol.cpp05-Oct-20177.8K
README.md05-Oct-201718.9K
socket.cpp05-Oct-20179.3K
socket.h05-Oct-20175.7K
socket_mock.cpp05-Oct-20174.9K
socket_mock.h05-Oct-20173.5K
socket_test.cpp05-Oct-201713.7K
tcp.cpp05-Oct-20176.5K
tcp.h05-Oct-20172.2K
tcp_test.cpp05-Oct-20177.4K
transport.h05-Oct-20171.5K
udp.cpp05-Oct-201713.7K
udp.h05-Oct-20172.8K
udp_test.cpp05-Oct-201720.6K
usb.h05-Oct-20172K
usb_linux.cpp05-Oct-201714.3K
usb_osx.cpp05-Oct-201716.6K
usb_windows.cpp05-Oct-201711.2K
usbtest.cpp05-Oct-20175.8K
util.cpp05-Oct-20172K

README.md

      1 Fastboot
      2 --------
      3 
      4 The fastboot protocol is a mechanism for communicating with bootloaders
      5 over USB or ethernet.  It is designed to be very straightforward to implement,
      6 to allow it to be used across a wide range of devices and from hosts running
      7 Linux, macOS, or Windows.
      8 
      9 
     10 ## Basic Requirements
     11 
     12 * USB
     13   * Two bulk endpoints (in, out) are required
     14   * Max packet size must be 64 bytes for full-speed, 512 bytes for
     15     high-speed and 1024 bytes for Super Speed USB.
     16   * The protocol is entirely host-driven and synchronous (unlike the
     17     multi-channel, bi-directional, asynchronous ADB protocol)
     18 
     19 * TCP or UDP
     20   * Device must be reachable via IP.
     21   * Device will act as the server, fastboot will be the client.
     22   * Fastboot data is wrapped in a simple protocol; see below for details.
     23 
     24 
     25 ## Transport and Framing
     26 
     27 1. Host sends a command, which is an ascii string in a single
     28    packet no greater than 64 bytes.
     29 
     30 2. Client response with a single packet no greater than 64 bytes.
     31    The first four bytes of the response are "OKAY", "FAIL", "DATA",
     32    or "INFO".  Additional bytes may contain an (ascii) informative
     33    message.
     34 
     35    a. INFO -> the remaining 60 bytes are an informative message
     36       (providing progress or diagnostic messages).  They should
     37       be displayed and then step #2 repeats
     38 
     39    b. FAIL -> the requested command failed.  The remaining 60 bytes
     40       of the response (if present) provide a textual failure message
     41       to present to the user.  Stop.
     42 
     43    c. OKAY -> the requested command completed successfully.  Go to #5
     44 
     45    d. DATA -> the requested command is ready for the data phase.
     46       A DATA response packet will be 12 bytes long, in the form of
     47       DATA00000000 where the 8 digit hexadecimal number represents
     48       the total data size to transfer.
     49 
     50 3. Data phase.  Depending on the command, the host or client will
     51    send the indicated amount of data.  Short packets are always
     52    acceptable and zero-length packets are ignored.  This phase continues
     53    until the client has sent or received the number of bytes indicated
     54    in the "DATA" response above.
     55 
     56 4. Client responds with a single packet no greater than 64 bytes.
     57    The first four bytes of the response are "OKAY", "FAIL", or "INFO".
     58    Similar to #2:
     59 
     60    a. INFO -> display the remaining 60 bytes and return to #4
     61 
     62    b. FAIL -> display the remaining 60 bytes (if present) as a failure
     63       reason and consider the command failed.  Stop.
     64 
     65    c. OKAY -> success.  Go to #5
     66 
     67 5. Success.  Stop.
     68 
     69 
     70 ## Example Session
     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:  "FAILUnknown variable"  getvar failure; see getvar details below
     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 
     99 ## Command Reference
    100 
    101 * Command parameters are indicated by printf-style escape sequences.
    102 
    103 * Commands are ascii strings and sent without the quotes (which are
    104   for illustration only here) and without a trailing 0 byte.
    105 
    106 * Commands that begin with a lowercase letter are reserved for this
    107   specification.  OEM-specific commands should not begin with a
    108   lowercase letter, to prevent incompatibilities with future specs.
    109 
    110 The various currently defined commands are:
    111 
    112     getvar:%s          Read a config/version variable from the bootloader.
    113                        The variable contents will be returned after the
    114                        OKAY response. If the variable is unknown, the bootloader
    115                        should return a FAIL response, optionally with an error
    116                        message.
    117 
    118                        Previous versions of this document indicated that getvar
    119                        should return an empty OKAY response for unknown
    120                        variables, so older devices might exhibit this behavior,
    121                        but new implementations should return FAIL instead.
    122 
    123     download:%08x      Write data to memory which will be later used
    124                        by "boot", "ramdisk", "flash", etc.  The client
    125                        will reply with "DATA%08x" if it has enough
    126                        space in RAM or "FAIL" if not.  The size of
    127                        the download is remembered.
    128 
    129     verify:%08x        Send a digital signature to verify the downloaded
    130                        data.  Required if the bootloader is "secure"
    131                        otherwise "flash" and "boot" will be ignored.
    132 
    133     flash:%s           Write the previously downloaded image to the
    134                        named partition (if possible).
    135 
    136     erase:%s           Erase the indicated partition (clear to 0xFFs)
    137 
    138     boot               The previously downloaded data is a boot.img
    139                        and should be booted according to the normal
    140                        procedure for a boot.img
    141 
    142     continue           Continue booting as normal (if possible)
    143 
    144     reboot             Reboot the device.
    145 
    146     reboot-bootloader
    147                        Reboot back into the bootloader.
    148                        Useful for upgrade processes that require upgrading
    149                        the bootloader and then upgrading other partitions
    150                        using the new bootloader.
    151 
    152     powerdown          Power off the device.
    153 
    154 
    155 
    156 ## Client Variables
    157 
    158 The "getvar:%s" command is used to read client variables which
    159 represent various information about the device and the software
    160 on it.
    161 
    162 The various currently defined names are:
    163 
    164     version             Version of FastBoot protocol supported.
    165                         It should be "0.4" for this document.
    166 
    167     version-bootloader  Version string for the Bootloader.
    168 
    169     version-baseband    Version string of the Baseband Software
    170 
    171     product             Name of the product
    172 
    173     serialno            Product serial number
    174 
    175     secure              If the value is "yes", this is a secure
    176                         bootloader requiring a signature before
    177                         it will install or boot images.
    178 
    179 Names starting with a lowercase character are reserved by this
    180 specification.  OEM-specific names should not start with lowercase
    181 characters.
    182 
    183 
    184 ## TCP Protocol v1
    185 
    186 The TCP protocol is designed to be a simple way to use the fastboot protocol
    187 over ethernet if USB is not available.
    188 
    189 The device will open a TCP server on port 5554 and wait for a fastboot client
    190 to connect.
    191 
    192 ### Handshake
    193 Upon connecting, both sides will send a 4-byte handshake message to ensure they
    194 are speaking the same protocol. This consists of the ASCII characters "FB"
    195 followed by a 2-digit base-10 ASCII version number. For example, the version 1
    196 handshake message will be [FB01].
    197 
    198 If either side detects a malformed handshake, it should disconnect.
    199 
    200 The protocol version to use must be the minimum of the versions sent by each
    201 side; if either side cannot speak this protocol version, it should disconnect.
    202 
    203 ### Fastboot Data
    204 Once the handshake is complete, fastboot data will be sent as follows:
    205 
    206     [data_size][data]
    207 
    208 Where data\_size is an unsigned 8-byte big-endian binary value, and data is the
    209 fastboot packet. The 8-byte length is intended to provide future-proofing even
    210 though currently fastboot packets have a 4-byte maximum length.
    211 
    212 ### Example
    213 In this example the fastboot host queries the device for two variables,
    214 "version" and "none".
    215 
    216     Host    <connect to the device on port 5555>
    217     Host    FB01
    218     Device  FB01
    219     Host    [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version
    220     Device  [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
    221     Host    [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
    222     Device  [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable
    223     Host    <disconnect>
    224 
    225 
    226 ## UDP Protocol v1
    227 
    228 The UDP protocol is more complex than TCP since we must implement reliability
    229 to ensure no packets are lost, but the general concept of wrapping the fastboot
    230 protocol is the same.
    231 
    232 Overview:
    233   1. As with TCP, the device will listen on UDP port 5554.
    234   2. Maximum UDP packet size is negotiated during initialization.
    235   3. The host drives all communication; the device may only send a packet as a
    236      response to a host packet.
    237   4. If the host does not receive a response in 500ms it will re-transmit.
    238 
    239 ### UDP Packet format
    240 
    241     +----------+----+-------+-------+--------------------+
    242     | Byte #   | 0  |   1   | 2 - 3 |  4+                |
    243     +----------+----+-------+-------+--------------------+
    244     | Contents | ID | Flags | Seq # | Data               |
    245     +----------+----+-------+-------+--------------------+
    246 
    247     ID      Packet ID:
    248               0x00: Error.
    249               0x01: Query.
    250               0x02: Initialization.
    251               0x03: Fastboot.
    252 
    253             Packet types are described in more detail below.
    254 
    255     Flags   Packet flags: 0 0 0 0 0 0 0 C
    256               C=1 indicates a continuation packet; the data is too large and will
    257                   continue in the next packet.
    258 
    259               Remaining bits are reserved for future use and must be set to 0.
    260 
    261     Seq #   2-byte packet sequence number (big-endian). The host will increment
    262             this by 1 with each new packet, and the device must provide the
    263             corresponding sequence number in the response packets.
    264 
    265     Data    Packet data, not present in all packets.
    266 
    267 ### Packet Types
    268 
    269     Query
    270           The host sends a query packet once on startup to sync with the device.
    271           The host will not know the current sequence number, so the device must
    272           respond to all query packets regardless of sequence number.
    273 
    274           The response data field should contain a 2-byte big-endian value
    275           giving the next expected sequence number.
    276 
    277     Init
    278           The host sends an init packet once the query response is returned. The
    279           device must abort any in-progress operation and prepare for a new
    280           fastboot session. This message is meant to allow recovery if a
    281           previous session failed, e.g. due to network error or user Ctrl+C.
    282 
    283           The data field contains two big-endian 2-byte values, a protocol
    284           version and the max UDP packet size (including the 4-byte header).
    285           Both the host and device will send these values, and in each case
    286           the minimum of the sent values must be used.
    287 
    288     Fastboot
    289           These packets wrap the fastboot protocol. To write, the host will
    290           send a packet with fastboot data, and the device will reply with an
    291           empty packet as an ACK. To read, the host will send an empty packet,
    292           and the device will reply with fastboot data. The device may not give
    293           any data in the ACK packet.
    294 
    295     Error
    296           The device may respond to any packet with an error packet to indicate
    297           a UDP protocol error. The data field should contain an ASCII string
    298           describing the error. This is the only case where a device is allowed
    299           to return a packet ID other than the one sent by the host.
    300 
    301 ### Packet Size
    302 The maximum packet size is negotiated by the host and device in the Init packet.
    303 Devices must support at least 512-byte packets, but packet size has a direct
    304 correlation with download speed, so devices are strongly suggested to support at
    305 least 1024-byte packets. On a local network with 0.5ms round-trip time this will
    306 provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly
    307 less.
    308 
    309 Query and Initialization packets, which are sent before size negotiation is
    310 complete, must always be 512 bytes or less.
    311 
    312 ### Packet Re-Transmission
    313 The host will re-transmit any packet that does not receive a response. The
    314 requirement of exactly one device response packet per host packet is how we
    315 achieve reliability and in-order delivery of packets.
    316 
    317 For simplicity of implementation, there is no windowing of multiple
    318 unacknowledged packets in this version of the protocol. The host will continue
    319 to send the same packet until a response is received. Windowing functionality
    320 may be implemented in future versions if necessary to increase performance.
    321 
    322 The first Query packet will only be attempted a small number of times, but
    323 subsequent packets will attempt to retransmit for at least 1 minute before
    324 giving up. This means a device may safely ignore host UDP packets for up to 1
    325 minute during long operations, e.g. writing to flash.
    326 
    327 ### Continuation Packets
    328 Any packet may set the continuation flag to indicate that the data is
    329 incomplete. Large data such as downloading an image may require many
    330 continuation packets. The receiver should respond to a continuation packet with
    331 an empty packet to acknowledge receipt. See examples below.
    332 
    333 ### Summary
    334 The host starts with a Query packet, then an Initialization packet, after
    335 which only Fastboot packets are sent. Fastboot packets may contain data from
    336 the host for writes, or from the device for reads, but not both.
    337 
    338 Given a next expected sequence number S and a received packet P, the device
    339 behavior should be:
    340 
    341     if P is a Query packet:
    342       * respond with a Query packet with S in the data field
    343     else if P has sequence == S:
    344       * process P and take any required action
    345       * create a response packet R with the same ID and sequence as P, containing
    346         any response data required.
    347       * transmit R and save it in case of re-transmission
    348       * increment S
    349     else if P has sequence == S - 1:
    350       * re-transmit the saved response packet R from above
    351     else:
    352       * ignore the packet
    353 
    354 ### Examples
    355 
    356 In the examples below, S indicates the starting client sequence number.
    357 
    358     Host                                    Client
    359     ======================================================================
    360     [Initialization, S = 0x55AA]
    361     [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.]
    362     [Resulting values to use: version = 1, max packet size = 1024]
    363     ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
    364     ----------------------------------------------------------------------
    365     0x01 0x00 0x00 0x00
    366                                             0x01 0x00 0x00 0x00 0x55 0xAA
    367     0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00
    368                                             0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00
    369 
    370     ----------------------------------------------------------------------
    371     [fastboot "getvar" commands, S = 0x0001]
    372     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    373     ----------------------------------------------------------------------
    374     0x03  0x00  0x00  0x01  getvar:version
    375                                             0x03  0x00  0x00  0x01
    376     0x03  0x00  0x00  0x02
    377                                             0x03  0x00  0x00  0x02  OKAY0.4
    378     0x03  0x00  0x00  0x03  getvar:none
    379                                             0x03  0x00  0x00  0x03
    380     0x03  0x00  0x00  0x04
    381                                             0x03  0x00  0x00  0x04  FAILUnknown var
    382 
    383     ----------------------------------------------------------------------
    384     [fastboot "INFO" responses, S = 0x0000]
    385     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    386     ----------------------------------------------------------------------
    387     0x03  0x00  0x00  0x00  <command>
    388                                             0x03  0x00  0x00  0x00
    389     0x03  0x00  0x00  0x01
    390                                             0x03  0x00  0x00  0x01  INFOWait1
    391     0x03  0x00  0x00  0x02
    392                                             0x03  0x00  0x00  0x02  INFOWait2
    393     0x03  0x00  0x00  0x03
    394                                             0x03  0x00  0x00  0x03  OKAY
    395 
    396     ----------------------------------------------------------------------
    397     [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF]
    398     ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
    399     ----------------------------------------------------------------------
    400     0x03 0x00 0xFF 0xFF download:0000834
    401                                             0x03 0x00 0xFF 0xFF
    402     0x03 0x00 0x00 0x00
    403                                             0x03 0x00 0x00 0x00 DATA0000834
    404     0x03 0x01 0x00 0x01 <1020 bytes>
    405                                             0x03 0x00 0x00 0x01
    406     0x03 0x01 0x00 0x02 <1020 bytes>
    407                                             0x03 0x00 0x00 0x02
    408     0x03 0x00 0x00 0x03 <60 bytes>
    409                                             0x03 0x00 0x00 0x03
    410     0x03 0x00 0x00 0x04
    411                                             0x03 0x00 0x00 0x04 OKAY
    412 
    413     ----------------------------------------------------------------------
    414     [Unknown ID error, S = 0x0000]
    415     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    416     ----------------------------------------------------------------------
    417     0x10  0x00  0x00  0x00
    418                                             0x00  0x00  0x00  0x00  <error message>
    419 
    420     ----------------------------------------------------------------------
    421     [Host packet loss and retransmission, S = 0x0000]
    422     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    423     ----------------------------------------------------------------------
    424     0x03  0x00  0x00  0x00  getvar:version [lost]
    425     0x03  0x00  0x00  0x00  getvar:version [lost]
    426     0x03  0x00  0x00  0x00  getvar:version
    427                                             0x03  0x00  0x00  0x00
    428     0x03  0x00  0x00  0x01
    429                                             0x03  0x00  0x00  0x01  OKAY0.4
    430 
    431     ----------------------------------------------------------------------
    432     [Client packet loss and retransmission, S = 0x0000]
    433     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    434     ----------------------------------------------------------------------
    435     0x03  0x00  0x00  0x00  getvar:version
    436                                             0x03  0x00  0x00  0x00 [lost]
    437     0x03  0x00  0x00  0x00  getvar:version
    438                                             0x03  0x00  0x00  0x00 [lost]
    439     0x03  0x00  0x00  0x00  getvar:version
    440                                             0x03  0x00  0x00  0x00
    441     0x03  0x00  0x00  0x01
    442                                             0x03  0x00  0x00  0x01  OKAY0.4
    443 
    444     ----------------------------------------------------------------------
    445     [Host packet delayed, S = 0x0000]
    446     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    447     ----------------------------------------------------------------------
    448     0x03  0x00  0x00  0x00  getvar:version [delayed]
    449     0x03  0x00  0x00  0x00  getvar:version
    450                                             0x03  0x00  0x00  0x00
    451     0x03  0x00  0x00  0x01
    452                                             0x03  0x00  0x00  0x01  OKAY0.4
    453     0x03  0x00  0x00  0x00  getvar:version [arrives late with old seq#, is ignored]
    454