How to flash upgrade

Introduction

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. If that does not help consult the dev-etrax mailing list. For instructions on how to send mail to the dev-etrax mailing list have a look at the contact us page.

Requirements

Please read the design of the SDK document first.

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

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

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 boots 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 exists 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 while turning on the power) i.e. the boot button must be kept down while the chip powers up.
Note The boot button must be kept down for some time after releasing the reset button (or after turning on the power). This time depends on the reset circuitry design. This time usually varies from 0.1 s to 2 s.

A program is used on the host to control the communication between the target and the host. This program consists 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 “crisv32boot”1) for ETRAX FS based designs.

Since the network bootstrap method uses 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 “crisv32boot” program with the appropriate arguments. Below is a list of the most commonly used arguments for the boot_<linux/etraxfs>” script.

Argument Explanation
-d <device>The network interface to use, default is eth0.
-fSave the whole firmware image to flash except the rescue partition.
-FSave the whole firmware image to flash. NOTE that this will overwrite parameters stored in the rescue partition such as the serial number/MAC address.
-hPrint help text (information on additional options not showed here)
-i <image>The path and name of the image to use, default is fimage.
-pPrint the resulting “etrax<chip_version>boot” command instead of executing it.

Note You must have root privileges when running boot_<linux/etraxfs> (and <etrax100/crisv32>boot). An error message like “Error, no suitable device found.” or “Error socket: Operation not permitted” indicates you don't have root privileges.

Test a firmware image

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

Enter the SDK root directory

cd ~/axis/devboard/

Source the “init_env” file to append the the path to the tools. (This step is only required if the “init_env file has not been sourced in the shell before.)

. init_env

or

source init_env

Set the target system in network boot mode.

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

This method writes 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.

Enter the SDK root directory

cd ~/axis/devboard/

Source the “init_env” file to append the the path to the tools. (This step is only required if the “init_env file has not been sourced in the shell before.)

. init_env

or

source init_env

Set the target system in network boot mode.

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 argument used above overwrites the whole flash except for the rescue partition that includes important parameters. However, if the product has an 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 a 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 includes 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 a firmware image though a browser.

In both the FTP and HTTP case an application named flash resides 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

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.

Example:

$ ftp 192.168.0.90
Connected to 192.168.0.90.
220 Axis Developer Board 82+/83+ release 2.00 (Jun 15 2005) ready.
Name (192.168.0.90:karljope): 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 ...
  1%
  .
  .
100%
Loading new file system ...
  1%
  .
  .
100%
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)
ftp>

Serial flashing

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

FIXME add instructions on how to use boot_<linux/etraxfs> for serial boot.

A great deal of effort has gone into making this documentation as correct as possible. The information here is provided “as is”, without warranty or guarantee of any kind. To be on the safe side, always contact us if you are in doubt.

1) It's named “etraxfsboot” in the 2.10 software distribution
 
axis/flash_howto.txt · Last modified: 2009/02/03 16:08 by jesper
 
All text is available under the terms of the GNU Free Documentation License (see Copyrights for details).