1 # SPDX-License-Identifier: GPL-2.0+
3 Device Firmware Upgrade (DFU)
7 The Device Firmware Upgrade (DFU) allows to download and upload firmware
8 to/from U-Boot connected over USB.
10 U-boot follows the Universal Serial Bus Device Class Specification for
11 Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).
13 U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
14 (cmd/dfu.c / CONFIG_CMD_DFU) based on:
15 - the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
16 USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
17 - The access to mediums is done in DFU backends (driver/dfu)
19 Today the supported DFU backends are:
20 - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
24 - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
27 These DFU backends are also used by
28 - the dfutftp (see README.dfutftp)
29 - the thordown command (cmd/thordown.c and gadget/f_thor.c)
31 The "virtual" backend is a generic DFU backend to support a board specific
32 target (for example OTP), only based on the weak functions:
33 - dfu_write_medium_virt
34 - dfu_get_medium_size_virt
35 - dfu_read_medium_virt
37 Configuration Options:
49 Environment variables:
50 the dfu command use 3 environments variables:
51 "dfu_alt_info" : the DFU setting for the USB download gadget with a comma
52 separated string of information on each alternate:
53 dfu_alt_info="<alt1>;<alt2>;....;<altN>"
55 when only several device are used, the format is:
56 - <interface> <dev>'='alternate list (';' separated)
57 - each interface is separated by '&'
59 "<interface1> <dev1>=<alt1>;....;<altN>&"\
60 "<interface2> <dev2>=<altN+1>;....;<altM>&"\
62 "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
64 "dfu_bufsiz" : size of the DFU buffer, when absent, use
65 CONFIG_SYS_DFU_DATA_BUF_SIZE (8MiB by default)
67 "dfu_hash_algo" : name of the hash algorithm to use
70 dfu <USB_controller> [<interface> <dev>] list
71 list the alternate device defined in "dfu_alt_info"
73 dfu <USB_controller> [<interface> <dev>]
74 start the dfu stack on the USB instance with the selected medium
75 backend and use the "dfu_alt_info" variable to configure the
76 alternate setting and link each one with the medium
77 The dfu command continue until receive a ^C in console or
78 a DFU detach transaction from HOST.
80 The possible values of <interface> are :
81 (with <USB controller> = 0 in the dfu command example)
83 "mmc" (for eMMC and SD card)
85 each element in "dfu_alt_info" =
86 <name> raw <offset> <size> raw access to mmc device
87 <name> part <dev> <part_id> raw acces to partition
88 <name> fat <dev> <part_id> file in FAT partition
89 <name> ext4 <dev> <part_id> file in EXT4 partition
91 with <partid> is the GPT or DOS partition index
93 "nand" (raw slc nand device)
95 each element in "dfu_alt_info" =
96 <name> raw <offset> <size> raw access to mmc device
97 <name> part <dev> <part_id> raw acces to partition
98 <name> partubi <dev> <part_id> raw acces to ubi partition
100 with <partid> is the MTD partition index
104 (<dev> is not used for RAM target)
105 each element in "dfu_alt_info" =
106 <name> ram <offset> <size> raw access to ram
108 "sf" (serial flash : NOR)
110 each element in "dfu_alt_info" =
111 <name> ram <offset> <size> raw access to sf device
112 <name> part <dev> <part_id> raw acces to partition
113 <name> partubi <dev> <part_id> raw acces to ubi partition
115 with <partid> is the MTD partition index
117 "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
119 with <dev> the mtd identifier as defined in mtd command
120 (nand0, nor0, spi-nand0,...)
121 each element in "dfu_alt_info" =
122 <name> raw <offset> <size> raw access to mtd device
123 <name> part <dev> <part_id> raw acces to partition
124 <name> partubi <dev> <part_id> raw acces to ubi partition
126 with <partid> is the MTD partition index
129 cmd: dfu 0 virt <dev>
130 each element in "dfu_alt_info" =
133 <interface> and <dev> are absent:
134 the dfu command to use multiple devices
137 "dfu_alt_info" variable provides the list of <interface> <dev> with
138 alternate list separated by '&' with the same format for each <alt>
139 mmc <dev>=<alt1>;....;<altN>
140 nand <dev>=<alt1>;....;<altN>
141 ram <dev>=<alt1>;....;<altN>
142 sf <dev>=<alt1>;....;<altN>
143 mtd <dev>=<alt1>;....;<altN>
144 virt <dev>=<alt1>;....;<altN>
147 When U-Boot runs the dfu stack, the DFU host tools can be used
148 to send/receive firmwares on each configurated alternate.
150 For example dfu-util is a host side implementation of the DFU 1.1
151 specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
154 Example 1: firmware located in eMMC or SD card, with:
155 - alternate 1 (alt=1) for SPL partition (GPT partition 1)
156 - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
158 The U-Boot configuration is:
160 U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
162 U-Boot> dfu 0 mmc 0 list
163 DFU alt settings list:
164 dev: eMMC alt: 0 name: spl layout: RAW_ADDR
165 dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
171 list the available alternate setting:
176 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
177 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
178 This program is Free Software and has ABSOLUTELY NO WARRANTY
179 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
181 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
182 alt=1, name="u-boot", serial="003A00203438510D36383238"
183 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
184 alt=0, name="spl", serial="003A00203438510D36383238"
186 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
191 To upload from U-Boot, use -U option
193 $> dfu-util -a 0 -U u-boot-spl.bin
194 $> dfu-util -a 1 -U u-boot.bin
196 To request a DFU detach and reset the USB connection:
197 $> dfu-util -a 0 -e -R
200 Example 2: firmware located in NOR (sf) and NAND, with:
201 - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
202 - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
203 - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
204 - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
206 U-Boot> env set dfu_alt_info \
207 "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
208 u-boot-env part 0 3&nand 0=UBI partubi 0,1"
212 DFU alt settings list:
213 dev: SF alt: 0 name: spl layout: RAW_ADDR
214 dev: SF alt: 1 name: ssbl layout: RAW_ADDR
215 dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
216 dev: NAND alt: 3 name: UBI layout: RAW_ADDR
221 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
222 intf=0, alt=3, name="UBI", serial="002700333338511934383330"
223 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
224 intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
225 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
226 intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
227 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
228 intf=0, alt=0, name="spl", serial="002700333338511934383330"
230 Same example with MTD backend
232 U-Boot> env set dfu_alt_info \
233 "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
234 "mtd nand0=UBI partubi 1"
241 DFU alt settings list:
242 dev: MTD alt: 0 name: spl layout: RAW_ADDR
243 dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
244 dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
245 dev: MTD alt: 3 name: UBI layout: RAW_ADDR
247 Example 3: firmware located in SD Card (mmc) and virtual partition on
248 OTP and PMIC not volatile memory
249 - alternate 1 (alt=1) for scard
250 - alternate 2 (alt=2) for OTP (virtual)
251 - alternate 3 (alt=3) for PMIC NVM (virtual)
253 U-Boot> env set dfu_alt_info \
254 "mmc 0=sdcard raw 0 0x100000&"\
259 DFU alt settings list:
260 dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
261 dev: VIRT alt: 1 name: otp layout: RAW_ADDR
262 dev: VIRT alt: 2 name: pmic layout: RAW_ADDR