blob: be53b5b393c35fdf8c459803e6710fc272c85155 [file] [log] [blame]
Patrick Delaunay321179e2019-10-14 09:27:59 +02001# SPDX-License-Identifier: GPL-2.0+
2
3Device Firmware Upgrade (DFU)
4
5Overview:
6
7 The Device Firmware Upgrade (DFU) allows to download and upload firmware
8 to/from U-Boot connected over USB.
9
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).
12
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)
18
19 Today the supported DFU backends are:
20 - MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system)
21 - NAND
22 - RAM
23 - SF (serial flash)
Patrick Delaunay6015af22019-10-14 09:28:04 +020024 - MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
Patrick Delaunayec44cac2019-10-14 09:28:06 +020025 - virtual
Patrick Delaunay321179e2019-10-14 09:27:59 +020026
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)
30
Patrick Delaunayec44cac2019-10-14 09:28:06 +020031 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
36
Patrick Delaunay321179e2019-10-14 09:27:59 +020037Configuration Options:
38 CONFIG_DFU
39 CONFIG_DFU_OVER_USB
40 CONFIG_DFU_MMC
Patrick Delaunay6015af22019-10-14 09:28:04 +020041 CONFIG_DFU_MTD
Patrick Delaunay321179e2019-10-14 09:27:59 +020042 CONFIG_DFU_NAND
43 CONFIG_DFU_RAM
44 CONFIG_DFU_SF
Patrick Delaunaycb986ba2019-10-14 09:28:00 +020045 CONFIG_DFU_SF_PART
Andy Shevchenko98a8f442019-11-27 18:12:15 +020046 CONFIG_DFU_TIMEOUT
Patrick Delaunayec44cac2019-10-14 09:28:06 +020047 CONFIG_DFU_VIRTUAL
Patrick Delaunay321179e2019-10-14 09:27:59 +020048 CONFIG_CMD_DFU
49
50Environment variables:
Heinrich Schuchardt3547e692020-05-23 13:48:07 +020051 the dfu command uses 3 environments variables:
Heinrich Schuchardt378fc832020-05-23 11:36:49 +020052 "dfu_alt_info" : the DFU setting for the USB download gadget with a semicolon
Patrick Delaunay321179e2019-10-14 09:27:59 +020053 separated string of information on each alternate:
54 dfu_alt_info="<alt1>;<alt2>;....;<altN>"
55
Heinrich Schuchardt3547e692020-05-23 13:48:07 +020056 when several devices are used, the format is:
Patrick Delaunayfebabe32019-10-14 09:28:02 +020057 - <interface> <dev>'='alternate list (';' separated)
58 - each interface is separated by '&'
59 dfu_alt_info=\
60 "<interface1> <dev1>=<alt1>;....;<altN>&"\
61 "<interface2> <dev2>=<altN+1>;....;<altM>&"\
62 ...\
63 "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
64
Patrick Delaunay321179e2019-10-14 09:27:59 +020065 "dfu_bufsiz" : size of the DFU buffer, when absent, use
Heinrich Schuchardt3547e692020-05-23 13:48:07 +020066 CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)
Patrick Delaunay321179e2019-10-14 09:27:59 +020067
68 "dfu_hash_algo" : name of the hash algorithm to use
69
70Commands:
Patrick Delaunayfebabe32019-10-14 09:28:02 +020071 dfu <USB_controller> [<interface> <dev>] list
Patrick Delaunay321179e2019-10-14 09:27:59 +020072 list the alternate device defined in "dfu_alt_info"
73
Andy Shevchenko98a8f442019-11-27 18:12:15 +020074 dfu <USB_controller> [<interface> <dev>] [<timeout>]
Patrick Delaunay321179e2019-10-14 09:27:59 +020075 start the dfu stack on the USB instance with the selected medium
76 backend and use the "dfu_alt_info" variable to configure the
77 alternate setting and link each one with the medium
78 The dfu command continue until receive a ^C in console or
Andy Shevchenko98a8f442019-11-27 18:12:15 +020079 a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option
80 is enabled and <timeout> parameter is present in the command line,
81 the DFU operation will be aborted automatically after <timeout>
82 seconds of waiting remote to initiate DFU session.
Patrick Delaunay321179e2019-10-14 09:27:59 +020083
84 The possible values of <interface> are :
85 (with <USB controller> = 0 in the dfu command example)
86
87 "mmc" (for eMMC and SD card)
88 cmd: dfu 0 mmc <dev>
89 each element in "dfu_alt_info" =
Heinrich Schuchardt378fc832020-05-23 11:36:49 +020090 <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device
91 <name> part <dev> <part_id> [mmcpart <num>] raw access to partition
92 <name> fat <dev> <part_id> [mmcpart <num>] file in FAT partition
93 <name> ext4 <dev> <part_id> [mmcpart <num>] file in EXT4 partition
Patrick Delaunay321179e2019-10-14 09:27:59 +020094
Heinrich Schuchardt378fc832020-05-23 11:36:49 +020095 with <partid> being the GPT or DOS partition index,
96 with <num> being the eMMC hardware partition number.
97
98 A value of environment variable dfu_alt_info for eMMC could be:
99
100 "u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1"
101
102 A value of environment variable dfu_alt_info for SD card could be:
103
104 "u-boot raw 0x80 0x800;uImage ext4 0 2"
Patrick Delaunay321179e2019-10-14 09:27:59 +0200105
106 "nand" (raw slc nand device)
107 cmd: dfu 0 nand <dev>
108 each element in "dfu_alt_info" =
109 <name> raw <offset> <size> raw access to mmc device
110 <name> part <dev> <part_id> raw acces to partition
111 <name> partubi <dev> <part_id> raw acces to ubi partition
112
113 with <partid> is the MTD partition index
114
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
121 "sf" (serial flash : NOR)
122 cmd: dfu 0 sf <dev>
123 each element in "dfu_alt_info" =
Chance.Yang69509fb2020-10-14 11:47:33 +0800124 <name> raw <offset> <size> raw access to sf device
Patrick Delaunaycb986ba2019-10-14 09:28:00 +0200125 <name> part <dev> <part_id> raw acces to partition
126 <name> partubi <dev> <part_id> raw acces to ubi partition
127
128 with <partid> is the MTD partition index
Patrick Delaunay321179e2019-10-14 09:27:59 +0200129
Patrick Delaunay6015af22019-10-14 09:28:04 +0200130 "mtd" (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
131 cmd: dfu 0 mtd <dev>
132 with <dev> the mtd identifier as defined in mtd command
133 (nand0, nor0, spi-nand0,...)
134 each element in "dfu_alt_info" =
135 <name> raw <offset> <size> raw access to mtd device
Patrick Delaunayd5640f72019-10-14 09:28:05 +0200136 <name> part <dev> <part_id> raw acces to partition
137 <name> partubi <dev> <part_id> raw acces to ubi partition
138
139 with <partid> is the MTD partition index
Patrick Delaunay6015af22019-10-14 09:28:04 +0200140
Patrick Delaunayec44cac2019-10-14 09:28:06 +0200141 "virt"
142 cmd: dfu 0 virt <dev>
143 each element in "dfu_alt_info" =
144 <name>
145
Patrick Delaunayfebabe32019-10-14 09:28:02 +0200146 <interface> and <dev> are absent:
147 the dfu command to use multiple devices
148 cmd: dfu 0 list
149 cmd: dfu 0
150 "dfu_alt_info" variable provides the list of <interface> <dev> with
151 alternate list separated by '&' with the same format for each <alt>
152 mmc <dev>=<alt1>;....;<altN>
153 nand <dev>=<alt1>;....;<altN>
154 ram <dev>=<alt1>;....;<altN>
155 sf <dev>=<alt1>;....;<altN>
Patrick Delaunay6015af22019-10-14 09:28:04 +0200156 mtd <dev>=<alt1>;....;<altN>
Patrick Delaunayec44cac2019-10-14 09:28:06 +0200157 virt <dev>=<alt1>;....;<altN>
Patrick Delaunayfebabe32019-10-14 09:28:02 +0200158
Patrick Delaunay067c13c2019-10-14 09:28:07 +0200159Callbacks:
160 The weak callback functions can be implemented to manage specific behavior
161 - dfu_initiated_callback : called when the DFU transaction is started,
162 used to initiase the device
163 - dfu_flush_callback : called at the end of the DFU write after DFU
164 manifestation, used to manage the device when
165 DFU transaction is closed
166
Patrick Delaunay321179e2019-10-14 09:27:59 +0200167Host tools:
168 When U-Boot runs the dfu stack, the DFU host tools can be used
169 to send/receive firmwares on each configurated alternate.
170
171 For example dfu-util is a host side implementation of the DFU 1.1
172 specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
173
174Usage:
Patrick Delaunayfebabe32019-10-14 09:28:02 +0200175 Example 1: firmware located in eMMC or SD card, with:
Patrick Delaunay321179e2019-10-14 09:27:59 +0200176 - alternate 1 (alt=1) for SPL partition (GPT partition 1)
177 - alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
178
179 The U-Boot configuration is:
180
181 U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
182
183 U-Boot> dfu 0 mmc 0 list
184 DFU alt settings list:
185 dev: eMMC alt: 0 name: spl layout: RAW_ADDR
186 dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
187
188 Boot> dfu 0 mmc 0
189
190 On the Host side:
191
192 list the available alternate setting:
193
194 $> dfu-util -l
195 dfu-util 0.9
196
197 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
198 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
199 This program is Free Software and has ABSOLUTELY NO WARRANTY
200 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
201
202 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
203 alt=1, name="u-boot", serial="003A00203438510D36383238"
204 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
205 alt=0, name="spl", serial="003A00203438510D36383238"
206
207 To download to U-Boot, use -D option
208
209 $> dfu-util -a 0 -D u-boot-spl.bin
210 $> dfu-util -a 1 -D u-boot.bin
211
212 To upload from U-Boot, use -U option
213
214 $> dfu-util -a 0 -U u-boot-spl.bin
215 $> dfu-util -a 1 -U u-boot.bin
216
217 To request a DFU detach and reset the USB connection:
218 $> dfu-util -a 0 -e -R
Patrick Delaunayfebabe32019-10-14 09:28:02 +0200219
220
221 Example 2: firmware located in NOR (sf) and NAND, with:
222 - alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
223 - alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
224 - alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
225 - alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
226
227 U-Boot> env set dfu_alt_info \
228 "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
229 u-boot-env part 0 3&nand 0=UBI partubi 0,1"
230
231 U-Boot> dfu 0 list
232
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
239 U-Boot> dfu 0
240
241 $> dfu-util -l
242 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
243 intf=0, alt=3, name="UBI", serial="002700333338511934383330"
244 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
245 intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
246 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
247 intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
248 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
249 intf=0, alt=0, name="spl", serial="002700333338511934383330"
Patrick Delaunayd5640f72019-10-14 09:28:05 +0200250
251 Same example with MTD backend
252
253 U-Boot> env set dfu_alt_info \
254 "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
255 "mtd nand0=UBI partubi 1"
256
257 U-Boot> dfu 0 list
258 using id 'nor0,0'
259 using id 'nor0,1'
260 using id 'nor0,2'
261 using id 'nand0,0'
262 DFU alt settings list:
263 dev: MTD alt: 0 name: spl layout: RAW_ADDR
264 dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
265 dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
266 dev: MTD alt: 3 name: UBI layout: RAW_ADDR
Patrick Delaunayec44cac2019-10-14 09:28:06 +0200267
268 Example 3: firmware located in SD Card (mmc) and virtual partition on
269 OTP and PMIC not volatile memory
270 - alternate 1 (alt=1) for scard
271 - alternate 2 (alt=2) for OTP (virtual)
272 - alternate 3 (alt=3) for PMIC NVM (virtual)
273
274 U-Boot> env set dfu_alt_info \
275 "mmc 0=sdcard raw 0 0x100000&"\
276 "virt 0=otp" \
277 "virt 1=pmic"
278
279 U-Boot> dfu 0 list
280 DFU alt settings list:
281 dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
282 dev: VIRT alt: 1 name: otp layout: RAW_ADDR
283 dev: VIRT alt: 2 name: pmic layout: RAW_ADDR