This document describes how to write and build applications for Linux running on ETRAX 100LX using the C programming language, gcc-cris and make. 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_lx in your home directory. If this is not the case, just keep it in mind and use your installation directory instead of ~/axis/devboard_lx in the examples. See also How to Install the Developer Board LX Software.
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 transferred 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_lx/apps mkdir hello
Write the source code and save it to a file called ~/axis/devboard_lx/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_lx/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_lx/apps/hello directory (note: make requires tabs instead of spaces in some places):
USE_UCLIBC=1 include $(APPS)/Rules.elinux INSTDIR = $(prefix)/bin INSTMODE = 0755 PROGS = hello SRCS = hello.c OBJS = hello.o CFLAGS += -Wall all: $(PROGS) $(PROGS): $(OBJS) $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@ install: $(PROGS) $(INSTALL) -d $(INSTDIR) $(INSTALL) -m $(INSTMODE) $(PROGS) $(INSTDIR) clean: rm -rf $(PROGS) *.o core
This may seem like a awful lot for a makefile, 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/ipsetd, 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_lx/ . ./init_envIf your shell does not understand
. ./init_env try source ./init_env instead.
Depending on whether a file named .target_clinux exists (in the same directory as the Makefile) or not the executable will be built for the developer board or your host operating system respectively.
(clinux is short for cris-linux which refers to the cris architecture in Linux 2.4.)
You can create the file by typing:
make clinuxThe magic of this is in
apps/Rules.elinux, which is included by the Makefile.
If a file named .target_clinux does not exist or the file .target_host exists make will build the application for your PC. To create .target_host type:
make host
When building for CRIS with the Makefile above you need to have uC-libc compiled for the CRIS target and installed (if you have already built a product, this step is not necessary -- doing it again will not cause any damage, though):
cd ~/axis/devboard_lx/libs/uC-libc make clinux make install
Now you can build the executable using make:
cd ~/axis/devboard_lx/apps/hello make clinux make
The output should look something like this:
gcc_cris -mlinux -DCRISMMU -muclibc=~/axis/devboard_lx/eroot -O2 -Wall -D__linux__ -Wall -c -o hello.o hello.c gcc_cris -mlinux -DCRISMMU -muclibc=~/axis/devboard_lx/eroot -s -static 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:
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 directory ~/axis/devboard_lx/eroot, which will be used as the root directory of the compressed ROM file system image, or you edit the file ~/axis/devboard_lx/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_lx/eroot/bin.
Then you need to build the new ROM file system image without rebuilding the applications:
cd ~/axis/devboard_lx make images
If you would run make install in the devboard_lx 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_lx/makespec and add the name of your directory (apps/hello) to the <subdirs> section:
<subdirs> apps/init apps/net-tools . . . apps/ping apps/mactool # New application added by me apps/hello
Then run make like this:
cd ~/axis/devboard_lx make install make imagesWhen the make is done new images have been created. To test the new ROM filesystem first put your devboard 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_lx (set the board in boot mode) ./ktest
When ktest is executed the image file ~/axis/devboard_lx/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_lx/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_lx (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_lx/files/etc/network. You can edit this file and run
make files (or make install) and make images again from the devboard_lx 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_lx 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, 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 gcc-cris.
There is, however, no port of the standard C++ library for CRIS Linux yet.