Flashing the Neo FreeRunner

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(moving section)
(Quick Step-By-Step Summary: spelling)
 
(13 intermediate revisions by 4 users not shown)
Line 21: Line 21:
 
== Using dfu-util ==
 
== Using dfu-util ==
  
=== Tools for flashing: dfu-util and NeoTool ===
+
[[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.
  
''Command-line''. [[dfu-util]], the tool to flash the FreeRunner has to be installed on your computer. 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.
+
See [[Manuals/Dfu-util]]
  
''GUI''. Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the [[NeoTool]] page.
+
=== NeoTool (GUI) ===
  
See [[Manuals/Dfu-util]]
+
Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the [[NeoTool]] page.
 +
 
 +
=== 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]].
 +
 
 +
== 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.
  
 
== Optional: Verifying boot-loader version ==
 
== Optional: Verifying boot-loader version ==
Line 41: 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 ? -->
 
== 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.
 
 
'''Beware of flashing the ''u-boot'' partition, probably you'll have to recreate mtdparts configuration for u-boot from [[U-boot#Using_usbtty_from_Linux|u-boot console]]. Probably this is due to some kind of bug in nandwrite.'''
 
 
<pre>
 
dynpart
 
dynenv set u-boot_env
 
</pre>
 
 
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 [[NAND_bad_blocks#Clearing_BadBlocks]] if this happened to you.
 
 
You're all done!
 
  
 
== Troubleshooting ==
 
== Troubleshooting ==
Line 100: 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

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.

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.

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

Tools for flashing: dfu-util and NeoTool

Command-line. dfu-util, the tool to flash the FreeRunner has to be installed on your computer. 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.

See Manuals/Dfu-util

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


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.

Beware of flashing the u-boot partition, probably you'll have to recreate mtdparts configuration for u-boot from u-boot console. Probably this is due to some kind of bug in nandwrite.

dynpart
dynenv set u-boot_env

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
  • 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 NAND_bad_blocks#Clearing_BadBlocks if this happened to you.

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