dfu.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. Device Firmware Upgrade (DFU)
  3. =============================
  4. Overview
  5. --------
  6. The Device Firmware Upgrade (DFU) allows to download and upload firmware
  7. to/from U-Boot connected over USB.
  8. U-boot follows the Universal Serial Bus Device Class Specification for
  9. Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).
  10. U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
  11. (cmd/dfu.c / CONFIG_CMD_DFU) based on:
  12. - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
  13. USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
  14. - The access to mediums is done in DFU backends (driver/dfu)
  15. Today the supported DFU backends are:
  16. - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT)
  17. - NAND
  18. - RAM
  19. - SF (serial flash)
  20. - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
  21. - virtual
  22. These DFU backends are also used by
  23. - the dfutftp (see README.dfutftp)
  24. - the thordown command (cmd/thordown.c and gadget/f_thor.c)
  25. The "virtual" backend is a generic DFU backend to support a board specific
  26. target (for example OTP), only based on the weak functions:
  27. - dfu_write_medium_virt
  28. - dfu_get_medium_size_virt
  29. - dfu_read_medium_virt
  30. Configuration Options
  31. ---------------------
  32. The following configuration option are relevant for device firmware upgrade:
  33. * CONFIG_DFU
  34. * CONFIG_DFU_OVER_USB
  35. * CONFIG_DFU_MMC
  36. * CONFIG_DFU_MTD
  37. * CONFIG_DFU_NAND
  38. * CONFIG_DFU_RAM
  39. * CONFIG_DFU_SF
  40. * CONFIG_DFU_SF_PART
  41. * CONFIG_DFU_TIMEOUT
  42. * CONFIG_DFU_VIRTUAL
  43. * CONFIG_CMD_DFU
  44. Environment variables
  45. ---------------------
  46. The dfu command uses 3 environments variables:
  47. dfu_alt_info
  48. The DFU setting for the USB download gadget with a semicolon separated
  49. string of information on each alternate::
  50. dfu_alt_info="<alt1>;<alt2>;....;<altN>"
  51. When several devices are used, the format is:
  52. - <interface> <dev>'='alternate list (';' separated)
  53. - each interface is separated by '&'::
  54. dfu_alt_info=\
  55. "<interface1> <dev1>=<alt1>;....;<altN>&"\
  56. "<interface2> <dev2>=<altN+1>;....;<altM>&"\
  57. ...\
  58. "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
  59. dfu_bufsiz
  60. size of the DFU buffer, when absent, defaults to
  61. CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)
  62. dfu_hash_algo
  63. name of the hash algorithm to use
  64. Commands
  65. --------
  66. dfu <USB_controller> [<interface> <dev>] list
  67. list the alternate device defined in *dfu_alt_info*
  68. dfu <USB_controller> [<interface> <dev>] [<timeout>]
  69. start the dfu stack on the USB instance with the selected medium
  70. backend and use the *dfu_alt_info* variable to configure the
  71. alternate setting and link each one with the medium
  72. The dfu command continue until receive a ^C in console or
  73. a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option
  74. is enabled and <timeout> parameter is present in the command line,
  75. the DFU operation will be aborted automatically after <timeout>
  76. seconds of waiting remote to initiate DFU session.
  77. The possible values of <interface> are (with <USB controller> = 0 in the dfu
  78. command example)
  79. mmc
  80. for eMMC and SD card::
  81. dfu 0 mmc <dev>
  82. each element in *dfu_alt_info* being
  83. * <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device
  84. * <name> part <dev> <part_id> [mmcpart <num>] raw access to partition
  85. * <name> fat <dev> <part_id> [mmcpart <num>] file in FAT partition
  86. * <name> ext4 <dev> <part_id> [mmcpart <num>] file in EXT4 partition
  87. * <name> skip 0 0 ignore flashed data
  88. * <name> script 0 0 execute commands in shell
  89. with
  90. partid
  91. being the GPT or DOS partition index,
  92. num
  93. being the eMMC hardware partition number.
  94. A value of environment variable *dfu_alt_info* for eMMC could be::
  95. u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1
  96. A value of environment variable *dfu_alt_info* for SD card could be::
  97. u-boot raw 0x80 0x800;uImage ext4 0 2
  98. If don't want to flash given image file to storage, use "skip" type
  99. entity.
  100. - It can be used to protect flashing wrong image for the specific board.
  101. - Especailly, this layout will be useful when thor protocol is used,
  102. which performs flashing in batch mode, where more than one file is
  103. processed.
  104. For example, if one makes a single tar file with support for the two
  105. boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one
  106. can use it to flash a proper u-boot image on both without a failure::
  107. u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0
  108. When flashing new system image requires do some more complex things
  109. than just writing data to the storage medium, one can use 'script'
  110. type. Data written to such entity will be executed as a command list
  111. in the u-boot's shell. This for example allows to re-create partition
  112. layout and even set new *dfu_alt_info* for the newly created paritions.
  113. Such script would look like::
  114. setenv dfu_alt_info ...
  115. setenv mbr_parts ...
  116. mbr write ...
  117. Please note that this means that user will be able to execute any
  118. arbitrary commands just like in the u-boot's shell.
  119. nand
  120. raw slc nand device::
  121. dfu 0 nand <dev>
  122. each element in *dfu_alt_info* being either of
  123. * <name> raw <offset> <size> raw access to mmc device
  124. * <name> part <dev> <part_id> raw acces to partition
  125. * <name> partubi <dev> <part_id> raw acces to ubi partition
  126. with
  127. partid
  128. is the MTD partition index
  129. ram
  130. raw access to ram::
  131. dfu 0 ram <dev>
  132. dev
  133. is not used for RAM target
  134. each element in *dfu_alt_info* being::
  135. <name> ram <offset> <size> raw access to ram
  136. sf
  137. serial flash : NOR::
  138. cmd: dfu 0 sf <dev>
  139. each element in *dfu_alt_info* being either of:
  140. * <name> raw <offset> <size> raw access to sf device
  141. * <name> part <dev> <part_id> raw acces to partition
  142. * <name> partubi <dev> <part_id> raw acces to ubi partition
  143. with
  144. partid
  145. is the MTD partition index
  146. mtd
  147. all MTD device: NAND, SPI-NOR, SPI-NAND,...::
  148. cmd: dfu 0 mtd <dev>
  149. with
  150. dev
  151. the mtd identifier as defined in mtd command
  152. (nand0, nor0, spi-nand0,...)
  153. each element in *dfu_alt_info* being either of:
  154. * <name> raw <offset> <size> forraw access to mtd device
  155. * <name> part <dev> <part_id> for raw acces to partition
  156. * <name> partubi <dev> <part_id> for raw acces to ubi partition
  157. with
  158. partid
  159. is the MTD partition index
  160. virt
  161. virtual flash back end for DFU
  162. ::
  163. cmd: dfu 0 virt <dev>
  164. each element in *dfu_alt_info* being:
  165. * <name>
  166. <interface> and <dev> are absent, the dfu command to use multiple devices::
  167. cmd: dfu 0 list
  168. cmd: dfu 0
  169. *dfu_alt_info* variable provides the list of <interface> <dev> with
  170. alternate list separated by '&' with the same format for each <alt>::
  171. mmc <dev>=<alt1>;....;<altN>
  172. nand <dev>=<alt1>;....;<altN>
  173. ram <dev>=<alt1>;....;<altN>
  174. sf <dev>=<alt1>;....;<altN>
  175. mtd <dev>=<alt1>;....;<altN>
  176. virt <dev>=<alt1>;....;<altN>
  177. Callbacks
  178. ---------
  179. The weak callback functions can be implemented to manage specific behavior
  180. dfu_initiated_callback
  181. called when the DFU transaction is started, used to initiase the device
  182. dfu_flush_callback
  183. called at the end of the DFU write after DFU manifestation, used to manage
  184. the device when DFU transaction is closed
  185. Host tools
  186. ----------
  187. When U-Boot runs the dfu stack, the DFU host tools can be used
  188. to send/receive firmwares on each configurated alternate.
  189. For example dfu-util is a host side implementation of the DFU 1.1
  190. specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
  191. Usage
  192. -----
  193. Example 1: firmware located in eMMC or SD card, with:
  194. - alternate 1 (alt=1) for SPL partition (GPT partition 1)
  195. - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
  196. The U-Boot configuration is::
  197. U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
  198. U-Boot> dfu 0 mmc 0 list
  199. DFU alt settings list:
  200. dev: eMMC alt: 0 name: spl layout: RAW_ADDR
  201. dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
  202. Boot> dfu 0 mmc 0
  203. On the Host side:
  204. list the available alternate setting::
  205. $> dfu-util -l
  206. dfu-util 0.9
  207. Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
  208. Copyright 2010-2016 Tormod Volden and Stefan Schmidt
  209. This program is Free Software and has ABSOLUTELY NO WARRANTY
  210. Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
  211. Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
  212. alt=1, name="u-boot", serial="003A00203438510D36383238"
  213. Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
  214. alt=0, name="spl", serial="003A00203438510D36383238"
  215. To download to U-Boot, use -D option
  216. $> dfu-util -a 0 -D u-boot-spl.bin
  217. $> dfu-util -a 1 -D u-boot.bin
  218. To upload from U-Boot, use -U option
  219. $> dfu-util -a 0 -U u-boot-spl.bin
  220. $> dfu-util -a 1 -U u-boot.bin
  221. To request a DFU detach and reset the USB connection:
  222. $> dfu-util -a 0 -e -R
  223. Example 2: firmware located in NOR (sf) and NAND, with:
  224. - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
  225. - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
  226. - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
  227. - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
  228. ::
  229. U-Boot> env set dfu_alt_info \
  230. "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
  231. u-boot-env part 0 3&nand 0=UBI partubi 0,1"
  232. U-Boot> dfu 0 list
  233. DFU alt settings list:
  234. dev: SF alt: 0 name: spl layout: RAW_ADDR
  235. dev: SF alt: 1 name: ssbl layout: RAW_ADDR
  236. dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
  237. dev: NAND alt: 3 name: UBI layout: RAW_ADDR
  238. U-Boot> dfu 0
  239. ::
  240. $> dfu-util -l
  241. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  242. intf=0, alt=3, name="UBI", serial="002700333338511934383330"
  243. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  244. intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
  245. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  246. intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
  247. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  248. intf=0, alt=0, name="spl", serial="002700333338511934383330"
  249. Same example with MTD backend
  250. ::
  251. U-Boot> env set dfu_alt_info \
  252. "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
  253. "mtd nand0=UBI partubi 1"
  254. U-Boot> dfu 0 list
  255. using id 'nor0,0'
  256. using id 'nor0,1'
  257. using id 'nor0,2'
  258. using id 'nand0,0'
  259. DFU alt settings list:
  260. dev: MTD alt: 0 name: spl layout: RAW_ADDR
  261. dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
  262. dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
  263. dev: MTD alt: 3 name: UBI layout: RAW_ADDR
  264. Example 3
  265. firmware located in SD Card (mmc) and virtual partition on OTP and PMIC not
  266. volatile memory
  267. - alternate 1 (alt=1) for scard
  268. - alternate 2 (alt=2) for OTP (virtual)
  269. - alternate 3 (alt=3) for PMIC NVM (virtual)
  270. ::
  271. U-Boot> env set dfu_alt_info \
  272. "mmc 0=sdcard raw 0 0x100000&"\
  273. "virt 0=otp" \
  274. "virt 1=pmic"
  275. ::
  276. U-Boot> dfu 0 list
  277. DFU alt settings list:
  278. dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
  279. dev: VIRT alt: 1 name: otp layout: RAW_ADDR
  280. dev: VIRT alt: 2 name: pmic layout: RAW_ADDR