How to flash upgrade


This guide describes how to flash an ETRAX based product using the most commonly used methods of flashing, all using an Ethernet network. The methods described in this document can be divided into two groups. One low level group containing methods suitable for development and production. And one high level group suitable for firmware upgrade of products on the field. The low level group comprise the "Network boot mode" method while the high level group comprise FTP and HTTP upgrading.

The instructions below will guide you through how to flash an ETRAX based product. If you encounter any problems read the theory chapter to get a better understanding of the process.


Please read the SDK Organization document on the Axis Developer WIKI.

  • Examples in this document assume that you have installed the Developer Board/ Device Server SDK in a directory called axis/devboard in your home directory (the expression "~/axis/devboard" will be used throughout this document). If this is not the case, just keep it in mind and use your installation directory instead of ~/axis/devboard in the examples.

  • Text within angle brackets “<>” should be read as a placeholder for something else, for example, linux-<kernel version> could be linux-2.6.12.

  • The developer board/device server or a design based on an ETRAX chip will be referred as "the target platform", "the target system" or simply "the target".

  • The PC running Linux which usually has the SDK installed will be referred as the "Linux host" or simply "the host".

Network boot mode theory

Normally the target platform boots from either NOR or NAND flash memory. However, most ETRAX based designs have the opportunity to start the ETRAX chip in one or more alternative bootstrap methods. The most commonly used alternative is network bootstrapping that allows the ETRAX chip to start from a specially formed Ethernet packet. When the ETRAX chip boot it scans a few pins to determine which bootstrap method to use. How to alter these pins to get into the network boot mode (or network bootstrap mode) is dependent on the design, usually a button or a jumper exist for this purpose. The normal procedure to set a target system in network boot mode is to press the network boot button or close the network boot jumper while releasing the reset button (or wile turning on the power) i.e. the boot button must be kept down while the chip powers up.

A program is used on the host to control the communication between the target and the host. This program consist of two parts, one running on your Linux host and one that is uploaded to and executed on the target. By setting up this client/server environment the target system can be controlled which, for example, allows for flash programming. This program is distributed with the SDK and is named "etrax100boot" for ETRAX 100LX based designs (which also involves all ETRAX 100LX MCM designs) and "etraxfsboot" for ETRAX FS based designs.

Since the network bootstrap method use raw Ethernet packages no IP or TCP has to be enabled on either the host or the target. However, this also implies that the packages used will be filtered when trying to pass a router. As a consequence the network boot method will only work if the host and the target are connected to the same network segment.

The "etrax<chip_version>boot" program can do a few basic things. The most important features are probably the ability to set registers, upload files, write to flash memory, perform memory tests and so on. Generally you will always have to set some registers before doing anything else, for example, to use the SDRAM memory you will have to go through the SDRAM configuration cycle by setting a few registers. Figuring out how to do this is not easy, therefore a script has been developed to extract the required parameters from the firmware image produced by the SDK. This script is named "boot_linux" for for ETRAX 100LX based designs (which also involves all ETRAX 100LX MCM designs) and "boot_etraxfs" for ETRAX FS based designs. The purpose of the script is to ease the firmware flashing which by far is the most common reason for using the network boot mode. Running the "boot_<linux/etraxfs>" script will extract the required parameters from the firmware image file and then run either the "etrax100boot" or the "etraxfsboot" program with the appropriate arguments. Below is a list of the most commonly used arguments for the boot_<linux/etraxfs>" script.

-d <device>
The network interface to use, default is eth0.

Save the whole firmware image to flash except the rescue partition.

Save the whole firmware image to flash. NOTE that this will overwrite parameters stored in the rescue partition such as the serial number/MAC address.

Print help text (information on additional options not showed here)

-i <image>
The path and name of the image to use, default is fimage.

Print the resulting "etrax<chip_version>boot" command instead of executing it.

Test a firmware image - using the network boot mode

This method allows a firmware image to be tested before written to the flash memory. The firmware is uploaded to the RAM and executed from there which implies that the firmware stored in the flash is not affected. This process use the ~/axis/devboard/kimage file that contain the kernel and the ROM file system. Since the kimage does not include the writeable jffs2 partition there must be a valid firmware image stored in the flash to use this method. Since the firmware is not written to the flash this method is recommended during development as it is considerably faster than other methods.

  1. Enter the SDK root directory
    'cd ~/axis/devboard/'
  2. Source the "init_env" file to append the the path to the tools. (This step is only required if the "init_env file have not been sourced in the shell before.)
    '. init_env' or 'source init_env'
  3. Set the target system in network boot mode.
  4. As root execute the "boot_linux" script for ETRAX 100LX based designs or the "boot_etraxfs" script for ETRAX FS based designs.
    'boot_<linux/etraxfs> -i kimage'

Flash upgrade - using the network boot mode

This method write the firmware image to the flash memory on the target system. Observe that this method will overwrite the configuration files in the /etc directory, which will affect, e.g., network settings.

  1. Enter the SDK root directory
    'cd ~/axis/devboard/'
  2. Source the "init_env" file to append the the path to the tools. (This step is only required if the "init_env file have not been sourced in the shell before.)
    '. init_env' or 'source init_env'
  3. Set the target system in network boot mode.
  4. As root execute the "boot_linux" script for ETRAX 100LX based designs or the "boot_etraxfs" script for ETRAX FS based designs.
    'boot_<linux/etraxfs> -f'

The "-f" option as used above overwrite the whole flash except for the rescue partition that include important parameters. However, if the product has a empty flash or for some other reason requires that the whole flash is (re)written use "-F" instead of "-f". NOTE that using "-F" will overwrite, e.g., the serial/MAC number, consequently it is not recommended to use "-F" unless you know what you are doing.

The network interface card on the Linux host must be specified unless the card that is connected to the target system is "eth0", which is the default. You specify this by adding the -d <ethX> option to the boot_<linux/etraxfs> script where "X" is the interface number.

FTP and HTTP upgrading - Theory

Upgrading the flash using FTP or HTTP requires that the target system is up and running. Moreover, the target system has to be accessible over an TCP/IP network and it must have the appropriate software, supporting this upgrade method, running.

The vftpd FTP server shipped in the SDK has two virtual targets. This implies that if you upload a file to that target the vftpd server will start the flash progress instead of storing the file. The two available targets are "flash" and "flash_all". The "flash" target will replace the kernel and root partition while the "flash_all" target will flash everything except the rescue partition that include parameters such as the serial number/MAC address.

The boa HTTP server shipped in the SDK comes with a CGI plug-in that allows uploading and writhing of an firmware image though a browser.

In both the FTP and HTTP case an application named flash reside on the target system. This Linux application performs the actual writing of the flash memory. Both the FTP or HTTP server use this application. 

Flash upgrade - using FTP

To flash your board using ftp start up a text based ftp program such as ftp in GNU/Linux. Login and execute the "put fimage flash" command. This will upload the fimage to the developer board and flash it. When finished with flashing the board will reboot with the new image.


$ ftp
Connected to
220 Axis Developer Board 82+/83+ release 2.00 (Jun 15 2005) ready.
Name ( root
331 User name okay, need password.
Password: pass
230 User logged in, proceed.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> binary
200 Command okay.
ftp> put fimage flash
local: fimage remote: flash
200 Command okay.
150-Shutting down processes.
Preparing system for upgrade ...
Entering run level 4 ...
Waiting for processes to be stopped in runlevel 4 ...
... waiting ...
... waiting ...
In run level 4.
Stopping remaining processes.
   sending TERM signal ...
All processes stopped.
The file system will be upgraded after reboot.
Unmounting file system /var ...
Unmounting file system /mnt/flash ...
File systems successfully shut down.
150 Opening data connection.
214-Virtual target execution.
Receiving new firmware ...
Erasing old file system ...
Loading new file system ...
The system upgrade completed successfully.
The unit will now reboot.
To continue, please connect to the unit again.
There may be a short delay before the new connection is accepted.
This connection will now close.
214 Virtual target exit.
8388632 bytes sent in 3.68 secs (2229.1 kB/s)

Serial flashing

As mentioned above the ETRAX chip supports several bootstrapping methods. One of these are the serial bootstrapping. Serial flashing is not described in this document but there exists an excellent Windows application, developed by Indunet, which you can read more about here.