Manuals/dfu-util

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Before using dfu-util: moving content here from Flashing the Neo FreeRunner)
(Exchg bootloader with U-Boot)
 
(3 intermediate revisions by one user not shown)
Line 1: Line 1:
This manual describes the usage of [[Dfu-util]].
+
This manual describes the usage of [[dfu-util]].
  
 
== Reference Documentation ==
 
== Reference Documentation ==
Line 129: Line 129:
  
 
=== Flashing the rootfs ===
 
=== Flashing the rootfs ===
 +
 +
The root filesystem has to be an image in jffs2 format. If the file you downloaded is zipped or compressed (has a .gz, bz2, .zip, tar, tar.gz or .tgz extension) you have to uncompress it first.
  
 
dfu-util -a rootfs -R -D /path/to/openmoko-devel-image.jffs2
 
dfu-util -a rootfs -R -D /path/to/openmoko-devel-image.jffs2
Line 138: Line 140:
 
dfu-util -a kernel -R -D /path/to/uImage
 
dfu-util -a kernel -R -D /path/to/uImage
  
=== Flashing the bootloader ===
+
=== Flashing the bootloader [[U-Boot]] ===
  
 
dfu-util -a u-boot -R -D /path/to/u-boot.bin
 
dfu-util -a u-boot -R -D /path/to/u-boot.bin
Line 165: Line 167:
 
== Troubleshooting notes ==
 
== 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 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'' [[U-Boot|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 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.

Latest revision as of 09:48, 10 February 2012

This manual describes the usage of dfu-util.

Contents

[edit] 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


[edit] Before using dfu-util

  • Read the other sections of this page first, because you will have 30 seconds to enter the flashing commands, come back here when ready.
  • Do not connect the USB cable from the PC to your Neo yet (disconnect it).
  • Boot your Neo into the NOR uBoot menu for flashing:
    • Turn off the Neo
    • Press and hold the AUX button
    • Press the Power button until the boot menu comes up
    • This menu is labelled *** BOOT MENU (NOR) ***
    • See also Booting the Neo FreeRunner
  • Stay in NOR uBoot menu, do not select or enter any item in the menu. Now you will be able to flash, make backups of your FreeRunner or query the FreeRunner with dfu-util.
  • The FreeRunner only stays at the NOR boot prompt for about 30 seconds and then shuts off unless you do something.
  • Connect your Neo to your computer directly (Using a hub in between could cause problems with the hub and the usb reset)
  • Now you can enter the dfu-util commands on your PC as described below.
  • If the Neo FreeRunner turns off before you press start flashing (screen goes black), go back to step 2. If you start flashing in time, the phone will not turn off meanwhile.

Note: Some myth existed that dfu-util is not worked with sudo. This is not true of course. It is working from both sudo and su sessions. --Gena2x 12:30, 20 July 2010 (UTC)

Note that the dfu-util connection does not use Ethernet over USB - that is, you should not attempt to set up a usb0 network interface on your GNU/Linux host desktop (on Windows, you need a DFU class driver, or you can use the LibUSB-Win32 driver described on the Dfu-util-windows page). The dfu-util utility sets up its own connection to the FreeRunner. In fact, you will not be able to make an Ethernet-over-USB connection to the FreeRunner when it is at the uBoot menu; this type of connection is only available when the FreeRunner has booted fully.

After connecting the FreeRunner to your host via USB cable, you can test whether dfu-util "sees" the FreeRunner by executing:

dfu-util -l

If you get error messages from the dfu-util command then try again. Often it works on the second try.

dfu-util uses the DeviceFirmwareUpgrade protocol, and may list more than one device. If so, try unplugging the other device (e.g. a USB mouse) or using the -d switch to tell dfu-util which device it should talk to, as described at the relevant bug report [1].

Also, please remember to execute the dfu-util command with sufficient privileges (ie. root) -- you will need complete control over the usb bus.

[edit] Command-line options

[edit] --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

[edit] --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 partitions for a list. You may also use the --list switch (see below), to get an online list.

[edit] --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.

[edit] --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.

[edit] --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).

[edit] --download

download the given file into the device.

[edit] --upload

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

NOTE: Upload support is currently broken - #676


[edit] Phrasebook

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

[edit] Flashing the rootfs

The root filesystem has to be an image in jffs2 format. If the file you downloaded is zipped or compressed (has a .gz, bz2, .zip, tar, tar.gz or .tgz extension) you have to uncompress it first.

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

Flashing the rootfs can take up to 15 minutes for a ~70MB image.

[edit] Flashing the kernel

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

[edit] Flashing the bootloader U-Boot

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

[edit] Flashing the splash image

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

see also Configuring_the_boot_splash_screens

[edit] 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


[edit] Success message

If flashing was successfull the following will be shown:

status(0) = No error condition is present
Done!

[edit] 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.

Personal tools

This manual describes the usage of Dfu-util.

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

  • Read the other sections of this page first, because you will have 30 seconds to enter the flashing commands, come back here when ready.
  • Do not connect the USB cable from the PC to your Neo yet (disconnect it).
  • Boot your Neo into the NOR uBoot menu for flashing:
    • Turn off the Neo
    • Press and hold the AUX button
    • Press the Power button until the boot menu comes up
    • This menu is labelled *** BOOT MENU (NOR) ***
    • See also Booting the Neo FreeRunner
  • Stay in NOR uBoot menu, do not select or enter any item in the menu. Now you will be able to flash, make backups of your FreeRunner or query the FreeRunner with dfu-util.
  • The FreeRunner only stays at the NOR boot prompt for about 30 seconds and then shuts off unless you do something.
  • Connect your Neo to your computer directly (Using a hub in between could cause problems with the hub and the usb reset)
  • Now you can enter the dfu-util commands on your PC as described below.
  • If the Neo FreeRunner turns off before you press start flashing (screen goes black), go back to step 2. If you start flashing in time, the phone will not turn off meanwhile.

Note: Some myth existed that dfu-util is not worked with sudo. This is not true of course. It is working from both sudo and su sessions. --Gena2x 12:30, 20 July 2010 (UTC)

Note that the dfu-util connection does not use Ethernet over USB - that is, you should not attempt to set up a usb0 network interface on your GNU/Linux host desktop (on Windows, you need a DFU class driver, or you can use the LibUSB-Win32 driver described on the Dfu-util-windows page). The dfu-util utility sets up its own connection to the FreeRunner. In fact, you will not be able to make an Ethernet-over-USB connection to the FreeRunner when it is at the uBoot menu; this type of connection is only available when the FreeRunner has booted fully.

After connecting the FreeRunner to your host via USB cable, you can test whether dfu-util "sees" the FreeRunner by executing:

dfu-util -l

If you get error messages from the dfu-util command then try again. Often it works on the second try.

dfu-util uses the DeviceFirmwareUpgrade protocol, and may list more than one device. If so, try unplugging the other device (e.g. a USB mouse) or using the -d switch to tell dfu-util which device it should talk to, as described at the relevant bug report [1].

Also, please remember to execute the dfu-util command with sufficient privileges (ie. root) -- you will need complete control over the usb bus.

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 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 rootfs can take up to 15 minutes for a ~70MB image.

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


Success message

If flashing was successfull the following will be shown:

status(0) = No error condition is present
Done!

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.