Merge "Switch fastboot docs to markdown." am: e94deb3a am: b095bf0c

FastBoot  Version  0.4

----------------------

Fastboot

--------

The fastboot protocol is a mechanism for communicating with bootloaders

over USB or ethernet.  It is designed to be very straightforward to implement,

to allow it to be used across a wide range of devices and from hosts running

Linux, Windows, or OSX.

Linux, macOS, or Windows.

Basic Requirements

------------------

## Basic Requirements

* USB

  * Two bulk endpoints (in, out) are required

  * Fastboot data is wrapped in a simple protocol; see below for details.

Transport and Framing

---------------------

## Transport and Framing

1. Host sends a command, which is an ascii string in a single

   packet no greater than 64 bytes.

5. Success.  Stop.

Example Session

---------------

## Example Session

    Host:    "getvar:version"        request version variable

    Client:  "FAILunknown command"   indicate failure

Command Reference

-----------------

## Command Reference

* Command parameters are indicated by printf-style escape sequences.

  specification.  OEM-specific commands should not begin with a

  lowercase letter, to prevent incompatibilities with future specs.

 "getvar:%s"           Read a config/version variable from the bootloader.

The various currently defined commands are:

    getvar:%s          Read a config/version variable from the bootloader.

                       The variable contents will be returned after the

                       OKAY response. If the variable is unknown, the bootloader

                       should return a FAIL response, optionally with an error

                       variables, so older devices might exhibit this behavior,

                       but new implementations should return FAIL instead.

 "download:%08x"       Write data to memory which will be later used

    download:%08x      Write data to memory which will be later used

                       by "boot", "ramdisk", "flash", etc.  The client

                       will reply with "DATA%08x" if it has enough

                       space in RAM or "FAIL" if not.  The size of

                       the download is remembered.

  "verify:%08x"        Send a digital signature to verify the downloaded

    verify:%08x        Send a digital signature to verify the downloaded

                       data.  Required if the bootloader is "secure"

                       otherwise "flash" and "boot" will be ignored.

  "flash:%s"           Write the previously downloaded image to the

    flash:%s           Write the previously downloaded image to the

                       named partition (if possible).

  "erase:%s"           Erase the indicated partition (clear to 0xFFs)

    erase:%s           Erase the indicated partition (clear to 0xFFs)

  "boot"               The previously downloaded data is a boot.img

    boot               The previously downloaded data is a boot.img

                       and should be booted according to the normal

                       procedure for a boot.img

  "continue"           Continue booting as normal (if possible)

    continue           Continue booting as normal (if possible)

  "reboot"             Reboot the device.

    reboot             Reboot the device.

  "reboot-bootloader"  Reboot back into the bootloader.

    reboot-bootloader

                       Reboot back into the bootloader.

                       Useful for upgrade processes that require upgrading

                       the bootloader and then upgrading other partitions

                       using the new bootloader.

  "powerdown"          Power off the device.

    powerdown          Power off the device.

Client Variables

----------------

## Client Variables

The "getvar:%s" command is used to read client variables which

represent various information about the device and the software

characters.

TCP Protocol v1

---------------

## TCP Protocol v1

The TCP protocol is designed to be a simple way to use the fastboot protocol

over ethernet if USB is not available.

The device will open a TCP server on port 5554 and wait for a fastboot client

to connect.

-- Handshake --

### Handshake

Upon connecting, both sides will send a 4-byte handshake message to ensure they

are speaking the same protocol. This consists of the ASCII characters "FB"

followed by a 2-digit base-10 ASCII version number. For example, the version 1

The protocol version to use must be the minimum of the versions sent by each

side; if either side cannot speak this protocol version, it should disconnect.

-- Fastboot Data --

### Fastboot Data

Once the handshake is complete, fastboot data will be sent as follows:

    [data_size][data]

Where data_size is an unsigned 8-byte big-endian binary value, and data is the

Where data\_size is an unsigned 8-byte big-endian binary value, and data is the

fastboot packet. The 8-byte length is intended to provide future-proofing even

though currently fastboot packets have a 4-byte maximum length.

-- Example --

### Example

In this example the fastboot host queries the device for two variables,

"version" and "none".

    Host    <disconnect>

UDP Protocol v1

---------------

## UDP Protocol v1

The UDP protocol is more complex than TCP since we must implement reliability

to ensure no packets are lost, but the general concept of wrapping the fastboot

     response to a host packet.

  4. If the host does not receive a response in 500ms it will re-transmit.

-- UDP Packet format --

### UDP Packet format

    +----------+----+-------+-------+--------------------+

    | Byte #   | 0  |   1   | 2 - 3 |  4+                |

    +----------+----+-------+-------+--------------------+

    Data    Packet data, not present in all packets.

-- Packet Types --

Query     The host sends a query packet once on startup to sync with the device.

### Packet Types

    Query

          The host sends a query packet once on startup to sync with the device.

          The host will not know the current sequence number, so the device must

          respond to all query packets regardless of sequence number.

          The response data field should contain a 2-byte big-endian value

          giving the next expected sequence number.

Init      The host sends an init packet once the query response is returned. The

    Init

          The host sends an init packet once the query response is returned. The

          device must abort any in-progress operation and prepare for a new

          fastboot session. This message is meant to allow recovery if a

          previous session failed, e.g. due to network error or user Ctrl+C.

          Both the host and device will send these values, and in each case

          the minimum of the sent values must be used.

Fastboot  These packets wrap the fastboot protocol. To write, the host will

    Fastboot

          These packets wrap the fastboot protocol. To write, the host will

          send a packet with fastboot data, and the device will reply with an

          empty packet as an ACK. To read, the host will send an empty packet,

          and the device will reply with fastboot data. The device may not give

          any data in the ACK packet.

Error     The device may respond to any packet with an error packet to indicate

    Error

          The device may respond to any packet with an error packet to indicate

          a UDP protocol error. The data field should contain an ASCII string

          describing the error. This is the only case where a device is allowed

          to return a packet ID other than the one sent by the host.

-- Packet Size --

### Packet Size

The maximum packet size is negotiated by the host and device in the Init packet.

Devices must support at least 512-byte packets, but packet size has a direct

correlation with download speed, so devices are strongly suggested to support at

Query and Initialization packets, which are sent before size negotiation is

complete, must always be 512 bytes or less.

-- Packet Re-Transmission --

### Packet Re-Transmission

The host will re-transmit any packet that does not receive a response. The

requirement of exactly one device response packet per host packet is how we

achieve reliability and in-order delivery of packets.

giving up. This means a device may safely ignore host UDP packets for up to 1

minute during long operations, e.g. writing to flash.

-- Continuation Packets --

### Continuation Packets

Any packet may set the continuation flag to indicate that the data is

incomplete. Large data such as downloading an image may require many

continuation packets. The receiver should respond to a continuation packet with

an empty packet to acknowledge receipt. See examples below.

-- Summary --

### Summary

The host starts with a Query packet, then an Initialization packet, after

which only Fastboot packets are sent. Fastboot packets may contain data from

the host for writes, or from the device for reads, but not both.

Given a next expected sequence number S and a received packet P, the device

behavior should be:

    if P is a Query packet:

      * respond with a Query packet with S in the data field

    else if P has sequence == S:

    else:

      * ignore the packet

-- Examples --

### Examples

In the examples below, S indicates the starting client sequence number.

    Host                                    Client