Asisi
Home

eCos and SID on ARM PID target HOWTO

Information

Author	Date	Version
Robert Cragie	20 Feb 2003	0.1 Draft

This document describes how to set up the environments for getting eCos and a target application to work with SID. By the end of this tutorial, you should be able to:

Build a simple, multi-threaded application linked with eCos.
Build the SID simulator infrastucture to support a simulated ARM PID target.
Debug and run the application using GDB (Insight) connected to a simulated ARM PID target.

What is eCos?

eCos is an embedded, configurable multi-threaded operating system which can target many systems and CPUs.

For more details see Redhat's eCos page.

What is SID?

SID is a simulation environment which allows a number of software-defined components to be built together to provide a target which simulates a real hardware target.

For more details see Redhat's SID page.

Assumptions

I am assuming use of the following environment:

Linux (although I have indicated where to get Windows versions where appropriate).
bash is used as the command shell.
The user's user ID is 'user'.
All created directories are based on the user's root directory (reached using 'cd ~', or 'cd /home/user').
Superuser access is possible.
Tcl/Tk is installed (8.0 or later)

It is undoubtedly possible to get it all working using cygwin on Windows(tm), but I have not done this.

The following syntax indicates a command run as user:

$ <command>

The following syntax indicates a command run as a superuser:

# <command>

Installing eCos

Getting eCos source

I would strongly recommend getting the latest CVS version of eCos, and not to attempt to use version 1.3.1, which still seems to be being used even though it is very old. The following contains extracts from Redhat's eCos anonymous CVS page.

Type the following command to login to the CVS server:

$ cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos login

You will be prompted for a password which is anoncvs. You only need to perform this login the first time you access the eCos CVS repository. The password is saved in the file .cvspass in your home directory for use in subsequent sessions.

It is recommended that you use different directory trees for the anonymous CVS sources and for full releases of eCos. Create a new directory for the check out and change to that directory:

$ mkdir ~/ecos-cvs

$ cd ~/ecos-cvs

Now type:

$ cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos co -P ecos

This command should initiate a connection to the CVS server and check out the latest version of eCos, including TCP/IP networking stack and SNMP. It may take quite a while.

If you are unable to use CVS, you can get snapshots from eCosCentric here. The latest one is called ecos-v2-alpha-snap.tar.bz2; get this and unzip it into the ecos-cvs directory:

$ bunzip2 -c ecos-v2-alpha-snap.tar.bz2 | tar xvf -

Getting eCos Configuration Tool Version 2

I would recommend using the graphical Configuration Tool as it is generally easier to use than trying to decipher the relatively terse configuration files to change options. The following contains extracts from Redhat's eCos Configuration Tool Version 2 page:

Under Linux

Download configtool-2.11-i386.tar.gz (3.1Mb) or configtool-2.11-i386.tar.bz2 (2.8Mb)

Login as superuser and unarchive the tar file into a suitable directory. I am assuming here that /opt/ecos/configtool is the required destination directory for all files (note: configtool does not have to be installed by superuser, but it is preferable):

$ su

# mkdir -p /opt/ecos/configtool/bin

# cd /opt/ecos/configtool/bin

# tar xvfz /home/user/configtool-2.11-i386.tar.gz

(or, if you dowloaded the bz2 version:)

# bunzip2 -c /home/user/configtool-2.11-i386.tar.bz2 | tar xvf -

As there is only one executable, it is probably easiest to create a symbolic link to it:

# ln -s /opt/ecos/configtool/configtool-2.11/bin/configtool /usr/bin/configtool

Alternatively, make sure that /opt/ecos/configtool/configtool-2.11/bin is added to your PATH environment variable.

The following files will be extracted to the installation directory:

configtool, ecoslogo.png, rhlogo.png, about.htm, README.txt, license.txt, ecosplatforms.tar.gz, manual/

Optionally, untar the contents of ecosplatforms.tar.gz into your home directory, where it will create a directory called .eCosPlatforms. The information in these files isn't yet used by the Configuration Tool, but will keep the tool from generating some warnings.

The executable is statically linked to the wxWindows library, but does require the GTK+ 1.2, GDK 1.2 and TCL 8.x libraries to be installed.

Note: On SuSE Linux, there needs to be an additional symbolic link to the Tcl library. Do the following:

# cd /usr/lib

# ln -s libtcl8.3.so libtcl.so

Under Windows

Download configtool-2.11-setup.exe (2.65Mb)

Run the installer provided. A new eCos Configuration Tool group will be added to your Start menu and a shortcut to the Configuration Tool will appear on your desktop.

Running the Configuration Tool

Run the configtool executable. You can invoke the tool with zero, one, or two parameters. The two parameters can be the location of the repository and/or the location of a save file (extension .ecc). The tool will use the last loaded repository or ask the user for a suitable location.

For detailed information about the Configuration Tool, please refer to the HTML manual which may be invoked from the Help menu or by clicking on the "Linux Configuration Tool Guide" in the internal help system's contents. This is similar to but different from "The eCos Configuration Tool" section in the eCos User Guide, which refers to the original Windows version of the configuration tool (as opposed to the new cross-platform Linux and Windows version).

Getting `arm-elf` tools

As this is a complex procedure, you need to follow the directions here for Linux (or here for Windows) exactly. Once you have done this, you will have all the required tools needed to build for an arm-elf target (note this does not include the thumb target).

Note that the link to Insight 5.0 is broken. However, I have downloaded and installed Insight 5.2.1 (insight-5.2.1.tar.bz2) instead and see that it has some worthwhile bugfixes from 5.0.

Building eCos environment for PID target

Set the repository

Assuming you have checked out the latest version to a directory called ecos-cvs, you need to set the following environment variable for the Configuration Tool to pick up where all the source is (known as the repository, not to be confused with the CVS repository):

$ ECOS_REPOSITORY=/home/user/ecos-cvs/ecos/packages; export ECOS_REPOSITORY

This line should also be added to your shell initialisation script (.bashrc, or .bash_profile)

Create the `ecos.ecc` file

Create a new directory in your home directory and change to it:

$ mkdir -p ~/ecos-targets/pid-current

$ cd ~/ecos-targets/pid-current

Run the configtool

Enter the following

$ configtool

You should see the Configuration Tool start.

Create default settings for the PID target

Select the Build->Templates... menu item. In the Hardware combo box, select ARM development board (PID), and press 'OK'.

Change the following options:

eCos HAL->ROM Monitor support->Work with a ROM Monitor to disabled (unchecked)

eCos HAL->Platform-independent HAL options->Route diagnostic output to debug channel to disabled (unchecked)

Now save the file as ecos.ecc using the File->Save as... menu item

Build the tree

To build the tree for the PID development board, select the Build->Generate Build Tree menu item. You will see three directories: ecos_build, ecos_install and ecos_mlt

Make the libraries

$ cd ecos_build

$ make

This will place all the required files for an application in ecos_install.

Create the 'two threads' example

$ cd ../ecos_install

$ mkdir examples

$ cd examples

Get the two threads source code from here. Copy it into a file called twothreads.c.

Build this as follows

$ arm-elf-gcc -g -I../include twothreads.c -L../lib -o twothreads.x -Ttarget.ld -nostdlib

There should be no errors. You now have the executable (twothreads.x) which you can download, debug and run on the SID target using Insight, or gdb.

Installing SID

Getting SID source

The following contains extracts from Redhat's SID page.

Type the following command to login to the CVS server:

$ cvs -z 9 -d :pserver:anoncvs@sources.redhat.com:/cvs/src login

You will be prompted for a password which is anoncvs. You only need to perform this login the first time you access the SID CVS repository. The password is saved in the file .cvspass in your home directory for use in subsequent sessions.

It is recommended that you use different directory trees for the anonymous CVS sources and for full releases of SID. Create a new directory for the check out and change to that directory:

$ mkdir ~/sid-cvs

$ cd ~/sid-cvs

Now type:

$ cvs -z 9 -d :pserver:anoncvs@sources.redhat.com:/cvs/src co sid

This command should initiate a connection to the CVS server and check out the latest version of SID. It may take quite a while.

If you are unable to use CVS, automated CVS snapshots are available here; obtain the latest one of these and unzip it into the sid-cvs directory.

Building SID

Having checked out the source, you should see a single src subdirectory in the sid-cvs directory. Create a build directory alongside this:

$ mkdir build

$ cd build

Login as superuser and run configure to produce the build tree. I am assuming here that /opt/sid is the required destination directory for all files:

$ su

# ../src/configure --prefix=/opt/sid --exec-prefix=/opt/sid 2>&1 | tee configure.out

Now make all the files and install them:

# cd ~/sid-cvs/build

# make all install

Note that this may take a very long time (hours).

Add the executable directory to the path:

$ export PATH=/opt/sid/bin:$PATH

This line should also be added to your shell initialisation script (.bashrc, or .bash_profile)

Running a sample session

Change back to where the twothreads executable is:

$ cd ~/ecos-targets/pid-current/ecos_install/examples

Run SID with the following options:

$ arm-elf-sid --board=pid7t-normalmap --gdb=2000 -EL --tksm &

What this actually does is run a script file called arm-elf-sid. This in turn runs a more complex Perl script called configrun-sid, which builds the complex configuration file needed for SID on the fly, and then runs it.

The --board=pid7t option is a configrun-sid option which specifies that the configuration file for the PID7T target should be constructed. The additional -normalmap option ensures that the remapping operations done at startup by eCos do not affect the board.
The --gdb=2000 option is also a configrun-sid option which specifies that the configuration file should also include a stub to allow GDB connection to the PID7T target via TCP/IP using port 2000.
The -EL option specifies little-endian mode
The --tksm option is also a configrun-sid option which specifies that the configuration file should also include an experimental GUI interface which can show the 'innards' of the target. This is needed to see the output from the UART.
& simply runs it as a background task.

Select the experimental GUI window titled 'System Monitor' and left-click and hold on 'uart1' in the left hand column. Select 'GUIs' and then 'tk tty'. You should see an empty window called 'hw-uart-ns16550 uart1' come up.

Run GDB (I am assuming you are using Insight):

$ arm-elf-gdb twothreads.x

Connect to the target by selecting the Run->Connect to target menu item. Initially, you will get a dialog box; select the following options in the combo boxes on the left hand side:

Target	Remote/TCP
Hostname	localhost
Port	2000

Enable (check) the Set breakpoint at checkbox, and enter 'cyg_user_start' in the edit box to the right.

Disable (uncheck) the Display download Dialog checkbox.

Click on OK. You should see a dialog saying 'Successfully connected'; press OK on this dialog to dismiss it. Note that on Insight 5.2.1 these settings are remembered on further connections to the target.

Download the code to the target by selecting the Run->Download menu item.You should see a blue bar in the status bar showing the download progress.

Run the code by selecting the Run->Run menu item. You should see the code run up to the breakpoint specified at 'cyg_user_start'.

Continue the execution by selecting the Control->Continue menu item. You will see it hit another breakpoint at the end of 'main', and another at 'exit'; ignore these and continue the execution further by selecting the Control->Continue menu item in each case.

Select the 'hw-uart-ns16550 uart1' window. You should already see the following text:

Entering twothreads' cyg_user_start() function Beginning execution, thread data is 0 Beginning execution, thread data is 1

Wait patiently. After a while, you should see something like the following:

Thread 0: and now a delay of 239 clock ticks Thread 1: and now a delay of 230 clock ticks

You are now running a fully multi-thread application using eCos running on a simulated real target board (i.e. one which actually exists in real life).

Finishing the sample session

To finish, simply exit GDB as usual, and kill SID by typing:

$ killall -9 sid

Running SID without GDB

If you want to run SID without using GDB, you can run it with the following options:

$ arm-elf-sid --board=pid7t-normalmap-uart1:tty -EL twothreads.x

This will open a separate window for UART 1 output, i.e. printf() etc. You should already see the following text: