Subversion Repositories openrisc_2011-10-31

The following chapters of this manual comprise a simple tutorial

for configuring and building eCos, building and running eCos tests,

and finally building three stand-alone example programs which use

the  eCos API to perform some simple tasks.

You will need a properly installed eCos system, with the correct

versions of the GNU toolchain. On Windows

you will be using the bash command line interpreter that comes with

Cygwin, with the environment variables set as described in the

toolchain documentation.

Most development projects using eCos would contain some (or

most) of  the following:

eCos is configured to provide the desired API (the inclusion

of libc, uitron, and the disabling of certain undesired funtions,

etc.), and semantics (selecting scheduler, mutex behavior, etc.).

See .

It would normally make sense to enable eCos assertion checking

at this time as well, to catch as many programming errors during

the development phase as possible.

Note that it should not be necessary to spend much time on

eCos configuration initially. It may be important to perform fine

tuning to reduce the memory footprint and to improve performance

later when the product reaches a testable state.

While we strive to thoroughly test eCos, the vast number

of configuration permutations mean that the particular configuration

parameters used for your project may not have been tested. Therefore,

we advise running the eCos tests after the project's

eCos configuration has been determined. See .

Obviously, this should be repeated if the configuration changes

later on in the development process.

While your project is probably targeting a specific architecture

and platform, possibly custom hardware, it may be possible to perform

part of the application development using simulated or synthetic

targets.

There are three good reasons for doing this:

It may be possible by this means to perform application

development in parallel with the design/implementation

of the target hardware, thus providing more time for developing

and testing functionality, and reducing time-to-market.

The build-run-debug-cycle may be faster when the application

does not have to be downloaded to a target via a serial interface.

Debugging is also likely to be more responsive when you do not have to

to communicate with the remote GDB stubs in RedBoot via serial. It

also removes the need for manually or automatically resetting the

target hardware.

New hardware can often be buggy. Comparing the behaviour of the

program on the hardware and in the simulator or synthetic target may

allow you to identify where the problems lie.

This approach is possible because all targets (including

simulators and synthetic ones) provide the same basic API: that

is, kernel, libc, libm, uitron, infra, and to some extent, HAL and

IO.

Synthetic targets are especially suitable as they allow you

to construct simulations of elaborate devices by interaction with

the host system, where an IO device API can hide the details from

the application. When switching to hardware later in the development

cycle, the IO driver is properly implemented.

Simulators can also do this, but it all depends on the

design and capabilities of the simulator you use. Some, like

SID or

Bochs provide

complete hardware emulation, while others just support enough of the

instruction set to run compiled code.

Therefore, select a simulator or synthetic target and use

it for as long as possible for application development. That is,

configure for the selected target, build eCos, build the application

and link with eCos, run and debug. Repeat the latter two steps until

you are happy with it.

Obviously, at some time you will have to switch to the intended

target hardware, for example when adding target specific feature

support, for memory footprint/performance characterization,

and for final tuning of eCos and the application.

Repeat the build-run-debug-cycle while performing final tuning

and debugging of application. Remember to disable eCos assertion

checking if you are testing any performance-related aspects, it can

make a big difference.

It may be useful to switch between this and the previous step

repeatedly through the development process; use the simulator/synthetic

target for actual development, and use the target hardware to continually

check memory footprint and performance. There should be little cost

in switching between the two targets when using two separate build

trees. 

This chapter documents the configuration of eCos. The process is

the same for any of the supported targets: you may select a

hardware target (if you have a board available), any one of the

simulators, or a synthetic target (if your host platform has synthetic

target support).

There are various ways to download an executable image to a

target board, and these involve different ways of preparing the

executable image. In the eCos Hardware Abstraction Layer (HAL package)

there are configuration options to support the different download

methods.  summarizes the

ways in which an eCos image can be prepared for different types of

download. This is not an exhaustive list, some targets define

additional start-up types of their own. Where a ROM Monitor is

mentioned, this will usually be RedBoot, although on some older, or

low resource, targets you may need to use CygMon or the GDB stubs ROM,

see the target documentation for details.

      
      

         
209
         

         

         

      
      

         
210
         

         

         

      
      

         
211
         

         

         

      
      

         
212
         

         

         

      
      

         
213
         

         

         
Download method
      
      

         
214
         

         

         
HAL configuration
      
      

         
215
         

         

         

      
      

         
216
         

         

         

      
      

         
217
         

         

         

      
      

         
218
         

         

         

      
      

         
219
         

         

         
Burn hardware ROM
      
      

         
220
         

         

         
 ROM or ROMRAM start-up
      
      

         
221
         

         

         

      
      

         
222
         

         

         

      
      

         
223
         

         

         
Download to ROM emulator
      
      

         
224
         

         

         
 ROM or ROMRAM start-up
      
      

         
225
         

         

         

      
      

         
226
         

         

         

      
      

         
227
         

         

         
Download to board with ROM Monitor
      
      

         
228
         

         

         
 RAM start-up
      
      

         
229
         

         

         

      
      

         
230
         

         

         

      
      

         
231
         

         

         
Download to simulator without ROM Monitor
      
      

         
232
         

         

         
 ROM start-up
      
      

         
233
         

         

         

      
      

         
234
         

         

         

      
      

         
235
         

         

         
Download to simulator with ROM Monitor
      
      

         
236
         

         

         
 RAM start-up
      
      

         
237
         

         

         

      
      

         
238
         

         

         

      
      

         
239
         

         

         
Download to simulator ignoring devices
      
      

         
240
         

         

         
 SIM configuration
      
      

         
241
         

         

         

      
      

         
242
         

         

         

      
      

         
243
         

         

         
Run synthetic target
      
      

         
244
         

         

         
 RAM start-up
      
      

         
245
         

         

         

      
      

         
246
         

         

         

      
      

         
247
         

         

         

      
      

         
248
         

         

         

You cannot run an application configured for RAM start-up

on the simulator directly: it will fail during start-up. You can

only download it to the simulator if

you are already running RedBoot in the simulator,

as described in the toolchain documentation

or you load through the

SID 

GDB debugging component.  This is not the same as the simulated

stub, since it does not require a target program to be running to

get GDB to talk to it.  It can be done before letting the simulator

run

or you use the ELF loader component to get a program into memory.

Configuring eCos' HAL package for simulation should

rarely be needed for real development; binaries built with such

a kernel will not run on target boards at all,

and the MN10300 and

TX39 simulators can run binaries built for stdeval1 and jmr3904

target boards.

The main use for a ``simulation'' configuration

is if you are trying to work around problems with the device drivers

or with the simulator.  Also note that when using a TX39 system configured

for simulator start-up you should then invoke the simulator with

the --board=jmr3904pal

option instead of

--board=jmr3904

If your chosen architecture does not have simulator support,

then the combinations above that refer to the simulator do not apply.

Similarly, if your chosen platform does not have RedBoot

ROM support, the combinations listed above that use

RedBoot do not apply.

The debugging environment for most developers will be either

a hardware board or the simulator, in which case they will be able

to select a single HAL configuration.

Note that the use of the Configuration Tool

is described in detail in 

LINKEND="THE-ECOS-CONFIGURATION-TOOL">.

The Configuration Tool (see )

has five main elements: the configuration window,

the conflicts window,

the properties window, the short

description window,

and the output window.

Start by opening the templates window via Build->Templates.

Select the desired target (see ).

Make sure that the configuration is correct for the target

in terms of endianness, CPU model, Startup type, etc. (see ).

Next, select the Build->Library menu

item to start building eCos (see 

LINKEND="FIGURE-SELECTING-THE-BUILD-LIBRARY-MENU-ITEM">).  The

application will configure the sources, prepare a build tree, and

build the libtarget.a library, which contains the

eCos kernel and other packages.

The Save As dialog box will appear, asking

you to specify a directory in which to place your save file. You

can use the default, but it is a good idea to make a subdirectory,

called ecos-work for example. 

The first time you build an eCos library for a specific

architecture, the Configuration Tool may prompt

you for the location of the appropriate build tools (including

make and

TARGET-gcc) using a

Build Tools dialog box (as shown in 

LINKEND="FIGURE-BUILD-TOOLS-DIALOG">). You can select a location from

the drop down list, browse to the directory using the

Browse button, or type in the location of the

build tools manually.

The Configuration Tool may also prompt you

for the location of the user tools (such as cat and

ls) using a User Tools dialog

box (as shown in ). As with

the Build Tools dialog, you can select a location

from the drop down list, browse to the directory using the

Browse button, or type in the location of the

user tools manually. Note that on Linux, this will often be

unnecessary as the tools will already be on your PATH.

When the tool locations have been entered, the Configuration

Tool will configure the sources, prepare a build tree,

and build the libtarget.a library, which contains

the eCos kernel and other packages.

The output from the configuration process and the building

of libtarget.a will be shown in the output

window.

Once the build process has finished you will have a kernel

with other packages in libtarget.a. You should

now build the eCos tests for your particular configuration. 

You can do this by selecting Build -> Tests.

Notice that you could have selected Tests instead

of Library in the earlier step and it would

have built both the library and the tests,

but this would increase the build time substantially, and if you

do not need to build the tests it is unnecessary.

 will guide you through running one

            of the test cases you just built on the selected target,

            using GDB. 

As an alternative to using the graphical

Configuration Tool, it is still possible to

configure and build a kernel by editing a configuration file manually

and using the ecosconfig command. 

Manual configuration and the ecosconfig command are

described in detail in .

To use the ecosconfig command you need to start a

shell. In Windows you need to start a

CygWin bash shell, not a

DOS command line.

The following instructions assume that the

PATH and ECOS_REPOSITORY

environment variables have been setup correctly as described in 

LINKEND="user-guide-installation-linux">.  They also assume Linux

usage but equally well apply to Windows running Cygwin.

Before invoking ecosconfig you need to

choose a directory in which to work. For the purposes of this tutorial,

the default path will be BASE_DIR/ecos-work.

Create this directory and change to it by typing: 

$ mkdir BASE_DIR/ecos-work

$ cd BASE_DIR/ecos-work

To see what options can be used with ecosconfig,

type: 

$ ecosconfig --help

The available packages, targets and templates may be listed

as follows:

$ ecosconfig list

Here is sample output from ecosconfig showing

the usage message.

$ ecosconfig --help

Usage: ecosconfig [ qualifier ... ] [ command ]

  commands are:

    list                                       : list repository contents

    new TARGET [ TEMPLATE [ VERSION ] ]        : create a configuration

    target TARGET                              : change the target hardware

    template TEMPLATE [ VERSION ]              : change the template

    add PACKAGE [ PACKAGE ... ]                : add package(s)

    remove PACKAGE [ PACKAGE ... ]             : remove package(s)

    version VERSION PACKAGE [ PACKAGE ... ]    : change version of package(s)

    export FILE                                : export minimal config info

    import FILE                                : import additional config info

    check                                      : check the configuration

    resolve                                    : resolve conflicts

    tree                                       : create a build tree

  qualifiers are:

    --config=FILE                              : the configuration file

    --prefix=DIRECTORY                         : the install prefix

    --srcdir=DIRECTORY                         : the source repository

    --no-resolve                               : disable conflict

resolution

    --version                                  : show version and copyright

$

$ ecosconfig list

Package CYGPKG_CYGMON (CygMon support via eCos):

aliases: cygmon

versions: &Version;

Package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1742 (Wallclock driver for Dallas 1742):

aliases: devices_wallclock_ds1742 device_wallclock_ds1742

versions: &Version;

Package CYGPKG_DEVICES_WALLCLOCK_SH3 (Wallclock driver for SH3 RTC module):

aliases: devices_wallclock_sh3 device_wallclock_sh3

versions: &Version;

Package CYGPKG_DEVICES_WATCHDOG_ARM_AEB (Watchdog driver for ARM/AEB board):

aliases: devices_watchdog_aeb device_watchdog_aeb

versions: &Version;

Package CYGPKG_DEVICES_WATCHDOG_ARM_EBSA285 (Watchdog driver for ARM/EBSA285 board):

aliases: devices_watchdog_ebsa285 device_watchdog_ebsa285

versions: &Version;

…

To configure for a listed target, type: 

$ ecosconfig new <target>

For example, to configure for the ARM PID development board,

type: 

$ ecosconfig new pid

You can then edit the generated file,

ecos.ecc, setting the options as required for the

target (endianess, CPU model, Startup type, etc.).  For detailed

information about how to edit the ecos.ecc file,

see the CDL Writer's Guide and 

LINKEND="editing-an-ecos-savefile">.

Create a build tree for the configured target by typing:

$ ecosconfig tree

If there are any problem with the configuration,

ecosconfig will tell you. The most likely cause of

this is mistakes when editing the ecos.ecc file.

You can check whether the configuration you have made is correct,

without building the tree with the following command:

$ ecosconfig check

If this reports any conflicts you can get

ecosconfig to try and resolve them itself by typing:

$ ecosconfig resolve

See  for more details.

You can now run the command make or make

tests, after which you will be at the same point you

would be after running the Configuration Tool

— you can start developing your own applications,

following the steps in . 

The procedure shown above allows you to do very coarse-grained

configuration of the eCos kernel: you can select which packages

to include in your kernel, and give target and start-up options.

But you cannot select components within a package, or set the very

fine-grained options. 

To select fine-grained configuration options you will need to

edit the configuration file ecos.ecc in the

current directory and regenerate the build tree.

You should follow the manual configuration process described

above very carefully, and you should read the comments in each file

to see when one option depends on other options or packages being

enabled or disabled. If you do not, you might end up with an inconsistently

configured kernel which could fail to build or might execute

incorrectly.

In  or 

LINKEND="using-ecosconfig-on-linux"> you created the eCos test cases

as part of the build process. Now it is time to try and run one.

Test executables that have been linked using the

Build->Tests operation against the current

configuration can be executed by selecting Tools->Run

Tests.

When a test run is invoked, a property sheet is displayed, see

. Press the Uncheck

All button and then find and check just one test,

bin_sem0 for example.

Now press the Properties button to set up

communications with the target. This will bring up a properties dialog

shown in . If you have

connected the target board via a serial cable, check the

Serial radio button, and select the serial port

and baud rate for the board. If the target is connected via the

network select the TCP/IP button and enter the IP

address that the board has been given, and the port number (usually

9000).

Click OK on this dialog and go back to the Run

Tests dialog. Press the Run button and

the selected test will be downloaded and run. The

Output tab will show you how this is

progressing. If it seems to stop for a long time, check that the

target board is correctly connected, and that eCos has been correctly

configured -- especially the start-up type.

When the program runs you should see a couple of line similar to this appear:

PASS:<Binary Semaphore 0 OK>

EXIT:<done>

This indicates that the test has run successfully.

See  for

further details.

Start a command shell (such as a Cygwin shell window in Windows)

with the environment variables set as described in the toolchain

documentation.  Change to the directory in which you set up your build

tree, and invoke  GDB on the test

program.

To run the bin_sem0 test (which will

test the kernel for the correct creation and destruction of binary

semaphores) type: 

$ TARGET-gdb -nw install/tests/kernel/&Version;/tests/bin_sem0

You should see output similar to the following in the command

window:

GNU gdb THIS-GDB-VERSION

Copyright 2001 Free Software Foundation, Inc.

GDB is free software, covered by the GNU General Public License, and you are

welcome to change it and/or distribute copies of it under certain conditions.

Type "show copying" to see the conditions.

There is absolutely no warranty for GDB.  Type "show warranty" for details.

This GDB was configured as "--host=THIS-HOST --target=THIS-TARGET".

(gdb)

If you are trying to run a synthetic target test on Linux, skip the following connection and download

steps. Otherwise, connect to the target by typing: 

(gdb) set remotebaud 38400

(gdb) target remote /dev/ttyS0

on Linux or

(gdb) set remotebaud 38400

(gdb) target remote com1

on Windows or

(gdb) target sim

to use a simulator in either host O/S.

Check the documentation for the target board for the actual baud rate

to use when connecting to real targets.

You will see output similar to the following: 

Remote debugging using /dev/ttyS1

0x0000d50c in ?? ()

    at BASE_DIR/kernel/&Version;/src/common/kapi.cxx:345

Current language:  auto; currently c++

(gdb)

Or if you are using the simulator:

Connected to the simulator.

(gdb)

Now download the program to the target with

(gdb) load

You should see output similar to the following on your screen: 

Loading section .text, size 0x4b04 lma 0x108000

Loading section .rodata, size 0x738 lma 0x10cb08

Loading section .data, size 0x1c0 lma 0x10d240

Start address 0x108000, load size 21500

Transfer rate: 24571 bits/sec, 311 bytes/write.

(gdb)

You are now ready to run your program. If you type: 

(gdb) continue

you will see output similar to the following: 

Continuing.

PASS:<Binary Semaphore 0 OK>

EXIT:<done>

 If you are using a simulator or the synthetic target rather

            than real hardware, you must use the GDB command

            “run” rather than “continue” to

            start your program.

You can terminate your GDB session with

Control+C, otherwise it will sit in the

“idle” thread and use up CPU time. This is not a problem

with real targets, but may have undesirable effects in simulated or

synthetic targets. Type quit and you are

done. 

While most test cases today run solely in the target environment,

some packages may require external testing infrastructure and/or

feedback from the external environment to do complete testing.

The serial package is an example of this. The network package

also contains some tests that require programs to be run on a

host. See the network Tests and Demonstrations

section in the network documentation in the eCos Reference

Guide. Here we will concentrate on the serial tests since

these are applicable to more targets.

Since the serial line is also used for communication with

GDB, a  filter is inserted in the communication pathway between

GDB and the serial device which is connected to the hardware target.

The filter forwards all communication between the two, but also

listens for special commands embedded in the data stream from the

target.

When such a command is seen, the filter stops forwarding data

to GDB from the target and enters a special mode. In this mode

the test case running on the target is able to control the filter,

commanding it to run various tests. While these tests run, GDB is

isolated from the target.

As the test completes (or if the filter detects a target crash)

the communication path between GDB and the hardware target is re-established,

allowing GDB to resume control.

In theory, it is possible to extend the filter to provide

a generic framework for other target-external testing components,

thus decoupling the testing infrastructure from the (possibly limited)

communication means provided by the target (serial, JTAG, Ethernet,

etc). 

Another advantage is that the host tools do not need to

know about the various testing environments required by the eCos

packages, since all contact with the target continues to happen

via GDB.

The example programs in this tutorial are included, along

with a Makefile, in the examples directory

of the eCos distribution. The first program you will run is a hello

world-style application, then you will run a more complex

application that demonstrates the creation of threads and the use

of cyg_thread_delay(), and finally you will run

one that uses clocks and alarm handlers.

The Makefile depends on an externally

defined variable to find the eCos library and header files. This

variable is INSTALL_DIR and must be set to the

pathname of the install directory created in 

linkend="using-configtool-windows-linux">.