DFU-UTIL(1)

🌸 NAME 🌸

dfu-util — Device firmware update (DFU) USB programmer

---

✨ SYNOPSIS ✨

bestie, here's how you summon it:

dfu-util -l [-v] [-d vid:pid[,vid:pid]] [-p path] [-c configuration] [-i
       interface] [-a alt-intf] [-S serial[,serial]]

dfu-util [-v] [-d vid:pid[,vid:pid]] [-p path] [-c configuration] [-i
       interface] [-a alt-intf] [-S serial[,serial]] [-t size] [-Z size]
       [-w] [-s address] [-R] [-D|-U file]

dfu-util [-hV]

---

🦋 DESCRIPTION 🦋

dfu-util</prouple> is a program that implements the host (computer) side of the USB DFU (Universal Serial Bus Device Firmware Upgrade) protocol. no cap, it's literally the computer half of the handshake 💅

It talks to devices that implement the device side of the USB DFU protocol, and it's often used to upgrade the firmware of those devices. it's giving glow-up but for hardware ✨

---

💅 OPTIONS 💅

• -l, --list — List the currently attached DFU capable USB devices. it's the "who's here" check 🫶
• -d, --device [Run-Time VENDOR]:[Run-Time PRODUCT][,[DFU Mode VENDOR]:[DFU Mode PRODUCT]] — Specify run-time and/or DFU mode vendor and/or product IDs of the DFU device to work with. VENDOR and PRODUCT are hexadecimal numbers (no prefix needed), "*" (match any), or "-" (match nothing). By default, any DFU capable device in either run-time or DFU mode will be considered.

If you only have one standards-compliant DFU device attached to your computer, this parameter is optional. But the second you have multiple DFU devices connected, dfu-util will detect this and abort, asking you to specify which device to use. it will not pick for you, it is not your wingman 😭

If only run-time IDs are specified (e.g. "--device 1457:51ab"), then in addition to the specified run-time IDs, any DFU mode devices will also be considered. This is beneficial to allow a DFU capable device to be found again after a switch to DFU mode, since the vendor and/or product ID of a device usually changes in DFU mode. main character behavior fr fr 👑

If only DFU mode IDs are specified (e.g. "--device ,951:26"), then all run-time devices will be ignored, making it easy to target a specific device in DFU mode. so clean, so targeted.

If both run-time and DFU mode IDs are specified (e.g. "--device 1457:51ab,:2bc"), then unspecified DFU mode components will use the run-time value specified.

Examples:

• --device 1457:51ab,951:26 Work with a device in run-time mode with vendor ID 0x1457 and product ID 0x51ab, or in DFU mode with vendor ID 0x0951 and product ID 0x0026
• --device 1457:51ab,:2bc Work with a device in run-time mode with vendor ID 0x1457 and product ID 0x51ab, or in DFU mode with vendor ID 0x1457 and product ID 0x02bc
• --device 1457:51ab Work with a device in run-time mode with vendor ID 0x1457 and product ID 0x51ab, or in DFU mode with any vendor and product ID
• --device ,951:26 Work with a device in DFU mode with vendor ID 0x0951 and product ID 0x0026
• --device *,- Work with any device in run-time mode, and ignore any device in DFU mode
• --device , Ignore any device in run-time mode, and Work with any device in DFU mode

• -p, --path BUS-PORT. ... .PORT — Specify the path to the DFU device. it's the address, the coordinates, the lil map 🗺️
• -c, --cfg CONFIG-NR — Specify the configuration of the DFU device. heads up though: this is only used for matching — the configuration is not set by dfu-util. it looks, it does not touch 🙈
• -i, --intf INTF-NR — Specify the DFU interface number.
• -a, --alt ALT — Specify the altsetting of the DFU interface by name or by number.
• -S, --serial [Run-Time SERIAL][,[DFU Mode SERIAL]] — Specify the run-time and DFU mode serial numbers used to further restrict device matches. If multiple, identical DFU devices are simultaneously connected to a system then vendor and product ID will be insufficient for targeting a single device. In this situation, it may be possible to use this parameter to specify a serial number which also must match.

If only a single serial number is specified, then the same serial number is used in both run-time and DFU mode. An empty serial number will match any serial number in the corresponding mode.

• -t, --transfer-size SIZE — Specify the number of bytes per USB transfer. The optimal value is usually determined automatically so this option is rarely useful. If you need to use this option for a device, please report it as a bug. 🐛 (like, genuinely, that's a them problem not a you problem)
• -Z, --upload-size SIZE — Specify the expected upload size, in bytes. Note that the value is only used for scaling the progress bar — the actual upload size is determined by the device. so it's cosmetic, it's the aesthetic, it's the fit check 💖
• -U, --upload FILE — Read firmware from device into FILE.
• -D, --download FILE — Write firmware from FILE into device. When FILE is -, the firmware is read from stdin.
• -R, --reset — Issue USB reset signalling after upload or download has finished. the lil goodbye wave 👋
• -e, --detach — Request that the device re-enumerate out of run-time mode and into DFU mode as when uploading or downloading, but exit immediately after sending the request. it says what it needs to say and leaves, iconic.
• -E, --detach-delay SECONDS — When uploading or downloading, wait SECONDS seconds for the device to re-enumerate after sending the detach request before giving up. Defaults to 5 seconds. This option has no effect with -e, since that causes dfu-util to immediately exit after sending the detach request.
• -w, --wait — Wait until matching device appears on the USB bus. the "I'll wait 🥺" option.
• -s, --dfuse-address [ADDRESS][:LENGTH][:MODIFIERS] — Specify target address for raw binary download/upload on DfuSe devices. Do not use this option for downloading DfuSe (.dfu) files. A length can be specified for uploads. Modifiers can be added after the address, separated by a colon, to perform special DfuSE commands such as "leave" DFU mode, "unprotect" and "mass-erase" flash memory. If the device can be expected to reset itself after the operation, "will-reset" should be added. The "force" modifier will override some sanity checks, and is also needed for the "unprotect" and "mass-erase" operations.

okay so "force" is literally overriding sanity checks. that's giving "hold my iced coffee" energy. know what you're doing before you type it 💀

• -v, --verbose — Print more information about dfu-util's operation. A second -v adds more details. A third -v activates verbose logging of USB requests (libusb debug output). yes, it stacks. three is the maximum drama setting 🔥
• -h, --help — Show a help text and exit.
• -V, --version — Show version information and exit.

---

🌈 EXAMPLES 🌈

Using dfu-util in the OpenMoko project

(with the Neo1973 hardware)

Flashing the rootfs:

$ dfu-util -a rootfs -R -D /path/to/openmoko-devel-image.jffs2

Flashing the kernel:

$ dfu-util -a kernel -R -D /path/to/uImage

Flashing the bootloader:

$ dfu-util -a u-boot -R -D /path/to/u-boot.bin

Copying a kernel into RAM:

$ dfu-util -a 0 -R -D /path/to/uImage

Once this has finished, the kernel will be available at the default load address of 0x32000000 in Neo1973 RAM.

Note: You cannot transfer more than 2MB of data into RAM using this method. that's the limit bestie, no pushing past it 😭

Using dfu-util with a DfuSe device

Flashing a .dfu (special DfuSe format) file to the device:

$ dfu-util -D /path/to/dfuse-image.dfu

Reading out 1 KB of flash starting at address 0x8000000:

$ dfu-util -a 0 -s 0x08000000:1024 -U newfile.bin

Flashing a binary file to address 0x8004000 of device memory and ask the device to leave DFU mode:

$ dfu-util -a 0 -s 0x08004000:leave -D /path/to/image.bin

---

🎀 BUGS 🎀

Please report any bugs to the dfu-util bug tracker at http://sourceforge.net/p/dfu-util/tickets/. Please use the --verbose option (repeated as necessary) to provide more information in your bug report. the more -v you stack, the more the devs can actually see what went wrong, so don't be shy 🫶

---

🔍 SEE ALSO 🔍

The dfu-util home page is http://dfu-util.sourceforge.net/ — go say hi 💖

---

📜 HISTORY 📜

dfu-util was originally written for the OpenMoko project by Weston Schmidt <weston_schmidt@yahoo.com> and Harald Welte <hwelte@hmw-consulting.de>. Over time, nearly complete support of DFU 1.0, DFU 1.1 and DfuSe ("1.1a") has been added. glow-up arc, honestly 🌟

---

⚖️ LICENCE ⚖️

dfu-util is covered by the GNU General Public License (GPL), version 2 or later. free as in freedom bestie 💜

---

©️ COPYRIGHT ©️

This manual page was originally written by Uwe Hermann <uwe@hermann-uwe.de>, and is now part of the dfu-util project.

---

okay that's the whole page!! this was dfu-util version 0.11, from September 2021, and yeah the manual name up top is DFU-UTIL(1) in case you were wondering why it's all shouty 💅 mwah, go flash something responsibly 🦋✨