1DFU-UTIL(1)                 General Commands Manual                DFU-UTIL(1)
2
3
4

NAME

6       dfu-util - Device firmware update (DFU) USB programmer
7

SYNOPSIS

9       dfu-util  -l  [-v]  [-d vid:pid[,vid:pid]] [-p path] [-c configuration]
10              [-i interface] [-a alt-intf] [-S serial[,serial]]
11
12       dfu-util [-v] [-d vid:pid[,vid:pid]] [-p path] [-c  configuration]  [-i
13              interface]  [-a  alt-intf]  [-S  serial[,serial]]  [-t size] [-Z
14              size] [-w] [-s address] [-R] [-D|-U file]
15
16       dfu-util [-hV]
17

DESCRIPTION

19       dfu-util is a program that implements the host (computer) side  of  the
20       USB DFU (Universal Serial Bus Device Firmware Upgrade) protocol.
21
22       dfu-util  communicates  with  devices that implement the device side of
23       the USB DFU protocol, and is often used to upgrade the firmware of such
24       devices.
25

OPTIONS

27       -l, --list
28              List the currently attached DFU capable USB devices.
29
30       -d,  --device  [Run-Time  VENDOR]:[Run-Time  PRODUCT][,[DFU  Mode  VEN‐
31       DOR]:[DFU Mode PRODUCT]]
32              Specify run-time and/or DFU mode vendor and/or  product  IDs  of
33              the  DFU device to work with. VENDOR and PRODUCT are hexadecimal
34              numbers (no prefix needed), "*" (match any), or "-" (match noth‐
35              ing).  By  default, any DFU capable device in either run-time or
36              DFU mode will be considered.
37
38              If you only have one standards-compliant DFU device attached  to
39              your  computer,  this parameter is optional. However, as soon as
40              you have multiple DFU devices connected,  dfu-util  will  detect
41              this and abort, asking you to specify which device to use.
42
43              If  only run-time IDs are specified (e.g. "--device 1457:51ab"),
44              then in addition to the specified run-time  IDs,  any  DFU  mode
45              devices  will  also be considered. This is beneficial to allow a
46              DFU capable device to be found again after a switch to DFU mode,
47              since  the  vendor and/or product ID of a device usually changes
48              in DFU mode.
49
50              If only DFU mode IDs are specified  (e.g.  "--device  ,951:26"),
51              then  all  run-time  devices  will be ignored, making it easy to
52              target a specific device in DFU mode.
53
54              If both run-time and DFU mode IDs are specified (e.g.  "--device
55              1457:51ab,:2bc"),  then unspecified DFU mode components will use
56              the run-time value specified.
57
58              Examples:
59
60              --device 1457:51ab,951:26
61                     Work with a device in run-time mode with vendor ID 0x1457
62                     and  product  ID  0x51ab,  or  in DFU mode with vendor ID
63                     0x0951 and product ID 0x0026
64
65
66              --device 1457:51ab,:2bc
67                     Work with a device in run-time mode with vendor ID 0x1457
68                     and  product  ID  0x51ab,  or  in DFU mode with vendor ID
69                     0x1457 and product ID 0x02bc
70
71
72              --device 1457:51ab
73                     Work with a device in run-time mode with vendor ID 0x1457
74                     and product ID 0x51ab, or in DFU mode with any vendor and
75                     product ID
76
77
78              --device ,951:26
79                     Work with a device in DFU mode with vendor ID 0x0951  and
80                     product ID 0x0026
81
82
83              --device *,-
84                     Work  with  any  device  in run-time mode, and ignore any
85                     device in DFU mode
86
87
88              --device ,
89                     Ignore any device in run-time mode,  and  Work  with  any
90                     device in DFU mode
91
92       -p, --path BUS-PORT. ... .PORT
93              Specify the path to the DFU device.
94
95       -c, --cfg CONFIG-NR
96              Specify  the  configuration of the DFU device. Note that this is
97              only used for matching, the configuration is  not  set  by  dfu-
98              util.
99
100       -i, --intf INTF-NR
101              Specify the DFU interface number.
102
103       -a, --alt ALT
104              Specify  the  altsetting of the DFU interface by name or by num‐
105              ber.
106
107       -S, --serial [Run-Time SERIAL][,[DFU Mode SERIAL]]
108              Specify the run-time and DFU mode serial numbers used to further
109              restrict device matches.  If multiple, identical DFU devices are
110              simultaneously connected to a system then vendor and product  ID
111              will  be  insufficient  for  targeting a single device.  In this
112              situation, it may be possible to use this parameter to specify a
113              serial number which also must match.
114
115              If  only  a  single  serial  number  is specified, then the same
116              serial number is used in both run-time and DFU  mode.  An  empty
117              serial  number will match any serial number in the corresponding
118              mode.
119
120       -t, --transfer-size SIZE
121              Specify the number of bytes per USB transfer. The optimal  value
122              is  usually  determined  automatically  so this option is rarely
123              useful. If you need to use this  option  for  a  device,  please
124              report it as a bug.
125
126       -Z, --upload-size SIZE
127              Specify  the expected upload size, in bytes. Note that the value
128              is only used for scaling the progress  bar,  the  actual  upload
129              size is determined by the device.
130
131       -U, --upload FILE
132              Read firmware from device into FILE.
133
134       -D, --download FILE
135              Write  firmware  from  FILE  into  device.  When  FILE is -, the
136              firmware is read from stdin.
137
138       -R, --reset
139              Issue USB reset signalling after upload  or  download  has  fin‐
140              ished.
141
142       -e, --detach
143              Request  that  the  device re-enumerate out of run-time mode and
144              into DFU mode as when uploading or downloading, but exit immedi‐
145              ately after sending the request.
146
147       -E, --detach-delay SECONDS
148              When  uploading  or  downloading,  wait  SECONDS seconds for the
149              device to re-enumerate after sending the detach  request  before
150              giving up. Defaults to 5 seconds. This option has no effect with
151              -e, since that causes dfu-util to immediately exit after sending
152              the detach request.
153
154       -w, --wait
155              Wait until matching device appears on the USB bus.
156
157       -s, --dfuse-address [ADDRESS][:LENGTH][:MODIFIERS]
158              Specify  target  address for raw binary download/upload on DfuSe
159              devices. Do not use this option  for  downloading  DfuSe  (.dfu)
160              files.   A length can be specified for uploads. Modifiers can be
161              added after the address, separated by a colon, to  perform  spe‐
162              cial  DfuSE  commands  such as "leave" DFU mode, "unprotect" and
163              "mass-erase" flash memory.  If the device  can  be  expected  to
164              reset  itself after the operation, "will-reset" should be added.
165              The "force" modifier will override some sanity  checks,  and  is
166              also needed for the "unprotect" and "mass-erase" operations.
167
168       -v, --verbose
169              Print  more  information about dfu-util's operation. A second -v
170              adds more details. A third -v activates verbose logging  of  USB
171              requests (libusb debug output).
172
173       -h, --help
174              Show a help text and exit.
175
176       -V, --version
177              Show version information and exit.
178

EXAMPLES

180   Using dfu-util in the OpenMoko project
181       (with the Neo1973 hardware)
182
183       Flashing the rootfs:
184         $ dfu-util -a rootfs -R -D /path/to/openmoko-devel-image.jffs2
185
186       Flashing the kernel:
187         $ dfu-util -a kernel -R -D /path/to/uImage
188
189       Flashing the bootloader:
190         $ dfu-util -a u-boot -R -D /path/to/u-boot.bin
191
192       Copying a kernel into RAM:
193         $ dfu-util -a 0 -R -D /path/to/uImage
194
195       Once  this  has  finished,  the kernel will be available at the default
196       load address of 0x32000000 in Neo1973 RAM.  Note: You  cannot  transfer
197       more than 2MB of data into RAM using this method.
198
199
200   Using dfu-util with a DfuSe device
201       Flashing a .dfu (special DfuSe format) file to the device:
202         $ dfu-util -a 0 -D /path/to/dfuse-image.dfu
203
204       Reading out 1 KB of flash starting at address 0x8000000:
205         $ dfu-util -a 0 -s 0x08000000:1024 -U newfile.bin
206
207       Flashing  a  binary  file to address 0x8004000 of device memory and ask
208       the device to leave DFU mode:
209         $ dfu-util -a 0 -s 0x08004000:leave -D /path/to/image.bin
210

BUGS

212       Please report any bugs to the dfu-util bug  tracker  at  http://source
213       forge.net/p/dfu-util/tickets/.    Please   use   the  --verbose  option
214       (repeated as necessary) to provide more information in your bug report.
215

SEE ALSO

217       The dfu-util home page is http://dfu-util.sourceforge.net/
218

HISTORY

220       dfu-util was originally written for  the  OpenMoko  project  by  Weston
221       Schmidt  <weston_schmidt@yahoo.com>  and  Harald Welte <hwelte@hmw-con‐
222       sulting.de>. Over time, nearly complete support of DFU 1.0, DFU 1.1 and
223       DfuSe ("1.1a") has been added.
224

LICENCE

226       dfu-util  is covered by the GNU General Public License (GPL), version 2
227       or later.
228
230       This manual page was originally written by  Uwe  Hermann  <uwe@hermann-
231       uwe.de>, and is now part of the dfu-util project.
232
233
234
235                               November 8, 2020                    DFU-UTIL(1)
Impressum