This document describes how to write and build applications for Linux (including elinux) running on ETRAX 100 or ETRAX 100LX using the C programming language, gcc-cris or make (Linux 2.4 cannot run on the older ETRAX 100, elinux can run on both but ETRAX 100 and ETRAX 100LX, but Linux 2.4 is a better choice if you have an ETRAX 100LX). It also describes how to transfer an application to the hardware and execute it.
Examples in this document assumes that you have installed the developer board
software in a directory called axis/devboard,
axis/devboard_lx or axis/devboard_bt 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.
See also the software installation guide (Developer Board
82, Developer Board LX
or Developer Board for Bluetooth)
Creating an executable for Linux on ETRAX 100LX involves writing the source code, cross compiling and linking it on a PC. Once the ETRAX executable is created it can be transfered to the hardware in a number of different ways and executed.
Let us write a simple application that writes "Hello World!" to standard output
and run it on the developer board.
First we need a directory for our new application.
Create a directory in the apps directory.
The tool we will use to build a new image for the developer board (the top-level
Makefile) will assume that applications resides in subdirectories in the
apps directory.
Avoid naming an application test since test is a shell builtin in most
shells and might also be an existing executable in your environment. Let us call
our application hello.
We then create a directory apps/hello for it:
cd ~/axis/devboard*/apps mkdir 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;
}
Compile it for your host:
cd ~/axis/devboard*/apps/hello gcc hello.c
This will create an executable for your operating system named a.out in your working directory. Try it:
./a.out
The output should be:
Hello World!
Now that we know that the application works for your operating system, let us 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 make.
Write a makefile called Makefile and save it in the
~/axis/devboard*/apps/hello directory (note: make requires tabs
instead of spaces in some places):
AXIS_USABLE_LIBS = GLIBC UCLIBC include $(AXIS_TOP_DIR)/tools/build/Rules.axis PROGS = hello INSTDIR = $(prefix)/bin/ INSTMODE = 0755 INSTOWNER = root INSTGROUP = root OBJS = hello.o all: $(PROGS) $(PROGS): $(OBJS) $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@ install: $(PROGS) $(INSTALL) -d $(INSTDIR) $(INSTALL) -m $(INSTMODE) -o $(INSTOWNER) -g $(INSTGROUP) $(PROGS) $(INSTDIR) clean: rm -f $(PROGS) *.o core
This may seem like a awful lot for a compiling one c-file, but this is just to
make things easier later on.
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.
To build for the developer board you first need to set some additional environment variables. The easiest way to do this is to run the init_env script that should exist in the product directory of the source code tree:
cd ~/axis/devboard*/ . ./init_envIf your shell does not understand
. ./init_env try
source ./init_env instead.
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
or your host operating system.
You should not create the file manually.
Create the file by typing:
make cris-axis-linux-gnuif you are using the devboard_lx or devboard_bt software and
make elinuxif you are using the devboard software.
The magic of this is in apps/Rules.elinux, which is included by
the Makefile.
To prepare for building the application for your PC (host) instead type:
make host
Now you can build the hello executable for the developer board using make:
cd ~/axis/devboard*/apps/hello make cris-axis-linux-gnu (or elinux) make
The output should look something like this:
gcc-cris -mlinux -isystem /home/john/axis/devboard*/eroot/include -Wall -O2 -c -o ipsetd.o ipsetd.c gcc-cris -mlinux -isystem /home/john/axis/devboard*/eroot/include -s -L/home/jonashg/axis/products/tech/devboard*/eroot/lib ipsetd.o -o ipsetd
If nothing happens when you run make you may need to remove any existing .o-file and executable. In that case type:
make clean make
If no errors occur an executable named hello will be created.
There are at least two ways of getting the executable into the developer board:
The easiest way would be using the top-level Makefile.
Then you have two alternatives:
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 edit the file
~/axis/devboard*/makespec to tell the top-level Makefile that your
application should be included in the ROM file system.
If you choose to just install the executable manually, use the Makefile we just wrote and type:
make installThe executable will then be installed in ~/axis/devboard*/eroot/bin.
Then you need to build the new ROM file system image without rebuilding the applications:
cd ~/axis/devboard* make images
If you would run make install in the devboard*
directory, all applications (subdirs) in the makespec file would be built and
installed.
That would be the intended way of using the top-level Makefile.
Let us see how that works.
Instead of installing the executable manually you then edit the file
~/axis/devboard*/makespec and add the name of your directory
(apps/hello) to the <subdirs> section:
<subdirs> . . . apps/busybox -r R1_1_6 apps/ipsetd -r R1_0_1 apps/tools/gdbserver -r R1_0_1 apps/utils/eraseflash -r R1_0_1 apps/utils/readbits -r R1_0_1 # New application added by me apps/hello </subdirs>
Then run make like this:
cd ~/axis/devboard* make install make imagesWhen the make is done new images have been created. To test the new ROM filesystem first put your developer board in boot mode by pressing the boot button, pressing and releasing the reset button and then releasing the boot button (i.e. the boot button must be kept down while resetting the developer board). Then run the script
ktest (this requires that the developer board
is on the same network segment as your computer, otherwise use FTP):
cd ~/axis/devboard* (set the board in boot mode) ./ktest
When ktest is executed the image file
~/axis/devboard*/kimage containing the kernel and the ROM file
system (created by the toplevle-Makefile) will be sent to RAM on the developer
board by the ETRAX 100 bootloader (etrax100boot) and the board will execute it.
Everything sent to the developer board using ktest is stored in RAM on the board and therefore lost upon reboot.
To make the changes permanent use ./flashit instead of
./ktest.
This will send the image file ~/axis/devboard*/fimage containing
the kernel, the ROM file system and the flash file system to the RAM on the
developer board and the board will then write it to flash before execute it.
If your computer is not using the eth0 interface to connect with the network
where the developer board is, you must specify which network interface to use
with ktest (or flashit).
You do this by adding the -d option in the kflash (or ktest) script.
For example:
cd ~/axis/devboard* (set the board in boot mode) ./flashit -d eth1Note that the flash file system of the board is then rewritten including configuration files in the /etc directory, which will result in the network settings of the board being replaced with those in
~/axis/devboard*/packages/initscripts/network.
You can edit this file and run make install and
make images again from the devboard* directory to
make the flash file system image contain your network settings.
When the board is up and running you can telnet to it and execute your
application by typing hello in the shell of the developer board.
When using FTP for transfering 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'.
Example:
$ ftp 123.45.67.89 Connected to 123.45.67.89. 220 Simple-FTPd (sftpd) ready. Name (123.45.67.89:john): 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> bin 200 Command okay. ftp> put hello local: hello remote: hello 200 Command okay. 150 Opening data connection. 226 Transfer complete. 1298 bytes sent in 0.000105 secs (1.2e+04 Kbytes/sec) ftp> chmod 755 hello 200 Command okay. ftp> quit 221 Goodbye.
You can find out more about the make targets by running make help
in the devboard* directory.
The ktest and flashit scripts are oftenly used during development for ETRAX.
There are, however, alternatives to these scripts;
kflash writes only the kernel and ROM file system to the flash
(leaving the flash file system untouched).
flashitall will write the entire fimage to the flash, thereby
overwriting the rescue partition containing rescue code and parameters, such as
the serial number,
this is not recommended, unless you know what you are doing!.
These scripts are all using the boot_linux tool for giving
arguments to the boot loader (etrax100boot).
Any image of any size can be written to any part of RAM or flash by giving the
correct arguments to boot_linux or etrax100boot.
These scripts are just for convenience.
You can also develop for the ETRAX 100LX using the C++ programming language and
g++-cris.