doc/android/fastboot-protocol.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 FastBoot Version 0.4
   4 ====================
   5
   6 The fastboot protocol is a mechanism for communicating with bootloaders
   7 over USB.  It is designed to be very straightforward to implement, to
   8 allow it to be used across a wide range of devices and from hosts running
   9 Linux, Windows, or OSX.
  10
  11 Basic Requirements
  12 ------------------
  13
  14 * Two bulk endpoints (in, out) are required
  15 * Max packet size must be 64 bytes for full-speed and 512 bytes for
  16   high-speed USB
  17 * The protocol is entirely host-driven and synchronous (unlike the
  18   multi-channel, bi-directional, asynchronous ADB protocol)
  19
  20
  21 Transport and Framing
  22 ---------------------
  23
  24 1. Host sends a command, which is an ascii string in a single
  25    packet no greater than 64 bytes.
  26
  27 2. Client response with a single packet no greater than 64 bytes.
  28    The first four bytes of the response are "OKAY", "FAIL", "DATA",
  29    or "INFO".  Additional bytes may contain an (ascii) informative
  30    message.
  31
  32    a. INFO -> the remaining 60 bytes are an informative message
  33       (providing progress or diagnostic messages).  They should
  34       be displayed and then step #2 repeats
  35
  36    b. FAIL -> the requested command failed.  The remaining 60 bytes
  37       of the response (if present) provide a textual failure message
  38       to present to the user.  Stop.
  39
  40    c. OKAY -> the requested command completed successfully.  Go to #5
  41
  42    d. DATA -> the requested command is ready for the data phase.
  43       A DATA response packet will be 12 bytes long, in the form of
  44       DATA00000000 where the 8 digit hexidecimal number represents
  45       the total data size to transfer.
  46
  47 3. Data phase.  Depending on the command, the host or client will
  48    send the indicated amount of data.  Short packets are always
  49    acceptable and zero-length packets are ignored.  This phase continues
  50    until the client has sent or received the number of bytes indicated
  51    in the "DATA" response above.
  52
  53 4. Client responds with a single packet no greater than 64 bytes.
  54    The first four bytes of the response are "OKAY", "FAIL", or "INFO".
  55    Similar to #2:
  56
  57    a. INFO -> display the remaining 60 bytes and return to #4
  58
  59    b. FAIL -> display the remaining 60 bytes (if present) as a failure
  60       reason and consider the command failed.  Stop.
  61
  62    c. OKAY -> success.  Go to #5
  63
  64 5. Success.  Stop.
  65
  66
  67 Example Session
  68 ---------------
  69
  70 .. code-block:: none
  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:  "OKAY"                  return value ""
  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
 102 * Command parameters are indicated by printf-style escape sequences.
 103
 104 * Commands are ascii strings and sent without the quotes (which are
 105   for illustration only here) and without a trailing 0 byte.
 106
 107 * Commands that begin with a lowercase letter are reserved for this
 108   specification.  OEM-specific commands should not begin with a
 109   lowercase letter, to prevent incompatibilities with future specs.
 110
 111 .. code-block:: none
 112
 113  "getvar:%s"           Read a config/version variable from the bootloader.
 114                        The variable contents will be returned after the
 115                        OKAY response.
 116
 117  "download:%08x"       Write data to memory which will be later used
 118                        by "boot", "ramdisk", "flash", etc.  The client
 119                        will reply with "DATA%08x" if it has enough
 120                        space in RAM or "FAIL" if not.  The size of
 121                        the download is remembered.
 122
 123   "verify:%08x"        Send a digital signature to verify the downloaded
 124                        data.  Required if the bootloader is "secure"
 125                        otherwise "flash" and "boot" will be ignored.
 126
 127   "flash:%s"           Write the previously downloaded image to the
 128                        named partition (if possible).
 129
 130   "erase:%s"           Erase the indicated partition (clear to 0xFFs)
 131
 132   "boot"               The previously downloaded data is a boot.img
 133                        and should be booted according to the normal
 134                        procedure for a boot.img
 135
 136   "continue"           Continue booting as normal (if possible)
 137
 138   "reboot"             Reboot the device.
 139
 140   "reboot-bootloader"  Reboot back into the bootloader.
 141                        Useful for upgrade processes that require upgrading
 142                        the bootloader and then upgrading other partitions
 143                        using the new bootloader.
 144
 145   "powerdown"          Power off the device.
 146
 147 Client Variables
 148 ----------------
 149
 150 The ``getvar:%s`` command is used to read client variables which
 151 represent various information about the device and the software
 152 on it.
 153
 154 The various currently defined names are::
 155
 156   version             Version of FastBoot protocol supported.
 157                       It should be "0.3" for this document.
 158
 159   version-bootloader  Version string for the Bootloader.
 160
 161   version-baseband    Version string of the Baseband Software
 162
 163   product             Name of the product
 164
 165   serialno            Product serial number
 166
 167   secure              If the value is "yes", this is a secure
 168                       bootloader requiring a signature before
 169                       it will install or boot images.
 170
 171 Names starting with a lowercase character are reserved by this
 172 specification.  OEM-specific names should not start with lowercase
 173 characters.