Flashing the Neo FreeRunner

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Flashing the boot loader to the NAND: replaced sudo with #)
(Quick Step-By-Step Summary: spelling)
 
(29 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
{{Languages|Flashing_the_Neo_FreeRunner}}
 
{{Languages|Flashing_the_Neo_FreeRunner}}
Openmoko regularly releases updated versions of the Openmoko root filesystem, the [[kernel]], and the [[Bootloader]] (either [[Uboot]] or [[Qi]]) as binary images. These may be programmed into the [[NAND_Flash|Flash memory (NAND)]] of Neo FreeRunner. For that, you can use the USB cable and another computer which will run an Openmoko-provided tool to flash the Neo FreeRunner "through" USB.
+
Most of the software on the Neo FreeRunner can be updated or changed. The root filesystem, the [[kernel]], and the [[Bootloader]] can be modified with the program [[dfu-util]] from a computer. This page does not describe flashing the [[NOR Flash]] which requires a [[debug board]]. See [[Flashing NOR]] for this procedure.  
  
== 3 software components and 2 kinds of storage ==
+
The [[NAND Flash]] is divided into 3 partitions for the bootloader, kernel, and root filesystem. Each component can be flashed separately.
  
Inside the FreeRunner 3 software components are working:
+
The '''bootloader''' is a small program that runs first and starts everything else when the FreeRunner is powered on. The bootloader is independent of the distribution you use.
* '''bootloader''': a small program that runs first and starts everything else when the FreeRunner is powered on or reset (depending on [[Booting the Neo FreeRunner|how you reset it]], the version from [[NOR_Flash|NOR]] or NAND is booted).
+
The '''kernel''' and the '''root filesystem''' are provided by the distribution.  
* '''kernel''': the central component in the Linux operating system.
+
* '''root filesystem''': contains all the files that make up the commands and applications that you can run.
+
All software components in the FreeRunner are bundled together into binary images.
+
 
+
The FreeRunner has two kinds of internal program storage: NOR flash and NAND flash. On a desktop computer when you want to replace the operating system (OS), you would boot it from a CD-ROM drive, then copy OS files from the CD to the internal hard drive. The FreeRunner does not have a CD-ROM drive and files must typically be re-written/flashed directly into internal storage (NAND flash). Alternatively, it is possible to boot from a microSD where all the files have been loaded onto.
+
 
+
NOR flash is small and stores only a special boot program used when you need to re-write the contents of the NAND flash. Usually it is not necessary to re-write the NOR flash. Instructions to do so is here: [[Flashing NOR]].
+
 
+
NAND flash acts more like a hard drive. It is divided into 3 partitions for the bootloader, kernel, and root filesystem. Being on different partitions, each component can be flashed separately. For example if you are trying to install a modified kernel, you only have to follow the steps to flash the kernel image.
+
  
 
'''Before you start: Erasing the root filesystem or flashing the bootloader are radical measures. Take the time to ponder the necessity. Sometimes problems can be fixed by only updating the kernel.'''
 
'''Before you start: Erasing the root filesystem or flashing the bootloader are radical measures. Take the time to ponder the necessity. Sometimes problems can be fixed by only updating the kernel.'''
  
== Alternative : running from microSD card ==
+
== Image files to flash into FreeRunner memory ==
 
+
You may install this distribution on the microSD card, in order to [[Booting from SD | boot from microSD card]]. That allows you to keep another distribution installed in NAND (for instance to test 2008.08 while still having 2007.2 for default boot).
+
 
+
== Software you need ==
+
 
+
=== #1 Tools for flashing: DFU-util and NeoTool ===
+
 
+
Note that there are some issues using dfu-util with sudo.
+
 
+
'''Don't use sudo with dfu-util. Make sure you are root before using dfu-util!'''
+
 
+
''Command-line''. DFU-util, the tool to flash the FreeRunner has to be installed on you laptop or desktop machine. It is available for Linux, MacOS X, and Windows (see links below). DFU-util allows you to connect to the FreeRunner through the USB cable and control its bootloader. That connection uses a special protocol which addresses the bootloader's interface, and differs from USB networking. For more details, see the separate [[dfu-util]] page.
+
 
+
''GUI''. Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the [[NeoTool]] page.
+
 
+
'''Linux:''' http://downloads.openmoko.org/distro/releases/Om2008.9/dfu-util
+
 
+
Make sure it is executable by setting the permissions with this command: chmod a+x dfu-util
+
 
+
'''Linux 64-bit:''' You need 64-bit version of dfu-util, which usually can be found in your distribution repository.
+
If your distribution does not provide 64-bit dfu-util, or it consistently fails with a "-62" error, you have two ways to go:
+
# Seek for 32-bit machine and do flashing form it.
+
# Use 32-bit chroot (on amd64 debian). Worked for me --[[User:Bubak|Bubak]] 16:54, 4 September 2008 (UTC).
+
# Just try the 32-bit dfu-util. Worked fine on my x86_64 Fedora 10 --[[User:Pcfe|pcfe]] 2009-01-16.
+
#* I can confirm this (Gentoo multilib x86_64) --[[User:Unlotto|Unlotto]] 14:15, 4 February 2009 (UTC)
+
#* I can confirm this (OpenSuSE 11.0 x86_64) --[[User:muthusuba|muthusuba]] 29 July 2009
+
 
+
'''MacOS X:''' [[MacOS_X#Graphical_Flashing_with_Openmoko_Flasher]]
+
 
+
'''Windows:''' http://projects.openmoko.org/frs/?group_id=166&release_id=162
+
 
+
See additional driver installation instructions for Windows at [[Dfu-util-windows]]
+
 
+
'''Virtual machines''' While there has been some limited success reported using dfu-util from within a Virtual Machine (such as VMware), in general it is not possible to use dfu-util in this fashion.  You must use dfu-util on an operating system that has direct access to the physical USB device hardware.
+
 
+
=== #2 Image files to flash into FreeRunner memory ===
+
  
There are separate image files for all 3 software components and depending on what you want to install, you pick the respective image file. In most cases you will need to install a Kernel (uImage) and a Root Filesystem (rootfs). In rare cases, when there is a bug you need fixed, you will also install a new bootloader.
+
There are separate image files for all 3 software components. In most cases you will need to install a Kernel (uImage) and a Root Filesystem (rootfs). In rare cases, when there is a bug you need fixed, you will also install a new bootloader.
  
 
Please read [[Distributions]] for choosing the distribution which fits your needs, and then see [[Download]] for downloading.
 
Please read [[Distributions]] for choosing the distribution which fits your needs, and then see [[Download]] for downloading.
 
== Boot the FreeRunner from NOR Flash ==
 
 
[[Image:menu15.jpg|thumb|Booting from NOR Flash]]
 
 
# Read the other sections of this page first, because you will have 30 seconds to enter the flashing commands, come back here when ready.
 
# Make sure your FreeRunner is off.
 
# Do not connect the USB cable from the PC to your Neo FreeRunner yet (disconnect it).
 
# Boot your Neo FreeRunner into the NOR uBoot menu for flashing.
 
## Press and hold 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 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 the GNU/Linux or Windows host via a USB cable.
 
# 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.
 
 
<!-- The following, upto dfu-util -l is taken from the thread "Re: FreeRunner (GTK2007.2) has suddenly become unbootable" on the Support list. -->
 
 
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:
 
 
<pre>dfu-util -l</pre>
 
 
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 [http://docs.openmoko.org/trac/ticket/2039].
 
 
Also, please remember to execute the dfu-util command with sufficient privileges (ie. root) -- you will need complete control over the usb bus.
 
  
 
== Do a backup ==
 
== Do a backup ==
Line 98: Line 21:
 
== Using dfu-util ==
 
== Using dfu-util ==
  
dfu-util can be used to read flash memory, write memory, and get information from the device.
+
[[Dfu-util]] is a command-line tool to flash the FreeRunner. It is available for Linux, MacOS X, and Windows. DFU-util allows you to connect to the FreeRunner through the USB cable and control its bootloader. That connection uses a special protocol which addresses the bootloader's interface, and differs from USB networking. For more details, see the separate [[dfu-util]] page.
  
This is the general command format to write an image file to a (predefined) "partition name" (referred to as ''altsetting'' in dfu-util help/manual) :
+
See [[Manuals/Dfu-util]]
  
# dfu-util -a ''<altsetting>'' -R -D ''<file_name>''
+
=== NeoTool (GUI) ===
  
where:<br>
+
Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the [[NeoTool]] page.
-a ''altsetting'' : Specify the altsetting of the DFU interface by name or by number<br>
+
-: Issue USB Reset signalling once we're finished<br>
+
-D  ''file_name'' : Write firmware from ''file_name'' into device
+
  
On Linux, you run dfu-util from a command shell prompt. If you have not put it somewhere on your command path you probably need to prefix it with a "./" like this '''./dfu-util'''.
+
=== DFUScript - A command line script to simplify dfu-util ===
On some systems you need to be root before this will work and on Ubuntu you must preface the command with "sudo" or you will get the following error: "Cannot claim interface: could not claim interface 2: Operation not permitted"
+
  
On Windows, you need to open a command window and run from a command line. Use Start-Run Program and type "cmd" to open a Window.
+
DFUScript was developed to assist users who have multiple devices in using dfu-util via the command line. Information on where to download and use DFUScript can be found on [[DFUScript]].
  
More detailed manual for dfu-util is available here : [[Dfu-util]]
+
== Alternative: using nandwrite ==
  
GUI frontend for dfu-util (and more): [[NeoTool]]
+
This approach involves writing the '''rootfs''' into nand directly on the phone from a system already running on it, not necessarily via usb from a computer.
  
== Flashing the Kernel ==
+
If you have a system running from a different partition that you intend to flash (for example sd card), you can use nandwrite to do the work, which is much faster (it takes about 30s to write a 59MB jffs2 image).
  
Note: The phone needs to be in the U-boot bootup menu for this to work.
+
See [[Nandwrite]] for more information.
      Get there by holding down the aux button while powering up the device.
+
  
The command format is:
+
== Optional: Verifying boot-loader version ==
 
+
# dfu-util -a kernel -R -D ''/path/to/uImage''
+
 
+
When flashing succeeds the following will be shown:
+
 
+
status(0) = No error condition is present
+
Done!
+
 
+
Flashing may fail with an error -110. This indicates that the kernel is too big for the default kernel partition. uboot can be used to change the size of the default partitions on the device. It may also mean that you are trying to put the wrong thing in the kernel space.
+
 
+
== Flashing the Root Filesystem ==
+
 
+
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.
+
 
+
The command format is:
+
 
+
<pre>
+
# dfu-util -a rootfs -R -D rootfs_filename.jffs2
+
</pre>
+
| U-Boot
+
where ''rootfs_filename.jffs2'' is the name of the file containing the root file system.
+
 
+
The flashing process can take up to 15 minutes for a ~70MB image. It is also wise to make sure that your Neo has enough battery charge prior to flashing.
+
 
+
When flashing succeeds the following will be shown:
+
 
+
<pre>
+
status(0) = No error condition is present
+
Done!
+
</pre>
+
 
+
== Flashing the boot loader to the NAND==
+
 
+
{{Note|In most cases you don't need to flash your bootloader. Flash it only if you want to update for a specific feature or due to a specific problem.}}
+
 
+
The boot loader (U-boot) file should have a .bin extension. As with the root filesystem, if the file you downloaded is zipped or compressed (has a .gz or .zip extension) you have to uncompress it first.
+
 
+
The command format is:
+
 
+
# dfu-util -a u-boot -R -D ''uboot.bin''
+
 
+
where ''uboot.bin'' is the name of the boot loader binary image file.
+
 
+
''Reminder'': You should have [[Flashing_the_Neo_FreeRunner#Boot_the_FreeRunner_from_NOR_Flash|boot from NOR first]], in order to flash the boot-loader in NAND. After flashing succesfully, make sure you reboot from NAND's newly flashed boot loader, to benefit from the updates.
+
 
+
=== Optional: Verifying boot-loader version ===
+
  
 
<!-- The following should probably be moved to [[Bootloader_versions]], IMHO -->
 
<!-- The following should probably be moved to [[Bootloader_versions]], IMHO -->
Line 181: Line 53:
 
   root@om-gta02:~# grep  Bootloader /dev/mtdblock0
 
   root@om-gta02:~# grep  Bootloader /dev/mtdblock0
 
   Neo1973 Bootloader U-Boot 1.3.2-moko12
 
   Neo1973 Bootloader U-Boot 1.3.2-moko12
 
 
<!-- ENDS ... subject: Re: Upgrading u-boot needed ? -->
 
<!-- ENDS ... subject: Re: Upgrading u-boot needed ? -->
 
== Reboot the FreeRunner from NAND ==
 
 
You should now be able to boot into the new images.
 
 
Pay attention '''to booting from the NAND flash this time''', in particular if you upgraded the boot-loader (in short: 1. press and hold ''power button'' down, and then 2. press ''aux button'')
 
 
The boot menu should be labelled '''*** BOOT MENU (NAND) ***''' this time (see [[Booting#Log_into_U-Boot_in_the_NAND_Flash|booting from NAND]] for more detailed instructions).
 
 
== A command line script to simplify dfu-util ==
 
 
DFUScript developed to assist users who have multiple devices in using dfu-util via the command line. Information on where to download and use DFUScript can be found on [[DFUScript]]
 
 
== Alternative: using nandwrite ==
 
 
This approach involves writing the '''rootfs''' into nand directly on the phone from a system already running on it, not necessarily via usb from a computer.
 
 
If you have a system running from a different partition that you intend to flash (for example sd card), you can use nandwrite to do the work, which is much faster (it takes about 30s to write a 59MB jffs2 image).
 
 
Make sure you have nandwrite installed (on gentoo, it's in sys-fs/mtd-utils package)
 
 
Also make sure that the host system has received correct partition list, for example for my stock Neo Freerunner partition list:
 
 
<pre>
 
#cat /proc/mtd
 
dev:    size  erasesize  name
 
mtd0: 00200000 00010000 "physmap-flash.0"
 
mtd1: 00040000 00020000 "u-boot"
 
mtd2: 00040000 00020000 "u-boot_env"
 
mtd3: 00800000 00020000 "kernel"
 
mtd4: 000a0000 00020000 "splash"
 
mtd5: 00040000 00020000 "factory"
 
mtd6: 0f6a0000 00020000 "rootfs"
 
</pre>
 
 
In this case, we're looking for 'rootfs' which according to above is mtd6. If you have it somewhere else, substitute mtd6 with whatever you have in the remainder of this section.
 
 
You can test your nand for bad blocks by issuing '''nandtest /dev/mtd6''' '''(this is a data destructive test !)'''
 
 
First, put your .jffs2 file somewhere the phone system can read it
 
 
Second, write the desired image into the nand this way:
 
<pre>
 
flash_eraseall /dev/mtd6
 
nandwrite -p /dev/mtd6 /path/to/image.jffs2
 
</pre>
 
 
* The -m flag can be used to tell nandwrite to mark blocks it detects bad as bad, so if nandwrite is bugged, your entire partition will be marked as bad. See http://wiki.openmoko.org/wiki/NAND_bad_blocks#Clearing_BadBlocks if this happened to you.
 
 
You're all done!
 
  
 
== Troubleshooting ==
 
== Troubleshooting ==
Line 241: Line 62:
 
* Try redownloading and reflashing the kernel, checking file integrity with the MD5 hash sums.
 
* Try redownloading and reflashing the kernel, checking file integrity with the MD5 hash sums.
  
==See also==
+
== Quick Step-By-Step Summary ==
*[http://www.denx.de/wiki/U-Boot/WebHome U-Boot home page]
+
 
 +
# Press AUX button first, hold it and press Power button. Wait until NOR flash U-Boot menu appears. You recognize it from the orange Openmoko logo. On the top it should usually say "U-Boot 1.3.2-moko12 (May 9 2008 - 10:28:48)".
 +
# Attach USB cable
 +
# Type the following commands, before the Neo automatically powers down
 +
 
 +
  # Flash u-boot
 +
  dfu-util -a u-boot -R -D /path/to/u-boot_image
 +
  # Flash the kernel
 +
  dfu-util -a kernel -R -D /path/to/uImage.bin
 +
  # Flash the rootfs
 +
  dfu-util -a rootfs -R -D /path/to/rootfs.jffs2
 +
 
 +
If needed, specify extra device specifying parameter -d [[USB Product IDs|0x1d50:0x5119]] to the dfu-util.
  
 
[[Category:Flashing Openmoko| ]]
 
[[Category:Flashing Openmoko| ]]

Latest revision as of 07:51, 10 February 2012

Most of the software on the Neo FreeRunner can be updated or changed. The root filesystem, the kernel, and the Bootloader can be modified with the program dfu-util from a computer. This page does not describe flashing the NOR Flash which requires a debug board. See Flashing NOR for this procedure.

The NAND Flash is divided into 3 partitions for the bootloader, kernel, and root filesystem. Each component can be flashed separately.

The bootloader is a small program that runs first and starts everything else when the FreeRunner is powered on. The bootloader is independent of the distribution you use. The kernel and the root filesystem are provided by the distribution.

Before you start: Erasing the root filesystem or flashing the bootloader are radical measures. Take the time to ponder the necessity. Sometimes problems can be fixed by only updating the kernel.

Contents

[edit] Image files to flash into FreeRunner memory

There are separate image files for all 3 software components. In most cases you will need to install a Kernel (uImage) and a Root Filesystem (rootfs). In rare cases, when there is a bug you need fixed, you will also install a new bootloader.

Please read Distributions for choosing the distribution which fits your needs, and then see Download for downloading.

[edit] Do a backup

If you have a working image that you're happy with but want to try something different, you should probably do a Backup.

[edit] Using dfu-util

Dfu-util is a command-line tool to flash the FreeRunner. It is available for Linux, MacOS X, and Windows. DFU-util allows you to connect to the FreeRunner through the USB cable and control its bootloader. That connection uses a special protocol which addresses the bootloader's interface, and differs from USB networking. For more details, see the separate dfu-util page.

See Manuals/Dfu-util

[edit] NeoTool (GUI)

Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the NeoTool page.

[edit] DFUScript - A command line script to simplify dfu-util

DFUScript was developed to assist users who have multiple devices in using dfu-util via the command line. Information on where to download and use DFUScript can be found on DFUScript.

[edit] Alternative: using nandwrite

This approach involves writing the rootfs into nand directly on the phone from a system already running on it, not necessarily via usb from a computer.

If you have a system running from a different partition that you intend to flash (for example sd card), you can use nandwrite to do the work, which is much faster (it takes about 30s to write a 59MB jffs2 image).

See Nandwrite for more information.

[edit] Optional: Verifying boot-loader version

(Optional) After an upgrade, you may wish to check that the u-boot version matches the one you have just flashed. You can use 'grep Bootloader /dev/mtdblock1' from a shell on the FreeRunner (and possibly the 1973 as well) to get the NAND u-boot version, like this:

  root@om-gta02:~# grep Bootloader /dev/mtdblock1
  Neo1973 Bootloader U-Boot 1.3.2+gitr18+64eb10cab8055084ae25ea4e73b66dd03cc1a0cb

You can grep for the same string in /dev/mtdblock0 to retrieve the NOR u-boot version:

  root@om-gta02:~# grep  Bootloader /dev/mtdblock0
  Neo1973 Bootloader U-Boot 1.3.2-moko12

[edit] Troubleshooting

Okay, so you just reflashed. The splash screen pops up, but uBoot fail to load the kernel, and return to boot menu. WTF?

  • It is likely that the wrong bits went to the wrong place. Try reflashing just the kernel, double checking that you select the uImage.bin kernel file, not the u-boot.bin bootloader file.
  • Try redownloading and reflashing the kernel, checking file integrity with the MD5 hash sums.

[edit] Quick Step-By-Step Summary

  1. Press AUX button first, hold it and press Power button. Wait until NOR flash U-Boot menu appears. You recognize it from the orange Openmoko logo. On the top it should usually say "U-Boot 1.3.2-moko12 (May 9 2008 - 10:28:48)".
  2. Attach USB cable
  3. Type the following commands, before the Neo automatically powers down
  # Flash u-boot
  dfu-util -a u-boot -R -D /path/to/u-boot_image
  # Flash the kernel
  dfu-util -a kernel -R -D /path/to/uImage.bin
  # Flash the rootfs
  dfu-util -a rootfs -R -D /path/to/rootfs.jffs2

If needed, specify extra device specifying parameter -d 0x1d50:0x5119 to the dfu-util.

Personal tools

Openmoko regularly releases updated versions of the Openmoko root filesystem, the kernel, and the Bootloader (either Uboot or Qi) as binary images. These may be programmed into the Flash memory (NAND) of Neo FreeRunner. For that, you can use the USB cable and another computer which will run an Openmoko-provided tool to flash the Neo FreeRunner "through" USB.

3 software components and 2 kinds of storage

Inside the FreeRunner 3 software components are working:

  • bootloader: a small program that runs first and starts everything else when the FreeRunner is powered on or reset (depending on how you reset it, the version from NOR or NAND is booted).
  • kernel: the central component in the Linux operating system.
  • root filesystem: contains all the files that make up the commands and applications that you can run.

All software components in the FreeRunner are bundled together into binary images.

The FreeRunner has two kinds of internal program storage: NOR flash and NAND flash. On a desktop computer when you want to replace the operating system (OS), you would boot it from a CD-ROM drive, then copy OS files from the CD to the internal hard drive. The FreeRunner does not have a CD-ROM drive and files must typically be re-written/flashed directly into internal storage (NAND flash). Alternatively, it is possible to boot from a microSD where all the files have been loaded onto.

NOR flash is small and stores only a special boot program used when you need to re-write the contents of the NAND flash. Usually it is not necessary to re-write the NOR flash. Instructions to do so is here: Flashing NOR.

NAND flash acts more like a hard drive. It is divided into 3 partitions for the bootloader, kernel, and root filesystem. Being on different partitions, each component can be flashed separately. For example if you are trying to install a modified kernel, you only have to follow the steps to flash the kernel image.

Before you start: Erasing the root filesystem or flashing the bootloader are radical measures. Take the time to ponder the necessity. Sometimes problems can be fixed by only updating the kernel.

Alternative : running from microSD card

You may install this distribution on the microSD card, in order to boot from microSD card. That allows you to keep another distribution installed in NAND (for instance to test 2008.08 while still having 2007.2 for default boot).

Software you need

#1 Tools for flashing: DFU-util and NeoTool

Note that there are some issues using dfu-util with sudo.

Don't use sudo with dfu-util. Make sure you are root before using dfu-util!

Command-line. DFU-util, the tool to flash the FreeRunner has to be installed on you laptop or desktop machine. It is available for Linux, MacOS X, and Windows (see links below). DFU-util allows you to connect to the FreeRunner through the USB cable and control its bootloader. That connection uses a special protocol which addresses the bootloader's interface, and differs from USB networking. For more details, see the separate dfu-util page.

GUI. Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the NeoTool page.

Linux: http://downloads.openmoko.org/distro/releases/Om2008.9/dfu-util

Make sure it is executable by setting the permissions with this command: chmod a+x dfu-util

Linux 64-bit: You need 64-bit version of dfu-util, which usually can be found in your distribution repository. If your distribution does not provide 64-bit dfu-util, or it consistently fails with a "-62" error, you have two ways to go:

  1. Seek for 32-bit machine and do flashing form it.
  2. Use 32-bit chroot (on amd64 debian). Worked for me --Bubak 16:54, 4 September 2008 (UTC).
  3. Just try the 32-bit dfu-util. Worked fine on my x86_64 Fedora 10 --pcfe 2009-01-16.
    • I can confirm this (Gentoo multilib x86_64) --Unlotto 14:15, 4 February 2009 (UTC)
    • I can confirm this (OpenSuSE 11.0 x86_64) --muthusuba 29 July 2009

MacOS X: MacOS_X#Graphical_Flashing_with_Openmoko_Flasher

Windows: http://projects.openmoko.org/frs/?group_id=166&release_id=162

See additional driver installation instructions for Windows at Dfu-util-windows

Virtual machines While there has been some limited success reported using dfu-util from within a Virtual Machine (such as VMware), in general it is not possible to use dfu-util in this fashion. You must use dfu-util on an operating system that has direct access to the physical USB device hardware.

#2 Image files to flash into FreeRunner memory

There are separate image files for all 3 software components and depending on what you want to install, you pick the respective image file. In most cases you will need to install a Kernel (uImage) and a Root Filesystem (rootfs). In rare cases, when there is a bug you need fixed, you will also install a new bootloader.

Please read Distributions for choosing the distribution which fits your needs, and then see Download for downloading.

Boot the FreeRunner from NOR Flash

Booting from NOR Flash
  1. Read the other sections of this page first, because you will have 30 seconds to enter the flashing commands, come back here when ready.
  2. Make sure your FreeRunner is off.
  3. Do not connect the USB cable from the PC to your Neo FreeRunner yet (disconnect it).
  4. Boot your Neo FreeRunner into the NOR uBoot menu for flashing.
    1. Press and hold AUX button
    2. Press the Power button until the boot menu comes up
    3. This menu is labelled *** BOOT MENU (NOR) ***
    4. See also Booting the Neo FreeRunner
  5. Stay in NOR uBoot menu, do not select or enter any item in menu. Now you will be able to flash, make backups of your FreeRunner or query the FreeRunner with dfu-util.
  6. The FreeRunner only stays at the NOR boot prompt for about 30 seconds and then shuts off unless you do something.
  7. Connect your Neo to the GNU/Linux or Windows host via a USB cable.
  8. Now you can enter the dfu-util commands on your PC as described below.
  9. 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 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.

Do a backup

If you have a working image that you're happy with but want to try something different, you should probably do a Backup.

Using dfu-util

dfu-util can be used to read flash memory, write memory, and get information from the device.

This is the general command format to write an image file to a (predefined) "partition name" (referred to as altsetting in dfu-util help/manual) :

# dfu-util -a <altsetting> -R -D <file_name>

where:
-a altsetting : Specify the altsetting of the DFU interface by name or by number
-R  : Issue USB Reset signalling once we're finished
-D file_name : Write firmware from file_name into device

On Linux, you run dfu-util from a command shell prompt. If you have not put it somewhere on your command path you probably need to prefix it with a "./" like this ./dfu-util. On some systems you need to be root before this will work and on Ubuntu you must preface the command with "sudo" or you will get the following error: "Cannot claim interface: could not claim interface 2: Operation not permitted"

On Windows, you need to open a command window and run from a command line. Use Start-Run Program and type "cmd" to open a Window.

More detailed manual for dfu-util is available here : Dfu-util

GUI frontend for dfu-util (and more): NeoTool

Flashing the Kernel

Note: The phone needs to be in the U-boot bootup menu for this to work.
      Get there by holding down the aux button while powering up the device.

The command format is:

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

When flashing succeeds the following will be shown:

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

Flashing may fail with an error -110. This indicates that the kernel is too big for the default kernel partition. uboot can be used to change the size of the default partitions on the device. It may also mean that you are trying to put the wrong thing in the kernel space.

Flashing the Root Filesystem

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.

The command format is:

 # dfu-util -a rootfs -R -D rootfs_filename.jffs2

| U-Boot where rootfs_filename.jffs2 is the name of the file containing the root file system.

The flashing process can take up to 15 minutes for a ~70MB image. It is also wise to make sure that your Neo has enough battery charge prior to flashing.

When flashing succeeds the following will be shown:

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

Flashing the boot loader to the NAND

NOTE: In most cases you don't need to flash your bootloader. Flash it only if you want to update for a specific feature or due to a specific problem.


The boot loader (U-boot) file should have a .bin extension. As with the root filesystem, if the file you downloaded is zipped or compressed (has a .gz or .zip extension) you have to uncompress it first.

The command format is:

# dfu-util -a u-boot -R -D uboot.bin

where uboot.bin is the name of the boot loader binary image file.

Reminder: You should have boot from NOR first, in order to flash the boot-loader in NAND. After flashing succesfully, make sure you reboot from NAND's newly flashed boot loader, to benefit from the updates.

Optional: Verifying boot-loader version

(Optional) After an upgrade, you may wish to check that the u-boot version matches the one you have just flashed. You can use 'grep Bootloader /dev/mtdblock1' from a shell on the FreeRunner (and possibly the 1973 as well) to get the NAND u-boot version, like this:

  root@om-gta02:~# grep Bootloader /dev/mtdblock1
  Neo1973 Bootloader U-Boot 1.3.2+gitr18+64eb10cab8055084ae25ea4e73b66dd03cc1a0cb

You can grep for the same string in /dev/mtdblock0 to retrieve the NOR u-boot version:

  root@om-gta02:~# grep  Bootloader /dev/mtdblock0
  Neo1973 Bootloader U-Boot 1.3.2-moko12


Reboot the FreeRunner from NAND

You should now be able to boot into the new images.

Pay attention to booting from the NAND flash this time, in particular if you upgraded the boot-loader (in short: 1. press and hold power button down, and then 2. press aux button)

The boot menu should be labelled *** BOOT MENU (NAND) *** this time (see booting from NAND for more detailed instructions).

A command line script to simplify dfu-util

DFUScript developed to assist users who have multiple devices in using dfu-util via the command line. Information on where to download and use DFUScript can be found on DFUScript

Alternative: using nandwrite

This approach involves writing the rootfs into nand directly on the phone from a system already running on it, not necessarily via usb from a computer.

If you have a system running from a different partition that you intend to flash (for example sd card), you can use nandwrite to do the work, which is much faster (it takes about 30s to write a 59MB jffs2 image).

Make sure you have nandwrite installed (on gentoo, it's in sys-fs/mtd-utils package)

Also make sure that the host system has received correct partition list, for example for my stock Neo Freerunner partition list:

#cat /proc/mtd
dev:    size   erasesize  name
mtd0: 00200000 00010000 "physmap-flash.0"
mtd1: 00040000 00020000 "u-boot"
mtd2: 00040000 00020000 "u-boot_env"
mtd3: 00800000 00020000 "kernel"
mtd4: 000a0000 00020000 "splash"
mtd5: 00040000 00020000 "factory"
mtd6: 0f6a0000 00020000 "rootfs"

In this case, we're looking for 'rootfs' which according to above is mtd6. If you have it somewhere else, substitute mtd6 with whatever you have in the remainder of this section.

You can test your nand for bad blocks by issuing nandtest /dev/mtd6 (this is a data destructive test !)

First, put your .jffs2 file somewhere the phone system can read it

Second, write the desired image into the nand this way:

flash_eraseall /dev/mtd6
nandwrite -p /dev/mtd6 /path/to/image.jffs2

You're all done!

Troubleshooting

Okay, so you just reflashed. The splash screen pops up, but uBoot fail to load the kernel, and return to boot menu. WTF?

  • It is likely that the wrong bits went to the wrong place. Try reflashing just the kernel, double checking that you select the uImage.bin kernel file, not the u-boot.bin bootloader file.
  • Try redownloading and reflashing the kernel, checking file integrity with the MD5 hash sums.

See also