Dfu-util

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Binaries)
(Mac: linkchg)
 
(31 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 
{{Languages|Dfu-util}}
 
{{Languages|Dfu-util}}
 
 
{{warning|Do not flash U-Boot unless you are sure you need to}}
 
{{note|You need to connect your neo directly to your pc with no hub between. Otherwise there could be problems with the hub and the usb reset.}}
 
{{note|Older versions of Dfu-util are broken on [http://en.wikipedia.org/wiki/Big_endian#Endianness_and_hardware big-endian] architectures. Make sure you're using SVN version r4696 or newer (7 Octcober 2008) if you're not on i386-32.}}
 
== Purpose ==
 
  
 
dfu-util is a program that implements the Host (PC) side of the [[USB DFU]] (Universal Serial Bus Device Firmware Upgrade) protocol.
 
dfu-util is a program that implements the Host (PC) side of the [[USB DFU]] (Universal Serial Bus Device Firmware Upgrade) protocol.
  
In the Openmoko project, we use this program to communicate with our specially enhanced [[u-boot]] boot loader, which implements the DFU device side.
+
In the Openmoko project, we use this program to communicate with our specially enhanced [[U-Boot]], which implements the DFU device side.
  
 
Using dfu-util and your smartphone, you can
 
Using dfu-util and your smartphone, you can
Line 19: Line 13:
  
 
== Source Code ==
 
== Source Code ==
 +
Dfu-util is currently maintained at http://dfu-util.gnumonks.org/.
 +
 
On Debian and Ubuntu, you'll need libusb-dev:
 
On Debian and Ubuntu, you'll need libusb-dev:
 
sudo apt-get install libusb-dev autogen pkg-config autotools-dev autoconf automake
 
sudo apt-get install libusb-dev autogen pkg-config autotools-dev autoconf automake
Line 25: Line 21:
 
yum install libusb-devel libusb-static
 
yum install libusb-devel libusb-static
  
On Gentoo you can emerge openmoko-dfu-util after unmasking it:
+
On Gentoo you can:
echo "app-mobilephone/openmoko-dfu-util      **" >> /etc/portage/package.keywords
+
emerge -va openmoko-dfu-util
emerge -va app-mobilephone/openmoko-dfu-util
+
  
You can check out and build the latest version of dfu-util using the following subversion commands:<br>
+
You can check out and build the latest version of dfu-util using the following git command:<br>
svn co https://svn.openmoko.org/trunk/src/host/dfu-util/<br>
+
git clone git://git.openezx.org/dfu-util.git
 +
<br>
 
cd dfu-util<br>
 
cd dfu-util<br>
 
./autogen.sh<br>
 
./autogen.sh<br>
Line 40: Line 36:
 
== Binaries ==
 
== Binaries ==
  
Binary packages will be [http://downloads.openmoko.org/releases/Om2008.9/dfu-util made available] as part of the regular Openmoko builds. Currently, there is a dfu-util for Linux/i386.
+
Binary packages will be [http://downloads.openmoko.org/distro/releases/Om2008.9/dfu-util made available] as part of the regular Openmoko builds. Currently, there is a dfu-util for Linux/i386.
  
 
You need to make the downloaded file (dfu-util) executable with:
 
You need to make the downloaded file (dfu-util) executable with:
Line 52: Line 48:
 
see below for full instructions.
 
see below for full instructions.
  
 +
=== Debian ===
 
[http://packages.debian.org/dfu-util dfu-util 0.0+r4880-1 is packaged] for Debian ''>= lenny'', so can be installed with: <tt>apt-get install dfu-util</tt>
 
[http://packages.debian.org/dfu-util dfu-util 0.0+r4880-1 is packaged] for Debian ''>= lenny'', so can be installed with: <tt>apt-get install dfu-util</tt>
  
 +
=== Ubuntu ===
 +
[http://packages.ubuntu.com/dfu-util dfu-util 0.0+r4067-3.1 is packaged] for Ubuntu ''>= intrepid (8.10)'', so can be installed with: <tt>apt-get install dfu-util</tt>
 +
 +
=== Slackware ===
 
[http://downloads.sourceforge.net/slackfr-packs/dfu-util-svn4686-i686-1cfdev12.1.tgz dfu-util is packaged] for '''Slackware''' (12.1), so can be installed with: <tt>pkgtool</tt>
 
[http://downloads.sourceforge.net/slackfr-packs/dfu-util-svn4686-i686-1cfdev12.1.tgz dfu-util is packaged] for '''Slackware''' (12.1), so can be installed with: <tt>pkgtool</tt>
  
 +
A newer SlackBuild is also available on [http://slackbuilds.org/repository/13.1/system/dfu-util/ slackbuilds.org]
 +
 +
=== Arch Linux ===
 
[http://aur.archlinux.org/packages.php?ID=21385 dfu-util is packaged] for Arch Linux, so can be installed with makepkg
 
[http://aur.archlinux.org/packages.php?ID=21385 dfu-util is packaged] for Arch Linux, so can be installed with makepkg
  
The links below install rpm package dfu-util in (open)SuSE :
+
=== openSuSE ===
 +
The links below install rpm packaged dfu-util in (open)SuSE :
  
[http://software.opensuse.org/ymp/home:worldcitizen/SLE_10/dfu-util.ymp 1-Click Install SLE 10]
+
[http://software.opensuse.org/ymp/home:worldcitizen/SLE_10/dfu-util.ymp 1-Click Install for SLE 10]
  
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_10.3/dfu-util.ymp 1-Click Install openSuSE 10.3]
+
[http://software.opensuse.org/ymp/home:worldcitizen/SLE_11/dfu-util.ymp 1-Click Install for SLE 11]
  
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_11.0/dfu-util.ymp 1-Click Install openSuSE 11.0]
+
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_10.3/dfu-util.ymp 1-Click Install for openSuSE 10.3]
  
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_11.1/dfu-util.ymp 1-Click Install openSuSE 11.1]
+
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_11.0/dfu-util.ymp 1-Click Install for openSuSE 11.0]
  
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_Factory/dfu-util.ymp 1-Click Install openSuSE Factory]
+
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_11.1/dfu-util.ymp 1-Click Install for openSuSE 11.1]
  
 +
[http://software.opensuse.org/ymp/home:worldcitizen/openSUSE_Factory/dfu-util.ymp 1-Click Install for openSuSE Factory]
  
Currently, there is a largely untested binary for Win32 (see [[Dfu-util-windows]]). Windows users can refer to [[No_Linux]] for a more tested approach.
+
=== CentOS ===
 +
[http://download.opensuse.org/repositories/home:/worldcitizen/CentOS_5/ Centos 5]
  
Compiling dfu-util on Mac:
+
=== Fedora ===
* http://lists.openmoko.org/pipermail/community/2007-July/008438.html
+
[http://download.opensuse.org/repositories/home:/worldcitizen/Fedora_10/ Fedora 9]
* [[User:SNMoore]]
+
* [[MacOS_X#Flashing_to_your_device]]
+
  
== Reference Documentation ==
+
[http://download.opensuse.org/repositories/home:/worldcitizen/Fedora_10/ Fedora 10]
  
To run dfu-util, you need to have /proc/bus/usb mounted and working. The terminal command "ls /proc/bus/usb" should return something similar to, "001  002  003  004  005  devices", it shouldn't be empty. If it is empty, use this command:
+
=== Mandriva ===
 +
[http://download.opensuse.org/repositories/home:/worldcitizen/Mandriva_2008/ Mandriva 2008]
  
<pre>
+
[http://download.opensuse.org/repositories/home:/worldcitizen/Mandriva_2009/ Mandriva 2009]
sudo mount -t usbfs usbfs /proc/bus/usb
+
</pre>
+
  
You can permanently add it in your fstab so that it automatically mounts. You can use emacs to edit you fstab using the command "sudo emacs /etc/fstab -nw" in your terminal window. Add the below line to your fstab:
+
=== RHEL ===
 +
[http://download.opensuse.org/repositories/home:/worldcitizen/RHEL_5/ RHEL 5]
  
<pre>
+
=== Gentoo ===
usbfs  /proc/bus/usb  usbfs  defaults
+
DFU-Util is in the main tree under the name [http://packages.gentoo.org/package/app-mobilephone/openmoko-dfu-util openmoko-dfu-util].
</pre>
+
  
 +
=== Windows ===
 +
Currently, there is a largely untested binary for Win32 (see [[Dfu-util-windows]]). Windows users can refer to [[No_Linux]] for a more tested approach.
  
=== Before using dfu-util ===
+
=== Mac ===
You'll need to boot your phone into the NAND Boot Menu:
+
Compiling dfu-util on Mac:
* Ensure your phone is connected directly to the host computer by USB (not the USB-charger! :)
+
* http://lists.openmoko.org/pipermail/community/2007-July/008438.html
* Ensure that you execute all dfu-util commands as root
+
* [[User:SNMoore]]
* Power off the phone
+
* [[MacOS_X#Flashing_to_your_device]]
* Hold down AUX
+
* [[Openmoko Flasher]] has a precompiled binary in the App bundle
* Press POWER until the Boot Menu appears
+
see also [[Booting the Neo FreeRunner]]
+
 
+
=== Command-line options ===
+
 
+
==== --help ====
+
 
+
<pre>
+
dfu-util - (C) 2007 by Openmoko Inc.
+
This program is Free Software and has ABSOLUTELY NO WARRANTY
+
 
+
Usage: dfu-util [options] ...
+
-h --help                    Print this help message
+
-V --version                  Print the version number
+
-l --list                    List the currently attached DFU capable USB devices
+
-d --device vendor:product    Specify Vendor/Product ID of DFU device
+
-c --cfg config_nr            Specify the Configuration of DFU device
+
-i --intf intf_nr            Specify the DFU Interface number
+
-a --alt alt_nr              Specify the Altseting of the DFU Interface
+
-t --transfer-size            Specify the number of bytes per USB Transfer
+
-U --upload file              Read firmware from device into <file>
+
-D --download file            Write firmware from <file> into device
+
-R --reset                    Issue USB Reset signalling once we're finished
+
</pre>
+
 
+
==== --alt ====
+
With the -a switch you specify the location on the device you want to write to or read from.
+
However, for most cases, ''kernel'' and ''rootfs'' will be enough.
+
 
+
See [[Neo_FreeRunner_partitions]] for a list. You may also use the ''--list'' switch (see below), to get an online list.
+
 
+
==== --list ====
+
 
+
Using the --list option, you can list the available DFU capable devices, their configuration, interface and altsettings.
+
Below is an example for a current Neo1973 phone in u-boot '''Runtime Mode'''
+
<pre>
+
# ./dfu-util --list
+
dfu-util - (C) 2007 by Openmoko Inc.
+
This program is Free Software and has ABSOLUTELY NO WARRANTY
+
 
+
Found DFU Runtime: [0x1457:0x5119] devnum=0, cfg=0, intf=2, alt=0, name="USB Device Firmware Upgrade"
+
</pre>
+
 
+
Below is an example for a current Neo1973 phone in u-boot '''DFU Mode'''
+
<pre>
+
# ./dfu-util --list
+
dfu-util - (C) 2007 by Openmoko Inc.
+
This program is Free Software and has ABSOLUTELY NO WARRANTY
+
 
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=0, name="RAM 0x32000000"
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=1, name="u-boot"
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=2, name="u-boot_env"
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=3, name="kernel"
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=4, name="splash"
+
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=5, name="rootfs"
+
</pre>
+
 
+
This shows you six interfaces, all in '''configuration 0''' and '''interface 0''', with altsetting 0...5, for RAM and each [[Partitions|partition]].
+
 
+
==== --device ====
+
 
+
You can specify the USB Vendor and Product ID of the device you want to program:
+
 
+
dfu-util --device 0x1457:0x5119
+
 
+
If you only have one standards-compliant DFU device attached to your PC, this is optional.  However, as soon as you have multiple DFU devices, dfu-util will detect this and abort, asking you to specify which device it shall use.
+
 
+
==== --transfer-size ====
+
 
+
Specifies the size of each individual USB transfer.  If you don't use it, the maximum possible size for your combination of host operating system and USB device is chosen (for optimal performance).
+
 
+
==== --download ====
+
 
+
download the given file into the device.
+
 
+
==== --upload ====
+
 
+
upload from the DFU device into the given file[name].
+
 
+
{{note|Upload support is currently broken - [http://docs.openmoko.org/trac/ticket/676 #676]}}
+
 
+
== Phrasebook ==
+
 
+
There's no full-fledged manual yet.  Instead, some examples:
+
 
+
=== 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
+
 
+
=== Flashing the splash image ===
+
 
+
dfu-util -a splash -R -D /path/to/splash.gz
+
 
+
see also [[Configuring_the_boot_splash_screens]]
+
 
+
=== 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}}
+
 
+
== Troubleshooting notes ==
+
 
+
If during flashing of an image using dfu-util you're consistently getting an error -110 message, check that the size of the destination NAND [[Partitions|partition]] is big enough to hold the image.  For example the kernel partition is only 2 MB big by default and a kernel with debugging info compiled-in can often exceed this.  It's possible to change the partition layout to enlarge a given partition and shrink other partitions but you have to remember to reflash all partitions whose start offset has changed afterwards.  To adjust partitions layout use the ''mtdparts'' [[Bootloader|u-boot command]].
+
 
+
If in turn you're facing errors in seemingly random places during the flashing of images, most likely the USB hub or cable through which your Neo1973 is connected, is of too poor quality.  It is recommended that you always connect the phone directly to the host when using dfu-util.
+
 
+
If dfu-util reports a message like the following, before it starts flashing:<pre>
+
Resetting USB...
+
not at least 2 device changes found ?!?
+
Lost device after RESET?</pre> retry the command - it should work on a second run.
+
 
+
If dfu-util complains about not being able to program the device while in runtime mode, do the following: while in the boot menu, remove the usb cable and insert it again. Depending on the version of uBoot it should display somewhere in the menu that it is now in DFU mode. Now dfu-util should be able to continue.
+
  
If dfu-util is too slow on Windows, that's a known bug. A suggestion is to run Linux on a virtual box. An full root image 97MB that is 776Mbit, the USB 1.1 on the Neo FreeRunner is capable of either 1.5 Mbit/s (Low-Speed) and 12 Mbit/s (Full-Speed). So flashing it should take less than 9 minutes with low speed and a bit more than a minute with full-speed. Plus transfer overhead, plus decompression on the Neo side.
+
== Manual ==
  
Note that any error messages indicate a probable failed transfer, despite latter messages emitted about success, etc.
+
See [[Manuals/Dfu-util]]
  
 
== See also ==
 
== See also ==
*[[Flashing the Neo 1973]] to the latest software.
+
*[[Flashing the Neo 1973]]
 
*[[Flashing the Neo FreeRunner]]
 
*[[Flashing the Neo FreeRunner]]
  
 
[[Category:Flashing Openmoko]]
 
[[Category:Flashing Openmoko]]

Latest revision as of 18:24, 13 February 2012


dfu-util is a program that implements the Host (PC) side of the USB DFU (Universal Serial Bus Device Firmware Upgrade) protocol.

In the Openmoko project, we use this program to communicate with our specially enhanced U-Boot, which implements the DFU device side.

Using dfu-util and your smartphone, you can

  • transfer and flash partitions in internal NAND Flash.
  • transfer anything into RAM
    • this can be used for fast development cycles of low-level code such as kernels without flashing them
  • read out the current internal NAND partitions
    • this is an easy and efficient way of doing full backups of your phone

Contents

[edit] Source Code

Dfu-util is currently maintained at http://dfu-util.gnumonks.org/.

On Debian and Ubuntu, you'll need libusb-dev: sudo apt-get install libusb-dev autogen pkg-config autotools-dev autoconf automake

On Fedora you'll need libusb-devel and libusb-static: yum install libusb-devel libusb-static

On Gentoo you can: emerge -va openmoko-dfu-util

You can check out and build the latest version of dfu-util using the following git command:
git clone git://git.openezx.org/dfu-util.git
cd dfu-util
./autogen.sh
./configure
make

The resulting binary is dfu-util/src/dfu-util.

[edit] Binaries

Binary packages will be made available as part of the regular Openmoko builds. Currently, there is a dfu-util for Linux/i386.

You need to make the downloaded file (dfu-util) executable with:

chmod +x dfu-util

you can then run it with

./dfu-util

see below for full instructions.

[edit] Debian

dfu-util 0.0+r4880-1 is packaged for Debian >= lenny, so can be installed with: apt-get install dfu-util

[edit] Ubuntu

dfu-util 0.0+r4067-3.1 is packaged for Ubuntu >= intrepid (8.10), so can be installed with: apt-get install dfu-util

[edit] Slackware

dfu-util is packaged for Slackware (12.1), so can be installed with: pkgtool

A newer SlackBuild is also available on slackbuilds.org

[edit] Arch Linux

dfu-util is packaged for Arch Linux, so can be installed with makepkg

[edit] openSuSE

The links below install rpm packaged dfu-util in (open)SuSE :

1-Click Install for SLE 10

1-Click Install for SLE 11

1-Click Install for openSuSE 10.3

1-Click Install for openSuSE 11.0

1-Click Install for openSuSE 11.1

1-Click Install for openSuSE Factory

[edit] CentOS

Centos 5

[edit] Fedora

Fedora 9

Fedora 10

[edit] Mandriva

Mandriva 2008

Mandriva 2009

[edit] RHEL

RHEL 5

[edit] Gentoo

DFU-Util is in the main tree under the name openmoko-dfu-util.

[edit] Windows

Currently, there is a largely untested binary for Win32 (see Dfu-util-windows). Windows users can refer to No_Linux for a more tested approach.

[edit] Mac

Compiling dfu-util on Mac:

[edit] Manual

See Manuals/Dfu-util

[edit] See also

Personal tools


WARNING: Do not flash U-Boot unless you are sure you need to


NOTE: You need to connect your neo directly to your pc with no hub between. Otherwise there could be problems with the hub and the usb reset.


NOTE: Older versions of Dfu-util are broken on big-endian architectures. Make sure you're using SVN version r4696 or newer (7 Octcober 2008) if you're not on i386-32.


Purpose

dfu-util is a program that implements the Host (PC) side of the USB DFU (Universal Serial Bus Device Firmware Upgrade) protocol.

In the Openmoko project, we use this program to communicate with our specially enhanced u-boot boot loader, which implements the DFU device side.

Using dfu-util and your smartphone, you can

  • transfer and flash partitions in internal NAND Flash.
  • transfer anything into RAM
    • this can be used for fast development cycles of low-level code such as kernels without flashing them
  • read out the current internal NAND partitions
    • this is an easy and efficient way of doing full backups of your phone

Source Code

On Debian and Ubuntu, you'll need libusb-dev: sudo apt-get install libusb-dev autogen pkg-config autotools-dev autoconf automake

On Fedora you'll need libusb-devel and libusb-static: yum install libusb-devel libusb-static

On Gentoo you can emerge openmoko-dfu-util after unmasking it: echo "app-mobilephone/openmoko-dfu-util **" >> /etc/portage/package.keywords emerge -va app-mobilephone/openmoko-dfu-util

You can check out and build the latest version of dfu-util using the following subversion commands:
svn co https://svn.openmoko.org/trunk/src/host/dfu-util/
cd dfu-util
./autogen.sh
./configure
make

The resulting binary is dfu-util/src/dfu-util.

Binaries

Binary packages will be made available as part of the regular Openmoko builds. Currently, there is a dfu-util for Linux/i386.

You need to make the downloaded file (dfu-util) executable with:

chmod +x dfu-util

you can then run it with

./dfu-util

see below for full instructions.

dfu-util 0.0+r4880-1 is packaged for Debian >= lenny, so can be installed with: apt-get install dfu-util

dfu-util is packaged for Slackware (12.1), so can be installed with: pkgtool

dfu-util is packaged for Arch Linux, so can be installed with makepkg

The links below install rpm package dfu-util in (open)SuSE :

1-Click Install SLE 10

1-Click Install openSuSE 10.3

1-Click Install openSuSE 11.0

1-Click Install openSuSE 11.1

1-Click Install openSuSE Factory


Currently, there is a largely untested binary for Win32 (see Dfu-util-windows). Windows users can refer to No_Linux for a more tested approach.

Compiling dfu-util on Mac:

Reference Documentation

To run dfu-util, you need to have /proc/bus/usb mounted and working. The terminal command "ls /proc/bus/usb" should return something similar to, "001 002 003 004 005 devices", it shouldn't be empty. If it is empty, use this command:

sudo mount -t usbfs usbfs /proc/bus/usb

You can permanently add it in your fstab so that it automatically mounts. You can use emacs to edit you fstab using the command "sudo emacs /etc/fstab -nw" in your terminal window. Add the below line to your fstab:

usbfs   /proc/bus/usb   usbfs   defaults


Before using dfu-util

You'll need to boot your phone into the NAND Boot Menu:

  • Ensure your phone is connected directly to the host computer by USB (not the USB-charger! :)
  • Ensure that you execute all dfu-util commands as root
  • Power off the phone
  • Hold down AUX
  • Press POWER until the Boot Menu appears

see also Booting the Neo FreeRunner

Command-line options

--help

dfu-util - (C) 2007 by Openmoko Inc.
This program is Free Software and has ABSOLUTELY NO WARRANTY

Usage: dfu-util [options] ...
-h --help                     Print this help message
-V --version                  Print the version number
-l --list                     List the currently attached DFU capable USB devices
-d --device vendor:product    Specify Vendor/Product ID of DFU device
-c --cfg config_nr            Specify the Configuration of DFU device
-i --intf intf_nr             Specify the DFU Interface number
-a --alt alt_nr               Specify the Altseting of the DFU Interface
-t --transfer-size            Specify the number of bytes per USB Transfer
-U --upload file              Read firmware from device into <file>
-D --download file            Write firmware from <file> into device
-R --reset                    Issue USB Reset signalling once we're finished

--alt

With the -a switch you specify the location on the device you want to write to or read from. However, for most cases, kernel and rootfs will be enough.

See Neo_FreeRunner_partitions for a list. You may also use the --list switch (see below), to get an online list.

--list

Using the --list option, you can list the available DFU capable devices, their configuration, interface and altsettings. Below is an example for a current Neo1973 phone in u-boot Runtime Mode

# ./dfu-util --list
dfu-util - (C) 2007 by Openmoko Inc.
This program is Free Software and has ABSOLUTELY NO WARRANTY

Found DFU Runtime: [0x1457:0x5119] devnum=0, cfg=0, intf=2, alt=0, name="USB Device Firmware Upgrade"

Below is an example for a current Neo1973 phone in u-boot DFU Mode

# ./dfu-util --list
dfu-util - (C) 2007 by Openmoko Inc.
This program is Free Software and has ABSOLUTELY NO WARRANTY

Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=0, name="RAM 0x32000000"
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=1, name="u-boot"
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=2, name="u-boot_env"
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=3, name="kernel"
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=4, name="splash"
Found DFU: [0x1457:0x5119] devnum=16, cfg=0, intf=0, alt=5, name="rootfs"

This shows you six interfaces, all in configuration 0 and interface 0, with altsetting 0...5, for RAM and each partition.

--device

You can specify the USB Vendor and Product ID of the device you want to program:

dfu-util --device 0x1457:0x5119

If you only have one standards-compliant DFU device attached to your PC, this is optional. However, as soon as you have multiple DFU devices, dfu-util will detect this and abort, asking you to specify which device it shall use.

--transfer-size

Specifies the size of each individual USB transfer. If you don't use it, the maximum possible size for your combination of host operating system and USB device is chosen (for optimal performance).

--download

download the given file into the device.

--upload

upload from the DFU device into the given file[name].

NOTE: Upload support is currently broken - #676


Phrasebook

There's no full-fledged manual yet. Instead, some examples:

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

Flashing the splash image

dfu-util -a splash -R -D /path/to/splash.gz

see also Configuring_the_boot_splash_screens

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


Troubleshooting notes

If during flashing of an image using dfu-util you're consistently getting an error -110 message, check that the size of the destination NAND partition is big enough to hold the image. For example the kernel partition is only 2 MB big by default and a kernel with debugging info compiled-in can often exceed this. It's possible to change the partition layout to enlarge a given partition and shrink other partitions but you have to remember to reflash all partitions whose start offset has changed afterwards. To adjust partitions layout use the mtdparts u-boot command.

If in turn you're facing errors in seemingly random places during the flashing of images, most likely the USB hub or cable through which your Neo1973 is connected, is of too poor quality. It is recommended that you always connect the phone directly to the host when using dfu-util.

If dfu-util reports a message like the following, before it starts flashing:
Resetting USB...
not at least 2 device changes found ?!?
Lost device after RESET?
retry the command - it should work on a second run.

If dfu-util complains about not being able to program the device while in runtime mode, do the following: while in the boot menu, remove the usb cable and insert it again. Depending on the version of uBoot it should display somewhere in the menu that it is now in DFU mode. Now dfu-util should be able to continue.

If dfu-util is too slow on Windows, that's a known bug. A suggestion is to run Linux on a virtual box. An full root image 97MB that is 776Mbit, the USB 1.1 on the Neo FreeRunner is capable of either 1.5 Mbit/s (Low-Speed) and 12 Mbit/s (Full-Speed). So flashing it should take less than 9 minutes with low speed and a bit more than a minute with full-speed. Plus transfer overhead, plus decompression on the Neo side.

Note that any error messages indicate a probable failed transfer, despite latter messages emitted about success, etc.

See also