Home | History | Annotate | only in /system/core/fastboot
Up to higher level directory
NameDateSize
.clang-format21-Aug-2018251
Android.mk21-Aug-20183.6K
bootimg_utils.cpp21-Aug-20183.4K
bootimg_utils.h21-Aug-20181.9K
engine.cpp21-Aug-201810.9K
fastboot.cpp21-Aug-201869.2K
fastboot.h21-Aug-20184.2K
fs.cpp21-Aug-20187.5K
fs.h21-Aug-2018366
OWNERS21-Aug-201852
protocol.cpp21-Aug-201810.4K
README.md21-Aug-201819.6K
socket.cpp21-Aug-20189.3K
socket.h21-Aug-20185.7K
socket_mock.cpp21-Aug-20184.9K
socket_mock.h21-Aug-20183.5K
socket_test.cpp21-Aug-201813.7K
tcp.cpp21-Aug-20186.5K
tcp.h21-Aug-20182.2K
tcp_test.cpp21-Aug-20187.4K
transport.h21-Aug-20181.5K
udp.cpp21-Aug-201813.7K
udp.h21-Aug-20182.8K
udp_test.cpp21-Aug-201820.6K
usb.h21-Aug-20182K
usb_linux.cpp21-Aug-201814.3K
usb_osx.cpp21-Aug-201816.3K
usb_windows.cpp21-Aug-201811.2K
usbtest.cpp21-Aug-20185.8K
util.cpp21-Aug-20181.9K

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     upload             Read data from memory which was staged by the last
    130                        command, e.g. an oem command.  The client will reply
    131                        with "DATA%08x" if it is ready to send %08x bytes of
    132                        data.  If no data was staged in the last command,
    133                        the client must reply with "FAIL".  After the client
    134                        successfully sends %08x bytes, the client shall send
    135                        a single packet starting with "OKAY".  Clients
    136                        should not support "upload" unless it supports an
    137                        oem command that requires "upload" capabilities.
    138 
    139     verify:%08x        Send a digital signature to verify the downloaded
    140                        data.  Required if the bootloader is "secure"
    141                        otherwise "flash" and "boot" will be ignored.
    142 
    143     flash:%s           Write the previously downloaded image to the
    144                        named partition (if possible).
    145 
    146     erase:%s           Erase the indicated partition (clear to 0xFFs)
    147 
    148     boot               The previously downloaded data is a boot.img
    149                        and should be booted according to the normal
    150                        procedure for a boot.img
    151 
    152     continue           Continue booting as normal (if possible)
    153 
    154     reboot             Reboot the device.
    155 
    156     reboot-bootloader
    157                        Reboot back into the bootloader.
    158                        Useful for upgrade processes that require upgrading
    159                        the bootloader and then upgrading other partitions
    160                        using the new bootloader.
    161 
    162     powerdown          Power off the device.
    163 
    164 
    165 
    166 ## Client Variables
    167 
    168 The "getvar:%s" command is used to read client variables which
    169 represent various information about the device and the software
    170 on it.
    171 
    172 The various currently defined names are:
    173 
    174     version             Version of FastBoot protocol supported.
    175                         It should be "0.4" for this document.
    176 
    177     version-bootloader  Version string for the Bootloader.
    178 
    179     version-baseband    Version string of the Baseband Software
    180 
    181     product             Name of the product
    182 
    183     serialno            Product serial number
    184 
    185     secure              If the value is "yes", this is a secure
    186                         bootloader requiring a signature before
    187                         it will install or boot images.
    188 
    189 Names starting with a lowercase character are reserved by this
    190 specification.  OEM-specific names should not start with lowercase
    191 characters.
    192 
    193 
    194 ## TCP Protocol v1
    195 
    196 The TCP protocol is designed to be a simple way to use the fastboot protocol
    197 over ethernet if USB is not available.
    198 
    199 The device will open a TCP server on port 5554 and wait for a fastboot client
    200 to connect.
    201 
    202 ### Handshake
    203 Upon connecting, both sides will send a 4-byte handshake message to ensure they
    204 are speaking the same protocol. This consists of the ASCII characters "FB"
    205 followed by a 2-digit base-10 ASCII version number. For example, the version 1
    206 handshake message will be [FB01].
    207 
    208 If either side detects a malformed handshake, it should disconnect.
    209 
    210 The protocol version to use must be the minimum of the versions sent by each
    211 side; if either side cannot speak this protocol version, it should disconnect.
    212 
    213 ### Fastboot Data
    214 Once the handshake is complete, fastboot data will be sent as follows:
    215 
    216     [data_size][data]
    217 
    218 Where data\_size is an unsigned 8-byte big-endian binary value, and data is the
    219 fastboot packet. The 8-byte length is intended to provide future-proofing even
    220 though currently fastboot packets have a 4-byte maximum length.
    221 
    222 ### Example
    223 In this example the fastboot host queries the device for two variables,
    224 "version" and "none".
    225 
    226     Host    <connect to the device on port 5555>
    227     Host    FB01
    228     Device  FB01
    229     Host    [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version
    230     Device  [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
    231     Host    [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
    232     Device  [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable
    233     Host    <disconnect>
    234 
    235 
    236 ## UDP Protocol v1
    237 
    238 The UDP protocol is more complex than TCP since we must implement reliability
    239 to ensure no packets are lost, but the general concept of wrapping the fastboot
    240 protocol is the same.
    241 
    242 Overview:
    243   1. As with TCP, the device will listen on UDP port 5554.
    244   2. Maximum UDP packet size is negotiated during initialization.
    245   3. The host drives all communication; the device may only send a packet as a
    246      response to a host packet.
    247   4. If the host does not receive a response in 500ms it will re-transmit.
    248 
    249 ### UDP Packet format
    250 
    251     +----------+----+-------+-------+--------------------+
    252     | Byte #   | 0  |   1   | 2 - 3 |  4+                |
    253     +----------+----+-------+-------+--------------------+
    254     | Contents | ID | Flags | Seq # | Data               |
    255     +----------+----+-------+-------+--------------------+
    256 
    257     ID      Packet ID:
    258               0x00: Error.
    259               0x01: Query.
    260               0x02: Initialization.
    261               0x03: Fastboot.
    262 
    263             Packet types are described in more detail below.
    264 
    265     Flags   Packet flags: 0 0 0 0 0 0 0 C
    266               C=1 indicates a continuation packet; the data is too large and will
    267                   continue in the next packet.
    268 
    269               Remaining bits are reserved for future use and must be set to 0.
    270 
    271     Seq #   2-byte packet sequence number (big-endian). The host will increment
    272             this by 1 with each new packet, and the device must provide the
    273             corresponding sequence number in the response packets.
    274 
    275     Data    Packet data, not present in all packets.
    276 
    277 ### Packet Types
    278 
    279     Query
    280           The host sends a query packet once on startup to sync with the device.
    281           The host will not know the current sequence number, so the device must
    282           respond to all query packets regardless of sequence number.
    283 
    284           The response data field should contain a 2-byte big-endian value
    285           giving the next expected sequence number.
    286 
    287     Init
    288           The host sends an init packet once the query response is returned. The
    289           device must abort any in-progress operation and prepare for a new
    290           fastboot session. This message is meant to allow recovery if a
    291           previous session failed, e.g. due to network error or user Ctrl+C.
    292 
    293           The data field contains two big-endian 2-byte values, a protocol
    294           version and the max UDP packet size (including the 4-byte header).
    295           Both the host and device will send these values, and in each case
    296           the minimum of the sent values must be used.
    297 
    298     Fastboot
    299           These packets wrap the fastboot protocol. To write, the host will
    300           send a packet with fastboot data, and the device will reply with an
    301           empty packet as an ACK. To read, the host will send an empty packet,
    302           and the device will reply with fastboot data. The device may not give
    303           any data in the ACK packet.
    304 
    305     Error
    306           The device may respond to any packet with an error packet to indicate
    307           a UDP protocol error. The data field should contain an ASCII string
    308           describing the error. This is the only case where a device is allowed
    309           to return a packet ID other than the one sent by the host.
    310 
    311 ### Packet Size
    312 The maximum packet size is negotiated by the host and device in the Init packet.
    313 Devices must support at least 512-byte packets, but packet size has a direct
    314 correlation with download speed, so devices are strongly suggested to support at
    315 least 1024-byte packets. On a local network with 0.5ms round-trip time this will
    316 provide transfer rates of ~2MB/s. Over WiFi it will likely be significantly
    317 less.
    318 
    319 Query and Initialization packets, which are sent before size negotiation is
    320 complete, must always be 512 bytes or less.
    321 
    322 ### Packet Re-Transmission
    323 The host will re-transmit any packet that does not receive a response. The
    324 requirement of exactly one device response packet per host packet is how we
    325 achieve reliability and in-order delivery of packets.
    326 
    327 For simplicity of implementation, there is no windowing of multiple
    328 unacknowledged packets in this version of the protocol. The host will continue
    329 to send the same packet until a response is received. Windowing functionality
    330 may be implemented in future versions if necessary to increase performance.
    331 
    332 The first Query packet will only be attempted a small number of times, but
    333 subsequent packets will attempt to retransmit for at least 1 minute before
    334 giving up. This means a device may safely ignore host UDP packets for up to 1
    335 minute during long operations, e.g. writing to flash.
    336 
    337 ### Continuation Packets
    338 Any packet may set the continuation flag to indicate that the data is
    339 incomplete. Large data such as downloading an image may require many
    340 continuation packets. The receiver should respond to a continuation packet with
    341 an empty packet to acknowledge receipt. See examples below.
    342 
    343 ### Summary
    344 The host starts with a Query packet, then an Initialization packet, after
    345 which only Fastboot packets are sent. Fastboot packets may contain data from
    346 the host for writes, or from the device for reads, but not both.
    347 
    348 Given a next expected sequence number S and a received packet P, the device
    349 behavior should be:
    350 
    351     if P is a Query packet:
    352       * respond with a Query packet with S in the data field
    353     else if P has sequence == S:
    354       * process P and take any required action
    355       * create a response packet R with the same ID and sequence as P, containing
    356         any response data required.
    357       * transmit R and save it in case of re-transmission
    358       * increment S
    359     else if P has sequence == S - 1:
    360       * re-transmit the saved response packet R from above
    361     else:
    362       * ignore the packet
    363 
    364 ### Examples
    365 
    366 In the examples below, S indicates the starting client sequence number.
    367 
    368     Host                                    Client
    369     ======================================================================
    370     [Initialization, S = 0x55AA]
    371     [Host: version 1, 2048-byte packets. Client: version 2, 1024-byte packets.]
    372     [Resulting values to use: version = 1, max packet size = 1024]
    373     ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
    374     ----------------------------------------------------------------------
    375     0x01 0x00 0x00 0x00
    376                                             0x01 0x00 0x00 0x00 0x55 0xAA
    377     0x02 0x00 0x55 0xAA 0x00 0x01 0x08 0x00
    378                                             0x02 0x00 0x55 0xAA 0x00 0x02 0x04 0x00
    379 
    380     ----------------------------------------------------------------------
    381     [fastboot "getvar" commands, S = 0x0001]
    382     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    383     ----------------------------------------------------------------------
    384     0x03  0x00  0x00  0x01  getvar:version
    385                                             0x03  0x00  0x00  0x01
    386     0x03  0x00  0x00  0x02
    387                                             0x03  0x00  0x00  0x02  OKAY0.4
    388     0x03  0x00  0x00  0x03  getvar:none
    389                                             0x03  0x00  0x00  0x03
    390     0x03  0x00  0x00  0x04
    391                                             0x03  0x00  0x00  0x04  FAILUnknown var
    392 
    393     ----------------------------------------------------------------------
    394     [fastboot "INFO" responses, S = 0x0000]
    395     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    396     ----------------------------------------------------------------------
    397     0x03  0x00  0x00  0x00  <command>
    398                                             0x03  0x00  0x00  0x00
    399     0x03  0x00  0x00  0x01
    400                                             0x03  0x00  0x00  0x01  INFOWait1
    401     0x03  0x00  0x00  0x02
    402                                             0x03  0x00  0x00  0x02  INFOWait2
    403     0x03  0x00  0x00  0x03
    404                                             0x03  0x00  0x00  0x03  OKAY
    405 
    406     ----------------------------------------------------------------------
    407     [Chunking 2100 bytes of data, max packet size = 1024, S = 0xFFFF]
    408     ID   Flag SeqH SeqL Data                ID   Flag SeqH SeqL Data
    409     ----------------------------------------------------------------------
    410     0x03 0x00 0xFF 0xFF download:0000834
    411                                             0x03 0x00 0xFF 0xFF
    412     0x03 0x00 0x00 0x00
    413                                             0x03 0x00 0x00 0x00 DATA0000834
    414     0x03 0x01 0x00 0x01 <1020 bytes>
    415                                             0x03 0x00 0x00 0x01
    416     0x03 0x01 0x00 0x02 <1020 bytes>
    417                                             0x03 0x00 0x00 0x02
    418     0x03 0x00 0x00 0x03 <60 bytes>
    419                                             0x03 0x00 0x00 0x03
    420     0x03 0x00 0x00 0x04
    421                                             0x03 0x00 0x00 0x04 OKAY
    422 
    423     ----------------------------------------------------------------------
    424     [Unknown ID error, S = 0x0000]
    425     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    426     ----------------------------------------------------------------------
    427     0x10  0x00  0x00  0x00
    428                                             0x00  0x00  0x00  0x00  <error message>
    429 
    430     ----------------------------------------------------------------------
    431     [Host packet loss and retransmission, S = 0x0000]
    432     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    433     ----------------------------------------------------------------------
    434     0x03  0x00  0x00  0x00  getvar:version [lost]
    435     0x03  0x00  0x00  0x00  getvar:version [lost]
    436     0x03  0x00  0x00  0x00  getvar:version
    437                                             0x03  0x00  0x00  0x00
    438     0x03  0x00  0x00  0x01
    439                                             0x03  0x00  0x00  0x01  OKAY0.4
    440 
    441     ----------------------------------------------------------------------
    442     [Client packet loss and retransmission, S = 0x0000]
    443     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    444     ----------------------------------------------------------------------
    445     0x03  0x00  0x00  0x00  getvar:version
    446                                             0x03  0x00  0x00  0x00 [lost]
    447     0x03  0x00  0x00  0x00  getvar:version
    448                                             0x03  0x00  0x00  0x00 [lost]
    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 
    454     ----------------------------------------------------------------------
    455     [Host packet delayed, S = 0x0000]
    456     ID    Flags SeqH  SeqL  Data            ID    Flags SeqH  SeqL  Data
    457     ----------------------------------------------------------------------
    458     0x03  0x00  0x00  0x00  getvar:version [delayed]
    459     0x03  0x00  0x00  0x00  getvar:version
    460                                             0x03  0x00  0x00  0x00
    461     0x03  0x00  0x00  0x01
    462                                             0x03  0x00  0x00  0x01  OKAY0.4
    463     0x03  0x00  0x00  0x00  getvar:version [arrives late with old seq#, is ignored]
    464