Flashing the Neo FreeRunner

From Openmoko

(Difference between revisions)
Jump to: navigation, search
m (slight improvement of intro)
(Quick Step-By-Step Summary: spelling)
 
(123 intermediate revisions by 60 users not shown)
Line 1: Line 1:
Openmoko regularly releases updated versions of the Openmoko root filesystem, the [[kernel]], and the [[Bootloader| U-Boot]] 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.
+
{{Languages|Flashing_the_Neo_FreeRunner}}
 +
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.  
  
{{note|The Openmoko software team builds images daily. If you want to use the latest images, you can download the image from the daily build, but we recommend you '''use the most stable image from http://downloads.openmoko.org/releases/Freerunner/.''' Images here have been tested by the test team.}}
+
The [[NAND Flash]] is divided into 3 partitions for the bootloader, kernel, and root filesystem. Each component can be flashed separately.  
  
== Overview ==
+
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.
All the components of the software in the FreeRunner are bundled together into binary images.
+
The '''kernel''' and the '''root filesystem''' are provided by the distribution.  
  
The '''bootloader''' is a small program that runs first when the FreeRunner is powered on or reset (depending on [[Booting the Neo FreeRunner|how you reset it]], the version from NOR or NAND is booted).
+
'''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.'''
The '''kernel''' is the central component in the Linux operating system.
+
The '''root filesystem''' contains all the files that make up the commands and applications that you can run.
+
  
On a desktop computer when you want to replace the operating system, you would boot it from a CD-ROM drive, then copy files from the CD to the internal hard drive.
+
== Image files to flash into FreeRunner memory ==
  
The FreeRunner does not have a CD-ROM drive but it does have two kinds of internal program storage: NOR flash and NAND flash. The NOR flash is small and stores only a special boot program used when you need to re-write the contents of the NAND flash. NAND flash acts more like a hard drive.
+
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.
  
The NAND Flash is divided into 3 partitions so that you can flash each component separately.
+
Please read [[Distributions]] for choosing the distribution which fits your needs, and then see [[Download]] for downloading.
For example if you are trying to install a better kernel, you only have to follow the steps to flash the kernel image.
+
 
+
The FreeRunner can also boot from an image in its micro SD card but that option is not covered here. See [[Booting from SD]] for more information.
+
+
'''Before you start: Erasing the root filesystem or flashing the uboot are radical measures. Take the time to ponder the necessity. Sometimes problems can be fixed by updating only the kernel.'''
+
 
+
The steps to reflash NAND are
+
 
+
# Collect everything you need together on your desktop computer. This includes the dfu-util program and the images you will load into the FreeRunner and a USB cable.
+
# Boot the FreeRunner from NOR Flash.
+
# Connect the FreeRunner to the desktop computer via the USB cable.
+
# Use dfu-util to backup the current contents of the FreeRunner.
+
# Use dfu-util to copy the images from the desktop into the FreeRunner.
+
# Boot the FreeRunner from NAND Flash to use the new image(s).
+
 
+
== Collect the things you need ==
+
 
+
=== Download the DFU-util program ===
+
 
+
There are versions of dfu-util for both Linux and Windows. It works the same way on both platforms.
+
There is a separate page to describe it in more detail: [[dfu-util]]
+
 
+
'''Linux'''
+
You can download the flashing tool for a GNU/Linux host from:
+
http://downloads.openmoko.org/releases/Freerunner/dfu-util
+
 
+
Make sure it is executable by setting the permissions with this command: chmod a+x dfu-util
+
 
+
'''Windows'''
+
You can download the flashing tool for a Windows host from:
+
[http://projects.openmoko.org/frs/?group_id=166&release_id=162 http://projects.openmoko.org/frs/?group_id=166&release_id=162]
+
 
+
See additional installation instructions for Windows at [[Dfu-util-windows]]
+
 
+
=== Download the image files that you will need ===
+
 
+
Exactly what files you need depends on what you are trying to install. Here are some pages you can refer to for more information.
+
 
+
''Edit request -- Some comments on why you'd want to replace each component could go here. For example you probably don't want to replace the bootloader unless there are bug fixes you really need.''
+
 
+
[[Bootloader]] : TBD
+
 
+
[[Kernel]] : You can download kernels from http://downloads.openmoko.org/releases/Freerunner/
+
 
+
You can download the standard Openmoko root filesystem from
+
http://downloads.openmoko.org/releases/Freerunner/
+
or you can see more options at [[Distributions]] and [[Latest_Images]]
+
 
+
If you download a '''Qtopia''' image, you will get a tarball file containing both the Qtopia root filesystem and a matching kernel. You can unpack them with the tar command, for example: tar xzvf ''qtopia.tgz''
+
 
+
If you download an '''FSO''' image, the file system will be in a jffs2 'summary' file.
+
A file with the extension ".jffs2.summary" can be flashed to the FreeRunner just like an ordinary jffs2 file.
+
 
+
== Boot the FreeRunner from NOR Flash ==
+
 
+
[[Image:menu15.jpg|thumb|Booting from NOR Flash]]
+
 
+
The Neo FreeRunner needs to be at the NOR uBoot menu for flashing. For more information on booting, see [[Booting the Neo FreeRunner| booting the Neo Freerunner]] (in short: 1. press and hold ''aux'' down, and then 2. press ''power button'').
+
 
+
Log into the NOR uBoot menu (labelled '''*** BOOT MENU (NOR) ***''') and just stay there, 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.
+
 
+
Once the FreeRunner is at the NOR boot menu, you can connect your Neo to the GNU/Linux or Windows host via USB cable.
+
 
+
<br clear=all>
+
  
 
== Do a backup ==
 
== 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 [[Pre-Flash Backup]], although it looks like the method on that page may not entirely work.
+
If you have a working image that you're happy with but want to try something different, you should probably do a [[Backup]].
 
+
''Is this still true? 7/31/08??''
+
  
 
== 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) :
+
 
+
dfu-util -a ''altsetting'' -R -D ''file_name''
+
 
+
where:<br>
+
-a ''altsetting'' : Specify the altsetting of the DFU interface by name or by number<br>
+
-R  : 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'''.
+
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.
+
 
+
== Flashing the Kernel ==
+
 
+
The command format is
+
  
dfu-util -a kernel -R -D ''/path/to/uImage''
+
See [[Manuals/Dfu-util]]
  
When flashing succeeds the following will be shown:
+
=== NeoTool (GUI) ===
  
status(0) = No error condition is present
+
Instead of the command-line-based DFU-util, you can use NeoTool, a graphical tool for flashing the FreeRunner: see the [[NeoTool]] page.
Done!
+
  
== Flashing the Root Filesystem ==
+
=== DFUScript - A command line script to simplify dfu-util ===
  
The root filesystem has to be an image in jffs2 format. If the file you downloaded is zipped or compressed (has a .gz or .zip extension) you have to uncompress it first.
+
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]].
  
The command format is
+
== Alternative: using nandwrite ==
  
dfu-util -a rootfs -R -D ''rootfs_filename.jffs2''
+
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.
  
where ''rootfs_filename.jffs2'' is the name of the file containing the root filesystem.
+
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).
  
When flashing succeeds the following will be shown:
+
See [[Nandwrite]] for more information.
  
status(0) = No error condition is present
+
== Optional: Verifying boot-loader version ==
Done!
+
  
== Flashing the boot loader to the NAND==
+
<!-- The following should probably be moved to [[Bootloader_versions]], IMHO -->
  
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.
+
<!-- Taken from posts by Mikael Berthe <mikael.berthe@lilotux.net> and Torfinn Ingolfsen <tingox@gmail.com> to Support list, subject: Re: Upgrading u-boot needed ? -->
 +
(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
  
The command format is
+
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
 +
<!-- ENDS ... subject: Re: Upgrading u-boot needed ? -->
  
dfu-util -a u-boot -R -D ''uboot.bin''
+
== Troubleshooting ==
  
where ''uboot.bin'' is the name of the boot loader binary image file.
+
Okay, so you just reflashed. The splash screen pops up, but uBoot fail to load the kernel, and return to boot menu. WTF?
  
''Reminder'': You should have [[Flashing_the_Neo_FreeRunner#Boot_the_FreeRunner_from_NOR_Flash|rebooted 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.
+
* 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.
  
== Reboot the FreeRunner from NAND ==
+
== Quick Step-By-Step Summary ==
  
You should now be able to boot into the new images.
+
# 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
  
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'')
+
  # 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
  
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).
+
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 U-Boot 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.

NOTE: The Openmoko software team builds images daily. If you want to use the latest images, you can download the image from the daily build, but we recommend you use the most stable image from http://downloads.openmoko.org/releases/Freerunner/. Images here have been tested by the test team.


Overview

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

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

On a desktop computer when you want to replace the operating system, you would boot it from a CD-ROM drive, then copy files from the CD to the internal hard drive.

The FreeRunner does not have a CD-ROM drive but it does have two kinds of internal program storage: NOR flash and NAND flash. The NOR flash is small and stores only a special boot program used when you need to re-write the contents of the NAND flash. NAND flash acts more like a hard drive.

The NAND Flash is divided into 3 partitions so that you can flash each component separately. For example if you are trying to install a better kernel, you only have to follow the steps to flash the kernel image.

The FreeRunner can also boot from an image in its micro SD card but that option is not covered here. See Booting from SD for more information.

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

The steps to reflash NAND are

  1. Collect everything you need together on your desktop computer. This includes the dfu-util program and the images you will load into the FreeRunner and a USB cable.
  2. Boot the FreeRunner from NOR Flash.
  3. Connect the FreeRunner to the desktop computer via the USB cable.
  4. Use dfu-util to backup the current contents of the FreeRunner.
  5. Use dfu-util to copy the images from the desktop into the FreeRunner.
  6. Boot the FreeRunner from NAND Flash to use the new image(s).

Collect the things you need

Download the DFU-util program

There are versions of dfu-util for both Linux and Windows. It works the same way on both platforms. There is a separate page to describe it in more detail: dfu-util

Linux You can download the flashing tool for a GNU/Linux host from: http://downloads.openmoko.org/releases/Freerunner/dfu-util

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

Windows You can download the flashing tool for a Windows host from: http://projects.openmoko.org/frs/?group_id=166&release_id=162

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

Download the image files that you will need

Exactly what files you need depends on what you are trying to install. Here are some pages you can refer to for more information.

Edit request -- Some comments on why you'd want to replace each component could go here. For example you probably don't want to replace the bootloader unless there are bug fixes you really need.

Bootloader : TBD

Kernel : You can download kernels from http://downloads.openmoko.org/releases/Freerunner/

You can download the standard Openmoko root filesystem from http://downloads.openmoko.org/releases/Freerunner/ or you can see more options at Distributions and Latest_Images

If you download a Qtopia image, you will get a tarball file containing both the Qtopia root filesystem and a matching kernel. You can unpack them with the tar command, for example: tar xzvf qtopia.tgz

If you download an FSO image, the file system will be in a jffs2 'summary' file. A file with the extension ".jffs2.summary" can be flashed to the FreeRunner just like an ordinary jffs2 file.

Boot the FreeRunner from NOR Flash

Booting from NOR Flash

The Neo FreeRunner needs to be at the NOR uBoot menu for flashing. For more information on booting, see booting the Neo Freerunner (in short: 1. press and hold aux down, and then 2. press power button).

Log into the NOR uBoot menu (labelled *** BOOT MENU (NOR) ***) and just stay there, 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.

Once the FreeRunner is at the NOR boot menu, you can connect your Neo to the GNU/Linux or Windows host via USB cable.


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 Pre-Flash Backup, although it looks like the method on that page may not entirely work.

Is this still true? 7/31/08??

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.

Flashing the Kernel

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 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 or .zip extension) you have to uncompress it first.

The command format is

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

where rootfs_filename.jffs2 is the name of the file containing the root filesystem.

When flashing succeeds the following will be shown:

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

Flashing the boot loader to the NAND

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 rebooted 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.

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).