fastboot-protocol.rst 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. FastBoot Version 0.4
  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. Basic Requirements
  9. ------------------
  10. * Two bulk endpoints (in, out) are required
  11. * Max packet size must be 64 bytes for full-speed and 512 bytes for
  12. high-speed USB
  13. * The protocol is entirely host-driven and synchronous (unlike the
  14. multi-channel, bi-directional, asynchronous ADB protocol)
  15. Transport and Framing
  16. ---------------------
  17. 1. Host sends a command, which is an ascii string in a single
  18. packet no greater than 64 bytes.
  19. 2. Client response with a single packet no greater than 64 bytes.
  20. The first four bytes of the response are "OKAY", "FAIL", "DATA",
  21. or "INFO". Additional bytes may contain an (ascii) informative
  22. message.
  23. a. INFO -> the remaining 60 bytes are an informative message
  24. (providing progress or diagnostic messages). They should
  25. be displayed and then step #2 repeats
  26. b. FAIL -> the requested command failed. The remaining 60 bytes
  27. of the response (if present) provide a textual failure message
  28. to present to the user. Stop.
  29. c. OKAY -> the requested command completed successfully. Go to #5
  30. d. DATA -> the requested command is ready for the data phase.
  31. A DATA response packet will be 12 bytes long, in the form of
  32. DATA00000000 where the 8 digit hexidecimal number represents
  33. the total data size to transfer.
  34. 3. Data phase. Depending on the command, the host or client will
  35. send the indicated amount of data. Short packets are always
  36. acceptable and zero-length packets are ignored. This phase continues
  37. until the client has sent or received the number of bytes indicated
  38. in the "DATA" response above.
  39. 4. Client responds with a single packet no greater than 64 bytes.
  40. The first four bytes of the response are "OKAY", "FAIL", or "INFO".
  41. Similar to #2:
  42. a. INFO -> display the remaining 60 bytes and return to #4
  43. b. FAIL -> display the remaining 60 bytes (if present) as a failure
  44. reason and consider the command failed. Stop.
  45. c. OKAY -> success. Go to #5
  46. 5. Success. Stop.
  47. Example Session
  48. ---------------
  49. .. code-block:: none
  50. Host: "getvar:version" request version variable
  51. Client: "OKAY0.4" return version "0.4"
  52. Host: "getvar:nonexistant" request some undefined variable
  53. Client: "OKAY" return value ""
  54. Host: "download:00001234" request to send 0x1234 bytes of data
  55. Client: "DATA00001234" ready to accept data
  56. Host: < 0x1234 bytes > send data
  57. Client: "OKAY" success
  58. Host: "flash:bootloader" request to flash the data to the bootloader
  59. Client: "INFOerasing flash" indicate status / progress
  60. "INFOwriting flash"
  61. "OKAY" indicate success
  62. Host: "powerdown" send a command
  63. Client: "FAILunknown command" indicate failure
  64. Command Reference
  65. -----------------
  66. * Command parameters are indicated by printf-style escape sequences.
  67. * Commands are ascii strings and sent without the quotes (which are
  68. for illustration only here) and without a trailing 0 byte.
  69. * Commands that begin with a lowercase letter are reserved for this
  70. specification. OEM-specific commands should not begin with a
  71. lowercase letter, to prevent incompatibilities with future specs.
  72. .. code-block:: none
  73. "getvar:%s" Read a config/version variable from the bootloader.
  74. The variable contents will be returned after the
  75. OKAY response.
  76. "download:%08x" Write data to memory which will be later used
  77. by "boot", "ramdisk", "flash", etc. The client
  78. will reply with "DATA%08x" if it has enough
  79. space in RAM or "FAIL" if not. The size of
  80. the download is remembered.
  81. "verify:%08x" Send a digital signature to verify the downloaded
  82. data. Required if the bootloader is "secure"
  83. otherwise "flash" and "boot" will be ignored.
  84. "flash:%s" Write the previously downloaded image to the
  85. named partition (if possible).
  86. "erase:%s" Erase the indicated partition (clear to 0xFFs)
  87. "boot" The previously downloaded data is a boot.img
  88. and should be booted according to the normal
  89. procedure for a boot.img
  90. "continue" Continue booting as normal (if possible)
  91. "reboot" Reboot the device.
  92. "reboot-bootloader" Reboot back into the bootloader.
  93. Useful for upgrade processes that require upgrading
  94. the bootloader and then upgrading other partitions
  95. using the new bootloader.
  96. "powerdown" Power off the device.
  97. "ucmd" execute any bootloader command and wait until it
  98. finishs.
  99. "acmd" execute any bootloader command, do not wait.
  100. Client Variables
  101. ----------------
  102. The ``getvar:%s`` command is used to read client variables which
  103. represent various information about the device and the software
  104. on it.
  105. The various currently defined names are::
  106. version Version of FastBoot protocol supported.
  107. It should be "0.3" for this document.
  108. version-bootloader Version string for the Bootloader.
  109. version-baseband Version string of the Baseband Software
  110. product Name of the product
  111. serialno Product serial number
  112. secure If the value is "yes", this is a secure
  113. bootloader requiring a signature before
  114. it will install or boot images.
  115. Names starting with a lowercase character are reserved by this
  116. specification. OEM-specific names should not start with lowercase
  117. characters.