README.dfu 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  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)
  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_VIRTUAL
  38. CONFIG_CMD_DFU
  39. Environment variables:
  40. the dfu command use 3 environments variables:
  41. "dfu_alt_info" : the DFU setting for the USB download gadget with a comma
  42. separated string of information on each alternate:
  43. dfu_alt_info="<alt1>;<alt2>;....;<altN>"
  44. when only several device are used, the format is:
  45. - <interface> <dev>'='alternate list (';' separated)
  46. - each interface is separated by '&'
  47. dfu_alt_info=\
  48. "<interface1> <dev1>=<alt1>;....;<altN>&"\
  49. "<interface2> <dev2>=<altN+1>;....;<altM>&"\
  50. ...\
  51. "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
  52. "dfu_bufsiz" : size of the DFU buffer, when absent, use
  53. CONFIG_SYS_DFU_DATA_BUF_SIZE (8MiB by default)
  54. "dfu_hash_algo" : name of the hash algorithm to use
  55. Commands:
  56. dfu <USB_controller> [<interface> <dev>] list
  57. list the alternate device defined in "dfu_alt_info"
  58. dfu <USB_controller> [<interface> <dev>]
  59. start the dfu stack on the USB instance with the selected medium
  60. backend and use the "dfu_alt_info" variable to configure the
  61. alternate setting and link each one with the medium
  62. The dfu command continue until receive a ^C in console or
  63. a DFU detach transaction from HOST.
  64. The possible values of <interface> are :
  65. (with <USB controller> = 0 in the dfu command example)
  66. "mmc" (for eMMC and SD card)
  67. cmd: dfu 0 mmc <dev>
  68. each element in "dfu_alt_info" =
  69. <name> raw <offset> <size> raw access to mmc device
  70. <name> part <dev> <part_id> raw acces to partition
  71. <name> fat <dev> <part_id> file in FAT partition
  72. <name> ext4 <dev> <part_id> file in EXT4 partition
  73. with <partid> is the GPT or DOS partition index
  74. "nand" (raw slc nand device)
  75. cmd: dfu 0 nand <dev>
  76. each element in "dfu_alt_info" =
  77. <name> raw <offset> <size> raw access to mmc device
  78. <name> part <dev> <part_id> raw acces to partition
  79. <name> partubi <dev> <part_id> raw acces to ubi partition
  80. with <partid> is the MTD partition index
  81. "ram"
  82. cmd: dfu 0 ram <dev>
  83. (<dev> is not used for RAM target)
  84. each element in "dfu_alt_info" =
  85. <name> ram <offset> <size> raw access to ram
  86. "sf" (serial flash : NOR)
  87. cmd: dfu 0 sf <dev>
  88. each element in "dfu_alt_info" =
  89. <name> ram <offset> <size> raw access to sf device
  90. <name> part <dev> <part_id> raw acces to partition
  91. <name> partubi <dev> <part_id> raw acces to ubi partition
  92. with <partid> is the MTD partition index
  93. "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
  94. cmd: dfu 0 mtd <dev>
  95. with <dev> the mtd identifier as defined in mtd command
  96. (nand0, nor0, spi-nand0,...)
  97. each element in "dfu_alt_info" =
  98. <name> raw <offset> <size> raw access to mtd device
  99. <name> part <dev> <part_id> raw acces to partition
  100. <name> partubi <dev> <part_id> raw acces to ubi partition
  101. with <partid> is the MTD partition index
  102. "virt"
  103. cmd: dfu 0 virt <dev>
  104. each element in "dfu_alt_info" =
  105. <name>
  106. <interface> and <dev> are absent:
  107. the dfu command to use multiple devices
  108. cmd: dfu 0 list
  109. cmd: dfu 0
  110. "dfu_alt_info" variable provides the list of <interface> <dev> with
  111. alternate list separated by '&' with the same format for each <alt>
  112. mmc <dev>=<alt1>;....;<altN>
  113. nand <dev>=<alt1>;....;<altN>
  114. ram <dev>=<alt1>;....;<altN>
  115. sf <dev>=<alt1>;....;<altN>
  116. mtd <dev>=<alt1>;....;<altN>
  117. virt <dev>=<alt1>;....;<altN>
  118. Callbacks:
  119. The weak callback functions can be implemented to manage specific behavior
  120. - dfu_initiated_callback : called when the DFU transaction is started,
  121. used to initiase the device
  122. - dfu_flush_callback : called at the end of the DFU write after DFU
  123. manifestation, used to manage the device when
  124. DFU transaction is closed
  125. Host tools:
  126. When U-Boot runs the dfu stack, the DFU host tools can be used
  127. to send/receive firmwares on each configurated alternate.
  128. For example dfu-util is a host side implementation of the DFU 1.1
  129. specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
  130. Usage:
  131. Example 1: firmware located in eMMC or SD card, with:
  132. - alternate 1 (alt=1) for SPL partition (GPT partition 1)
  133. - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
  134. The U-Boot configuration is:
  135. U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
  136. U-Boot> dfu 0 mmc 0 list
  137. DFU alt settings list:
  138. dev: eMMC alt: 0 name: spl layout: RAW_ADDR
  139. dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
  140. Boot> dfu 0 mmc 0
  141. On the Host side:
  142. list the available alternate setting:
  143. $> dfu-util -l
  144. dfu-util 0.9
  145. Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
  146. Copyright 2010-2016 Tormod Volden and Stefan Schmidt
  147. This program is Free Software and has ABSOLUTELY NO WARRANTY
  148. Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
  149. Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
  150. alt=1, name="u-boot", serial="003A00203438510D36383238"
  151. Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
  152. alt=0, name="spl", serial="003A00203438510D36383238"
  153. To download to U-Boot, use -D option
  154. $> dfu-util -a 0 -D u-boot-spl.bin
  155. $> dfu-util -a 1 -D u-boot.bin
  156. To upload from U-Boot, use -U option
  157. $> dfu-util -a 0 -U u-boot-spl.bin
  158. $> dfu-util -a 1 -U u-boot.bin
  159. To request a DFU detach and reset the USB connection:
  160. $> dfu-util -a 0 -e -R
  161. Example 2: firmware located in NOR (sf) and NAND, with:
  162. - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
  163. - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
  164. - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
  165. - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
  166. U-Boot> env set dfu_alt_info \
  167. "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
  168. u-boot-env part 0 3&nand 0=UBI partubi 0,1"
  169. U-Boot> dfu 0 list
  170. DFU alt settings list:
  171. dev: SF alt: 0 name: spl layout: RAW_ADDR
  172. dev: SF alt: 1 name: ssbl layout: RAW_ADDR
  173. dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
  174. dev: NAND alt: 3 name: UBI layout: RAW_ADDR
  175. U-Boot> dfu 0
  176. $> dfu-util -l
  177. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  178. intf=0, alt=3, name="UBI", serial="002700333338511934383330"
  179. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  180. intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
  181. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  182. intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
  183. Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
  184. intf=0, alt=0, name="spl", serial="002700333338511934383330"
  185. Same example with MTD backend
  186. U-Boot> env set dfu_alt_info \
  187. "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
  188. "mtd nand0=UBI partubi 1"
  189. U-Boot> dfu 0 list
  190. using id 'nor0,0'
  191. using id 'nor0,1'
  192. using id 'nor0,2'
  193. using id 'nand0,0'
  194. DFU alt settings list:
  195. dev: MTD alt: 0 name: spl layout: RAW_ADDR
  196. dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
  197. dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
  198. dev: MTD alt: 3 name: UBI layout: RAW_ADDR
  199. Example 3: firmware located in SD Card (mmc) and virtual partition on
  200. OTP and PMIC not volatile memory
  201. - alternate 1 (alt=1) for scard
  202. - alternate 2 (alt=2) for OTP (virtual)
  203. - alternate 3 (alt=3) for PMIC NVM (virtual)
  204. U-Boot> env set dfu_alt_info \
  205. "mmc 0=sdcard raw 0 0x100000&"\
  206. "virt 0=otp" \
  207. "virt 1=pmic"
  208. U-Boot> dfu 0 list
  209. DFU alt settings list:
  210. dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
  211. dev: VIRT alt: 1 name: otp layout: RAW_ADDR
  212. dev: VIRT alt: 2 name: pmic layout: RAW_ADDR