This document describes how to write and build applications for Linux 2.4 or 2.6 running on ETRAX 100LX. It deals with how to use the C programming language with the gcc-cris compiler and the Developer Board/Device Server SDK release 2.00 or later. It also describes how to include the developed application in a custom firmware images.

Requirements

To be able to compile software aimed to run on the ETRAX 100LX the Developer Board/Device server SDK and the CRIS compiler has to be properly installed. Please have a look at How to Install the Developer Board Software for guidance on how to prepare your system for software development for the ETRAX 100LX.

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.

Theory

Creating an executable for Linux on ETRAX 100LX involves writing the source code, cross compiling and linking it on a PC. Once the CRIS executable is created it can be transferred to the hardware in two different ways, either as a standalone application or included in a new firmware image.

The standalone executable has to be uploaded to the target with, e.g., FTP and has to be placed on the writeable partition (/mnt/flash). Using this method can be considered “safe” since it does not interfere with the target system (which is mounted as a read only partition). The target system is not affected and as a consequence it has to support all requirements of the application. Hence it is recommended that the SDK version, used when developing an application, is the same as the one the target system were derived from.

Adding the custom application to an ROM image will result in that the application resides on the read only kernel partition. To place it there the Developer Board/Device Server has to be flashed with a new firmware (upgrading all software). This method provides more flexibility since the system running on the target can be customized for a specific purpose. Read more about how to flash in the How to Flash Upgrade guide.

More about how to configure the SDK to perform one of the above approaches can be found later on in this guide.

Process

Let us write a simple application that writes "Hello World!" to standard output and run it on the developer board. First we confirm that the “Hello World!” is functional on the host and then we port this very simple application to the target (the developer board). To start with we build the application as a standalone application for both the host and the target systems.

Compiling “Hello World!” for host

First we need a directory for our new application. Create a directory in the ~/axis/devboard/apps directory. Let us call our application hello which makes it natural to create a directory named hello:

Write the source code and save it to a file called


                  
                  ~/axis/devboard/apps/hello/hello.c

#include <stdio.h>
int main(int argc, char *argv[]) {
printf("Hello World!\n");
return 0;
}

This will create an executable for your computer and operating system named a.out in your working directory. Try it:

Compiling “Hello World!” for target

Now that we know that the application works for your operating system, let us proceed and make an executable for the developer board. This will require a bit more work than just running gcc, therefore the easiest approach is to use the make program. Write a Makefile (a file with rules for the make program) and save it in the


                  
                  ~/axis/devboard/apps/hello

directory.

install: $(PROGS)
$(INSTALL) -d $(INSTDIR)
$(INSTALL) -m $(INSTMODE) -o $(INSTOWNER) -g $(INSTGROUP) $(PROGS) $(INSTDIR)

Note: make requires tabs indents, spaces will not work.
Tips: Normally you do not write a Makefile from scratch but copy the Makefile from another apps directory, for example


                  
                  apps/init/Makefile

, and modify it.

This may seem like an awful lot of work for a compiling one c-file, but this is just to make things easier later on. Depending on the contents of a file named .target-makefrag (in the same directory as the Makefile) the executable will be built for the Developer Board/Device Server or your host. You should not create the file manually, instead create the file by typing make <target> (in the same directory as the Makefile). This will instruct make which compiler to use when building our “hello” application. Available <targets> and their effect can be seen in the table below.

Target name	Description
cris-axis-linux-gnu	Build the application for Etrax 100LX with the glibc standard C library.
cris-axis-linux-gnuuclibc	Build the application for Etrax 100LX with the uClibc standard C library.
host	Build the application for the host system.

As you may have noticed the AXIS_TOP_DIR variable in the Makefile above is not set, therefore make will fail if you try to build the application. Hence we need to set this variable before running make. The easiest way to set all variables correctly is to source the init_env file in the SDK root directory. NB The init_env file will only exist if make have been executed in the SDK root directory, if not you can make it running “make init_env”. To source the init_env file execute the following commands:

If your shell does not understand “. init_env” try “source init_env” instead.

To build the hello executable for the cris architecture and glibc use the following commands:

gcc-cris -isystem /home/karljope/axis/devboard/target/cris-axis-linux-gnu/include -mlinux -mno-mul-bug-workaround -Wall -Wshadow -O2 -g -c -o hello.o hello.c
gcc-cris -isystem /home/karljope/axis/devboard/target/cris-axis-linux-gnu/include -mlinux -mno-mul-bug-workaround -L/home/karljope/axis/devboard/target/cris-axis-linux-gnu/lib -Wl,-rpath-link,/home/karljope/axis/devboard/target/cris-axis-linux-gnu/lib hello.o -o hello

If nothing happens when you run make you may need to remove any existing .o-file and executable. In that case type:

Getting the “Hello World!” application into the Developer Board

So far in this guide we have compiled the “Hello World” application for the target system, now it is time to get the application into the developer board. This could be done in two principal ways as described earlier in this document:

Stand-alone application

When using FTP for transferring files to the developer board, you must put them in the flash file system since you cannot write to the ROM file system. The flash file system is mounted at /mnt/flash on the board. Since transferring a file using FTP will not make the file executable you must set the execute bits manually using the


                  
                  chmod

command from the FTP client. Make sure you transfer the file in binary mode (as opposed to ASCII mode). The default root password is 'pass'.

$ 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> cd /mnt/flash
250 Command successful.
ftp> binary
200 Command okay.
ftp> put hello
local: hello remote: hello
200 Command okay.
150 Opening data connection.
226 Transfer complete.
17740 bytes sent in 0.00 secs (9705.4 kB/s)
ftp> chmod 755 hello
200 Command okay.
ftp> quit
221 Goodbye.

Now when the executable is uploaded to the developer board and we can verify that it works. Login with telnet, ssh, or via the serial terminal and try the “Hello World!” application. When logged in type:

New ROM file system

There are two different ways to include the “Hello World!” application in a new ROM file system. Either you just install the executable manually into the target directory in


                  
                  ~/axis/devboard/target/

, which will be used as the root directory of the compressed ROM file system image. Or you could edit a configuration file to tell the build system that your application should be included in the ROM file system automatically when running make in the SDK root directory.

The manual method
Chose this method if you would like to install the executable manually. In this example it is assumed that the target system is already built once before. Assure that the build type for your application is the same as the build type of the target system, if not change the build type of your application.

The executable will then be installed in ~/axis/devboard/target/<target type>/bin all according to the Makefile we created earlier.

This will create the images that you have to flash your developer board with. Consult the How to Flash Upgrade guide for instructions.

Note: Running make in the SDK top-level directory creates a new target directory resulting in that applications manually installed with this method are not included in the images. As a consequence this procedure must be performed for each manually added application after every time a top-level make have been performed.

The automatic method
Chose this method if you wish to create your ROM images (including the application) by running make in the SDK top-level. First, let us see how the build system works.

The top-level Makefile has a variable (SUBDIRS) containing a list of applications, libraries, packages, and the Linux kernel. This variable simply lists all the source code directories in the SDK that should be compiled and included in the ROM images when running make. Adding the directory apps/hello in this list is enough to make make work as desired. However, the top-level Makefile is created by the configure script and hence it is not recommended to edit the Makefile directly since it very likely will be overwritten. Instead we can add the directory for the “Hello World!” application by editing the configuration files used by the configure script. The configure script make use of several files to create the Makefile. In this example we will edit (or create) the ~/axis/devboard/configure-files/post file which is one of these.

NB: If you use the 2.00 release of the SDK the support for the ~/axis/devboard/configure-files/post file is not included, instead add the content described below to the ~/axis/devboard/configure-files/devboard/devboard file.

The ~/axis/devboard/configure-files/post file is not distributed with the SDK, so do not panic if you can not find it. Fire up your favourite text editor and add the following line to the ~/axis/devboard/configure-files/post file:

These lines inform the build system which source packages to fetch and unpack into the SDK hierarchy. More important to us the file path is added to the SUBDIRS variable. If the package exists in the SDK hierarchy (the directory is present) the configure script only adds the package to the SUBDIRS variable, hence it does not try to fetch it. Read more about the sub function and other functions in the functions guide.

When the make is done new images have been created. The next part step is to flash upgrade the developer board with your newly created images. Consult the How to Flash Upgrade guide for instructions.

Now boot your target system and login with telnet, ssh, or via the serial terminal and try the “Hello World!” application. When logged in type:

Notes

You can find out more about the make targets by running


                  
                  make help

in the


                  
                  ~/axis/devboard