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.