Replacing the filesystem image

As of 2010, all Gumstix customers should be using Gumstix OpenEmbedded, not Buildroot.

The Gumstix Developer's website is www.gumstix.org

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

For legacy customers still requiring buildroot:

Flashing the Gumstix is the process of replacing its filesystem image, held in flash memory, with a new copy. This is done to update software, add features, or fix bugs.

Most often, users will flash their Gumstix with a filesystem image built using the Buildroot. However, the original factory flash images are also available, and can be used to restore the Gumstix to its original configuration.

The uboot bootloader can also be flashed with a new copy. This is a less common and more dangerous operation. If filesystem flashing fails, it can simply be retried -- but if the bootloader is flashed incorrectly or corrupted, the Gumstix must be reflashed from the ground up by using a JTAG cable and special software.

This page deals primarily with flashing the filesystem image containing the Linux operating system and all user software.

Common Problems
If you get the following error message:

Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(31,2)

The new root_fs needs to mount / from device 1f01 instead of 1f02 which is where the old '/' was — linux changed the MTD device enumeration ordering between 2.6.11 and 2.6.15 and so our root device in flash moved. In U-Boot, do:

GUM> set bootargs console=ttyS0,115200n8 root=1f01 rootfstype=jffs2 reboot=cold,hard GUM> saveenv GUM> bootd

If you see lots of Unknown node type messages:

Scanning JFFS2 FS:. Unknown node type: 2006 len 4288 offset 0x5ef40 Unknown node type: 2006 len 6480 offset 0x7e6b0 / Unknown node type: 2006 len 4988 offset 0x9ec84 . Unknown node type: 2006 len 7368 offset 0xbe338 - Unknown node type: 2006 len 10128 offset 0xdd870
 * 1) JFFS2 loading 'boot/uImage' to 0xa2000000

that's currently normal. The 2.6.15 kernel has changed the JFFS2 filesystem in a way that cause U-Boot to report these unknown node-type messages. You can ignore the messages.

Flashing over SSH / ethernet
(This section was posted by Craig Hughes to the mailing list)

There is a way to flash a new root_fs (and a new u-boot which you'll need because of the bootargs change) from within linux afer copying the files over via ethernet or usbnet. However, if something goes wrong, then without a serial port you'll be hard pressed to figure out what went wrong. That said, it's fairly easy (ie hard to get wrong). If you're fairly confident, you can try the following:

copy the new rootfs.arm_nofpu.jffs2 and u-boot.bin from the buildroot to /tmp on the gumstix, via scp. If you are using a recent Verdex buildroot, you will also need to copy the Linux kernel (uImage), as this is no longer included in the rootfs.

then, on the gumstix, you'll need to identify where / is mounted from. For most recent builds, this will most likely be MTD partition 1 -- for people who running a pre-2.6.15 root_fs, this may be MTD partition 2:

/dev/mtdblock1 on / type jffs2 (rw,noatime) That's MTD partition 1. This means u-boot is in MTD partition 0. If this had said /dev/mtdblock2 then root_fs is in 2 and u-boot is in 1.
 * 1) mount | grep mtd

If 'mount' does not generate useful output (/ appears as '/dev/root' in many recent builds, so the above command will not reveal the necessary information), an alternative command is:

/dev/mtdblock1          15.8M      4.5M     11.3M  28% /
 * 1) df | grep mtd

In this case, the root_fs is on MTD partition 1 (/dev/mtdblock1), and u-boot is therefore in partition 0.

Now, follow the recipe:


 * 1) modprobe sa1100_wdt margin=1
 * 2) mount -o remount,ro /

If your new boot image has a different kernel version to the boot image you're replacing, type the following two commands to replace the u-boot bootloader with a matching version. When in doubt, do this step, otherwise the 'bootargs' variable to u-boot will not match the kernel version you're using, and you'll need a serial console to fix this before your board will boot again. If you are sure that your new boot image contains exactly the same kernel version, you can omit the next two commands and skip to the next step.

[Note that you would use /dev/mtd1 in place of /dev/mtd0 here if you had root_fs in mtd2 above]


 * 1) flash_unlock /dev/mtd0
 * 2) flashcp -v /tmp/u-boot.bin /dev/mtd0

If, and only if that above line succeeded, then proceed. If the above line failed, you're probably in trouble and may have just prepared your gumstix for its life as a doorstop. Well, actually, it can be reflashed using JTAG, but it'll still be a PITA. If you need help trying to recover from a failure from the above 2 lines, then please do not power down your Gumstix before asking for help from this forum. If the above steps fail, and you power down before fixing it, then you will need JTAG to recover.

Ok, that's the hardcore warnings out of the way. Onward:

[note this would be /dev/mtd2 if you have root_fs in mtd2 above]


 * 1) echo && flashcp -v /tmp/rootfs.arm_nofpu.jffs2 /dev/mtd1 && echo > /dev/watchdog

If you have a Verdex board and have copied a separate uImage file across, you'll need to run this command instead:


 * 1) echo && flashcp -v /tmp/rootfs.arm_nofpu.jffs2 /dev/mtd1 && flashcp /tmp/uImage /dev/mtd2 && echo > /dev/watchdog

Ok, that's it -- the final "echo" there to the watchdog device will trigger a reboot 1 second after the new flash image is written to flash and correctly verified. Remember not to run this command unless you are sure you have a matching version of u-boot.

A small but very important note.

You need to pad the rootfs.arm_nofpu.jffs2 to the appropriate size or your filesystem will become corrupt after reboot.

Flash space is distributed like this:

U-Boot (mtd0) - 256K : 262144 Bytes. Kernel (mtd2) - 1M  : 1048576 Bytes. Padding size is FlashTotal - Kernel - U-Boot.

Basic / Connex Standard (4MB) : 2883584 Bytes = 0x2C0000. XM Series (16MB Flash)       : 15466496 Bytes = 0xEC0000. Verdex XL6P (32MB Flash)     : 32243712 Bytes = 0x1EC0000.

The padding can be automated by the buildroot build process:

make menuconfig

Target Options --> [*] Pad Output (0x0) Pad output size (0x0 = to end of EB) [ ] Use sumtool to write summaries to the filesystem

Enable "Pad Output" Disable "sumtool" Replace 0x0 "Pad output size" with the hex value, matching your system, from the list above.

Finish building the system, and upload.

Flashing over serial
You can flash a Gumstix easily using a standard serial cable and Kermit/cKermit, or a communications program that supports Kermit-style file transfer. Connect the cable to the Gumstix's console serial port and start your communications software. For the console-vx board, use the middle port of the three present.

To flash the Gumstix, you will be communicating with the uboot bootloader. Uboot uses 115200 baud, 8 data bits, 1 stop bit, and no parity (115200/8n1), with no flow control. For the Kermit-style file transfer, your communications software must be set to send files in binary format.

Connect via serial
Follow the instructions at the page appropriate for your host OS:

Connecting via Serial - Linux

Connecting via Serial - MacOSX

Connecting via Serial - Windows

This will allow you to reach Linux login prompt.

Now, turn on or reboot your Gumstix. Almost immediately, it will prompt you (through the serial console) to press any key to stop booting and access uboot. Press a key.

Basix and Connex, pre-1326
These instructions apply to revisions BEFORE 1326. For 1326 and after, use the Verdex instructions.

At the  Uboot prompt, tell it to receive a file: loadb a2000000

(There are six zeros following the a2 in that line.)

Now, send your filesystem image. In Kermit/cKermit, press Ctrl-backslash and then c to access the control prompt, and type send rootfs.arm_nofpu.jffs2

Once your file transfer succeeds, the Gumstix is holding your new filesystem in RAM. The contents of Flash are still intact; aborting at this point will simply revert to your old filesystem. Connect to the UBOOT loader again... type the following and press enter. connect

Getting the new filesystem to take hold is a two-step process. First, the old filesystem must be erased; then, the new filesystem must be written from RAM to flash.

To erase the old filesystem, enter protect on 1:0-1 erase all

The first line protects flash sectors 0 and 1, which contain the uboot bootloader you're currently communicating with. This line is very important. If you omit it, your Gumstix will be unusable and will have to be reflashed using a far more complicated process.

Now, commit your new filesystem to flash: cp.b a2000000 40000 ${filesize}

This copies your new filesystem into flash (at address 40000 hex, for the curious). is a reference to the variable filesize, which was set by your file transfer. If this does not work simply convert the size of rootfs.arm_nofpu.jffs2 into hex (lowercase letters) and use instead. Also on different versions of uboot the variable can be either ${filesize}, $(filesize) or $filesize.

Once the copy completes, you can boot directly into your new filesystem by typing: boot

Verdex and post-1325 versions of Basix and Connex
The kernel (uImage) has been pulled out of filesystem (rootfs.arm_nofpu.jffs2) for Verdex, so the procedure is a little different. To switch between the GUM> prompt and kermit>, type CTRL-\ and then C.

So you have 3 files: bootloader (u-boot.bin), kernel (uImage), filesystem (rootfs.arm_nofpu.jffs2).

Replacing u-boot.bin is not safe and is done only if you need to. If it fails you are in trouble. DO NOT POWER DOWN! Read more in http://docwiki.gumstix.org/Replacing_the_filesystem_image#Flashing_over_SSH_.2F_ethernet If you are sure you need to replace u-boot.bin read at the end of http://docwiki.gumstix.org/U-boot#Loading_new_stuff_to_flash

U-Boot version 1.2.0
First, load the filesystem: GUM>loadb a2000000 kermit>send rootfs.arm_nofpu.jffs2 kermit>connect GUM>pro on 1:0-1 && jera all && cp.b a2000000 40000 ${filesize}

Now, load the kernel: GUM>loadb a2000000 kermit>send uImage kermit>connect GUM>katinstall 100000 GUM>katload 100000 GUM>bootm

If katinstall gives you a problem, make sure that your uboot is up to date.

U-Boot version 1.1.4
If your U-Boot is 1.1.4 and compiled u-boot.bin is 1.2.0 or newer look at the end of http://docwiki.gumstix.org/U-boot#Loading_new_stuff_to_flash for replacing U-Boot and then continue with 1.2.0 or newer instructions depending of your new u-boot version.

Copy the kernel into the root-Filesystem and rebuild the root-filesystem: host> cd ~/gumstix-buildroot host> mkdir -p build_arm_nofpu/root/boot/ host> cp uImage build_arm_nofpu/root/boot/ host> rm rootfs.arm_nofpu.jffs2 host> make ...

Then flash the filesystem: GUM>loadb a2000000 kermit>send rootfs.arm_nofpu.jffs2 kermit>connect GUM>pro on 1:0-1 && jera all && cp.b a2000000 40000 ${filesize} ... GUM>bootm

Using Minicom
You can use Minicom to do the Kermit transfer, but you still need to have the Kermit (cKermit) program installed. This is because U-Boot doesn't accept Minicom data-transfer. Create a ~/.kermrc file, with these contents:

set carrier-watch off set reliable fast set prefixing all set file type bin set rec pack 4096 set send pack 4096 set window 5 set modem type none set flow-control none

Flashing from MMC
You can flash your Gumstix's root filesystem by copying the filesystem image onto an MMC card. This is much faster than transferring the image serially, but will only work on Gumstix systems with an MMC slot.

The process is very similar to flashing the Gumstix serially, and you should read the directions for serial flashing before beginning this process. You will still need a serial cable and appropriately-configured communications software, as described above.

Boot the Gumstix and access the Uboot console, as described in the directions for serial flashing.

Initialize the mmc card by issuing the command: mmcinit. You should see some output that looks something like this (your actual output may vary depending on the version of u-boot and the exact MMC card used): GUM> mmcinit MMC found. Card desciption is: Manufacturer ID = 490000 HW/FW Revision = 1 9 Product Name = 460XFI Serial Number = 3e0cea Month = 8 Year = 2003

You can view the files on the MMC card by using the command: fatls mmc 1

Now, transfer the file from the MMC card into RAM on the Gumstix: fatload mmc 1 a2000000 rootfs.arm_nofpu.jffs2

Again, there are six zeros there.

(Replace  with the path to your file, if you have changed the name or put it in a directory on the card.)

Next, use exactly the same process as for serial flashing to erase and write the new image: protect on 1:0-1 erase all cp.b a2000000 40000 ${filesize}

And finally: boot

Flashing from CompactFlash
U-Boot 1.2 can flash from compact flash. Use: pinit on to tell it to find your CF card. You should see a report about the features of your card.

Then continue on with the flashing process as with mmc, except use "ide 0" where you would use "mmc 1": fatload ide 0 a2000000 rootfs.arm_nofpu.jffs2

Flashing over TFTP
If you have a network card for your gumstix, you can use TFTP to load files. You need to set the serverip variable to be the IP address of your TFTP server, and the ipaddr variable to IP address that you wish to assign to the gumstix. The IP addresses shown below are typical, you may need to adjust them for your network. Your freshly built root_fs (and U-Boot image if you are brave enough to upgrade that via TFTP) should be in the root of your TFTP server. Boot the Gumstix and access the Uboot console, as described in the directions for serial flashing, and then enter the following commands (editing the IP addresses appropriately):

setenv serverip 192.168.1.1 setenv ipaddr 192.168.1.20 saveenv tftp a2000000 [your rootfs image name, e.g rootfs.arm_nofpu.jffs2]

and then erase and copy into flash:

protect on 1:0-1 erase all cp.b a2000000 40000 ${filesize}

And finally: boot

Under Windows, the following free TFTP servers have been used successfully: tftpd32 and uCon. Under MacOS X, the following TFTP server has been used successfully: TftpServer.

Copying the flash image
You can make a copy of the flash

u-boot dd if=/dev/mtdblock0 of=/tmp/saved-mtd0

root mount -o remount,ro / dd if=/dev/mtdblock1 of=/tmp/saved-mtd1

then move this copy off the gumstix using scp or copy it to a mounted mmc or cf card

For newer buildroots which put the kernel in a separate partition, you can copy the kernel off using a command similar to that used for u-boot:

dd if=/dev/mtdblock2 of=/tmp/saved-mtd2

Note: the default load address is a2000000. u-boot stores its heap in the memory region just before a3f00000. The current heaps size is around 260K.

What this means is that if you save the image of a verdex XL6P, your image size will be too big to load at a2000000. It will wind up overwriting a portion of the heap, and u-boot will likely hang. Using a load address of a4000000 will work in this situation (but only on the XL6P - since it has 128 Mb of RAM and a4000000 starts at the 64Mb boundary).

Troubleshooting
If you can't make the "ctrl-backslash c" work, when you reach this point kill the terminal (kermit) and set up the connection again (without doing a connect). After this you will be ready to send the file. Holding alt down while typing 28 on the numerics follwed by c might do the trick.