README.dfu 11 KB

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