jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0+
2
3Device Firmware Upgrade (DFU)
4=============================
5
6Overview
7--------
8
9Device Firmware Upgrade (DFU) enables the download and upload of firmware
10to/from U-Boot while connected over USB.
11
12U-Boot follows the Universal Serial Bus Device Class Specification for
13Device Firmware Upgrade Version 1.1 from the USB forum (DFU v1.1 in www.usb.org).
14
15U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
16(cmd/dfu.c / CONFIG_CMD_DFU) based on:
17
18- the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
19 USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
20- The access to mediums is done in DFU backends (driver/dfu)
21
22Today the supported DFU backends are:
23
24- MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT)
25- SCSI (UFS, RAW partition, FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT)
26- NAND
27- RAM
28- SF (serial flash)
29- MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
30- virtual
31
32These DFU backends are also used by
33
34- the dfutftp (see README.dfutftp)
35- the thordown command (cmd/thordown.c and gadget/f_thor.c)
36
37The "virtual" backend is a generic DFU backend to support a board specific
38target (for example OTP), only based on the weak functions:
39
40- dfu_write_medium_virt
41- dfu_get_medium_size_virt
42- dfu_read_medium_virt
43
44Configuration Options
45---------------------
46
47The following configuration options are relevant to device firmware upgrade:
48
49* CONFIG_DFU
50* CONFIG_DFU_OVER_USB
51* CONFIG_DFU_MMC
52* CONFIG_DFU_MTD
53* CONFIG_DFU_NAND
54* CONFIG_DFU_RAM
55* CONFIG_DFU_SCSI
56* CONFIG_DFU_SF
57* CONFIG_DFU_SF_PART
58* CONFIG_DFU_TIMEOUT
59* CONFIG_DFU_VIRTUAL
60* CONFIG_CMD_DFU
61
62Environment variables
63---------------------
64
65The dfu command uses 3 environment variables:
66
67dfu_alt_info
68 The DFU setting for the USB download gadget with a semicolon separated
69 string of information on each alternate::
70
71 dfu_alt_info="<alt1>;<alt2>;....;<altN>"
72
73 When several devices are used, the format is:
74
75 - <interface> <dev>'='alternate list (';' separated)
76 - each interface is separated by '&'::
77
78 dfu_alt_info=\
79 "<interface1> <dev1>=<alt1>;....;<altN>&"\
80 "<interface2> <dev2>=<altN+1>;....;<altM>&"\
81 ...\
82 "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
83
84dfu_bufsiz
85 size of the DFU buffer, when absent, defaults to
86 CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)
87
88dfu_hash_algo
89 name of the hash algorithm to use
90
91Commands
92--------
93
94dfu <USB_controller> [<interface> <dev>] list
95 List the alternate device defined in *dfu_alt_info*.
96
97dfu <USB_controller> [<interface> <dev>] [<timeout>]
98 Start the dfu stack on the USB instance with the selected medium
99 backend and use the *dfu_alt_info* variable to configure the
100 alternate setting and link each one with the medium.
101 The dfu command continues until it receives a ^C in the console or
102 a DFU detach transaction from the HOST. If the CONFIG_DFU_TIMEOUT option
103 is enabled and a <timeout> parameter is present in the command line,
104 the DFU operation will be aborted automatically after <timeout>
105 seconds of waiting for the remote to initiate a DFU session.
106
107The possible values of <interface> are (with <USB controller> = 0 in the dfu
108command example)
109
110mmc
111 for eMMC and SD card::
112
113 dfu 0 mmc <dev>
114
115 each element in *dfu_alt_info* being
116
117 * <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device
118 * <name> part <dev> <part_id> [offset <byte>] raw access to partition
119 * <name> fat <dev> <part_id> file in FAT partition
120 * <name> ext4 <dev> <part_id> file in EXT4 partition
121 * <name> skip 0 0 ignore flashed data
122 * <name> script 0 0 execute commands in shell
123
124 with
125
126 offset
127 is the offset in the device (hexadecimal without "0x")
128 size
129 is the size of the access area (hexadecimal without "0x")
130 or 0 which means whole device
131 partid
132 being the GPT or DOS partition index,
133 num
134 being the eMMC hardware partition number.
135
136 A value of environment variable *dfu_alt_info* for eMMC could be::
137
138 u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1
139
140 A value of environment variable *dfu_alt_info* for SD card could be::
141
142 u-boot raw 0x80 0x800;uImage ext4 0 2
143
144 If you don't want to flash the given image file to storage, use the "skip"
145 type entity.
146
147 - It can be used to protect from flashing the wrong image for the specific board.
148 - Especially, this layout will be useful when the thor protocol is used,
149 which performs flashing in batch mode, where more than one file is
150 processed.
151
152 For example, if one makes a single tar file with support for the two
153 boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one
154 can use it to flash a proper u-boot image on both without a failure::
155
156 u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0
157
158 When flashing a new system image requires you to do some more complex
159 things than just writing data to the storage medium, one can use 'script'
160 type. Data written to such an entity will be executed as a command list
161 in the u-boot's shell. This for example allows you to re-create a partition
162 layout and even set a new *dfu_alt_info* for the newly created partitions.
163 Such a script would look like::
164
165 setenv dfu_alt_info ...
166 setenv mbr_parts ...
167 mbr write ...
168
169 Please note that this means the user will be able to execute any
170 arbitrary commands just like in the u-boot's shell.
171
172scsi
173 for UFS storage::
174
175 dfu 0 scsi <dev>
176
177 each element in *dfu_alt_info* being
178
179 * <name> raw <offset> <size> raw access to SCSI LUN
180 * <name> part <part_id> raw access to partition
181 * <name> fat <part_id> file in FAT partition
182 * <name> ext4 <part_id> file in EXT4 partition
183 * <name> skip 0 0 ignore flashed data
184 * <name> script 0 0 execute commands in shell
185
186 with
187
188 size
189 is the size of the access area (hexadecimal without "0x")
190 or 0 which means whole device
191 partid
192 is the GPT or DOS partition index.
193 dev
194 is the SCSI LU (Logical Unit) index (decimal only)
195
196 A value of environment variable *dfu_alt_info* for UFS could be::
197
198 u-boot part 4;bl2 raw 0x1e 0x1d
199
200 See mmc section above for details on the skip and script types.
201
202nand
203 raw slc nand device::
204
205 dfu 0 nand <dev>
206
207 each element in *dfu_alt_info* being either of
208
209 * <name> raw <offset> <size> raw access to nand device
210 * <name> part <dev_id> <part_id> raw access to partition
211 * <name> partubi <dev_id> <part_id> raw access to ubi partition
212
213 with
214
215 offset
216 is the offset in the nand device (hexadecimal without "0x")
217 size
218 is the size of the access area (hexadecimal without "0x")
219 dev_id
220 is the NAND device index (decimal only)
221 part_id
222 is the NAND partition index (decimal only)
223
224ram
225 raw access to ram::
226
227 dfu 0 ram <dev>
228
229 dev
230 is not used for RAM target
231
232 each element in *dfu_alt_info* being::
233
234 <name> ram <offset> <size> raw access to ram
235
236 with
237
238 offset
239 is the offset in the ram device (hexadecimal without "0x")
240 size
241 is the size of the access area (hexadecimal without "0x")
242
243sf
244 serial flash : NOR::
245
246 cmd: dfu 0 sf <dev>
247
248 each element in *dfu_alt_info* being either of:
249
250 * <name> raw <offset> <size> raw access to sf device
251 * <name> part <dev_id> <part_id> raw access to partition
252 * <name> partubi <dev_id> <part_id> raw access to ubi partition
253
254 with
255
256 offset
257 is the offset in the sf device (hexadecimal without "0x")
258 size
259 is the size of the access area (hexadecimal without "0x")
260 dev_id
261 is the sf device index (the device is "nor<dev_id>") (deximal only)
262 part_id
263 is the MTD partition index (decimal only)
264
265mtd
266 all MTD device: NAND, SPI-NOR, SPI-NAND,...::
267
268 cmd: dfu 0 mtd <dev>
269
270 with
271
272 dev
273 the mtd identifier as defined in mtd command
274 (nand0, nor0, spi-nand0,...)
275
276 each element in *dfu_alt_info* being either of:
277
278 * <name> raw <offset> <size> for raw access to mtd device
279 * <name> part <part_id> for raw access to partition
280 * <name> partubi <part_id> for raw access to ubi partition
281
282 with
283
284 offset
285 is the offset in the mtd device (hexadecimal without "0x")
286 size
287 is the size of the access area (hexadecimal without "0x")
288 part_id
289 is the MTD partition index (decimal only)
290
291virt
292 virtual flash back end for DFU
293
294 ::
295
296 cmd: dfu 0 virt <dev>
297
298 each element in *dfu_alt_info* being:
299
300 * <name>
301
302<interface> and <dev> are absent, the dfu command to use multiple devices::
303
304 cmd: dfu 0 list
305 cmd: dfu 0
306
307*dfu_alt_info* variable provides the list of <interface> <dev> with
308alternate list separated by '&' with the same format for each <alt>::
309
310 mmc <dev>=<alt1>;....;<altN>
311 nand <dev>=<alt1>;....;<altN>
312 ram <dev>=<alt1>;....;<altN>
313 scsi <dev>=<alt1>;....;<altN>
314 sf <dev>=<alt1>;....;<altN>
315 mtd <dev>=<alt1>;....;<altN>
316 virt <dev>=<alt1>;....;<altN>
317
318Callbacks
319---------
320
321The weak callback functions can be implemented to manage specific behavior
322
323dfu_initiated_callback
324 called when the DFU transaction is started, used to initialize the device
325
326dfu_flush_callback
327 called at the end of the DFU write after DFU manifestation, used to manage
328 the device when the DFU transaction is closed
329
330Host tools
331----------
332
333When U-Boot runs the dfu stack, the DFU host tools can be used
334to send/receive firmware images on each configured alternate.
335
336For example dfu-util is a host side implementation of the DFU 1.1
337specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
338
339Usage
340-----
341
342Example 1: firmware located in eMMC or SD card, with:
343
344- alternate 1 (alt=1) for SPL partition (GPT partition 1)
345- alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
346
347The U-Boot configuration is::
348
349 U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
350
351 U-Boot> dfu 0 mmc 0 list
352 DFU alt settings list:
353 dev: eMMC alt: 0 name: spl layout: RAW_ADDR
354 dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
355
356 Boot> dfu 0 mmc 0
357
358On the Host side:
359
360list the available alternate setting::
361
362 $> dfu-util -l
363 dfu-util 0.9
364
365 Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
366 Copyright 2010-2016 Tormod Volden and Stefan Schmidt
367 This program is Free Software and has ABSOLUTELY NO WARRANTY
368 Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
369
370 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
371 alt=1, name="u-boot", serial="003A00203438510D36383238"
372 Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
373 alt=0, name="spl", serial="003A00203438510D36383238"
374
375 To download to U-Boot, use -D option
376
377 $> dfu-util -a 0 -D u-boot-spl.bin
378 $> dfu-util -a 1 -D u-boot.bin
379
380 To upload from U-Boot, use -U option
381
382 $> dfu-util -a 0 -U u-boot-spl.bin
383 $> dfu-util -a 1 -U u-boot.bin
384
385 To request a DFU detach and reset the USB connection:
386 $> dfu-util -a 0 -e -R
387
388
389Example 2: firmware located in NOR (sf) and NAND, with:
390
391- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
392- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
393- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
394- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
395
396::
397
398 U-Boot> env set dfu_alt_info \
399 "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
400 u-boot-env part 0 3&nand 0=UBI partubi 0,1"
401
402 U-Boot> dfu 0 list
403
404 DFU alt settings list:
405 dev: SF alt: 0 name: spl layout: RAW_ADDR
406 dev: SF alt: 1 name: ssbl layout: RAW_ADDR
407 dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
408 dev: NAND alt: 3 name: UBI layout: RAW_ADDR
409
410 U-Boot> dfu 0
411
412::
413
414 $> dfu-util -l
415 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
416 intf=0, alt=3, name="UBI", serial="002700333338511934383330"
417 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
418 intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
419 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
420 intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
421 Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
422 intf=0, alt=0, name="spl", serial="002700333338511934383330"
423
424Same example with MTD backend
425
426::
427
428 U-Boot> env set dfu_alt_info \
429 "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
430 "mtd nand0=UBI partubi 1"
431
432 U-Boot> dfu 0 list
433 using id 'nor0,0'
434 using id 'nor0,1'
435 using id 'nor0,2'
436 using id 'nand0,0'
437 DFU alt settings list:
438 dev: MTD alt: 0 name: spl layout: RAW_ADDR
439 dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
440 dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
441 dev: MTD alt: 3 name: UBI layout: RAW_ADDR
442
443Example 3
444
445firmware located in SD Card (mmc) and virtual partition on OTP and PMIC
446non-volatile memory
447
448- alternate 1 (alt=1) for scard
449- alternate 2 (alt=2) for OTP (virtual)
450- alternate 3 (alt=3) for PMIC NVM (virtual)
451
452::
453
454 U-Boot> env set dfu_alt_info \
455 "mmc 0=sdcard raw 0 0x100000&"\
456 "virt 0=otp" \
457 "virt 1=pmic"
458
459::
460
461 U-Boot> dfu 0 list
462 DFU alt settings list:
463 dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
464 dev: VIRT alt: 1 name: otp layout: RAW_ADDR
465 dev: VIRT alt: 2 name: pmic layout: RAW_ADDR