Flashing the Neo FreeRunner

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Boot the FreeRunner from NOR Flash: Flashing procedure is now a numbered list instead a large block of text.)
(Do a backup)
Line 79: Line 79:
 
== 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 [[Pre-Flash Backup]].
 
+
''Is this still true? 7/31/08??''
+
  
 
== Using dfu-util ==
 
== Using dfu-util ==

Revision as of 23:55, 8 August 2008

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.

Contents

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 modified 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

You will download that program on your desktop computer. It will allow 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. There is a separate page to describe it in more detail: dfu-util.

MacOS X: MacOS_X#Graphical_Flashing_with_Openmoko_Flasher

Linux: http://buildhost.openmoko.org/releases/Freerunner/dfu-util

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

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

See additional driver 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. In most cases you will need to install a Kernel 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. Do not connect the USB cable from the PC to your Neo FreeRunner yet (disconnect it).
  3. 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
  4. Stay in NOR uBoot menu, do not to 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.
  5. The FreeRunner only stays at the NOR boot prompt for about 30 seconds and then shuts off unless you do something.
  6. Connect your Neo to the GNU/Linux or Windows host via a USB cable.
  7. Now you can enter the dfu-util commands on your PC as described below.
  8. 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

Sometimes I get error messages from the dfu-util command; I just try again. Often they work on the second try. Sometimes I have to boot into NOR again before things work. Once a connection has been made everything seems to work fine.

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.

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.

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

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.

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 modified 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

You will download that program on your desktop computer. It will allow 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. There is a separate page to describe it in more detail: dfu-util.

MacOS X: MacOS_X#Graphical_Flashing_with_Openmoko_Flasher

Linux: http://buildhost.openmoko.org/releases/Freerunner/dfu-util

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

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

See additional driver 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. In most cases you will need to install a Kernel 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. Do not connect the USB cable from the PC to your Neo FreeRunner yet (disconnect it).
  3. 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
  4. Stay in NOR uBoot menu, do not to 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.
  5. The FreeRunner only stays at the NOR boot prompt for about 30 seconds and then shuts off unless you do something.
  6. Connect your Neo to the GNU/Linux or Windows host via a USB cable.
  7. Now you can enter the dfu-util commands on your PC as described below.
  8. 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

Sometimes I get error messages from the dfu-util command; I just try again. Often they work on the second try. Sometimes I have to boot into NOR again before things work. Once a connection has been made everything seems to work fine.

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.

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