Subversion Repositories openrisc

    Overview

    The eCos synthetic target

    Overview

Usually eCos runs on either a custom piece of hardware, specially

designed to meet the needs of a specific application, or on a

development board of some sort that is available before the final

hardware. Such boards have a number of things in common:

Obviously there has to be at least one processor to do the work. Often

this will be a 32-bit processor, but it can be smaller or larger.

Processor speed will vary widely, depending on the expected needs of

the application. However the exact processor being used tends not to

matter very much for most of the development process: the use of

languages such as C or C++ means that the compiler will handle those

details.

There needs to be memory for code and for data. A typical system will

have two different types of memory. There will be some non-volatile

memory such as flash, EPROM or masked ROM. There will also be some

volatile memory such as DRAM or SRAM. Often the code for the final

application will reside in the non-volatile memory and all of the RAM

will be available for data. However updating non-volatile memory

requires a non-trivial amount of effort, so for much of the

development process it is more convenient to burn suitable firmware,

for example RedBoot, into the non-volatile memory and then use that to

load the application being debugged into RAM, alongside the

application data and a small area reserved for use by the firmware.

The platform must provide certain mimimal I/O facilities. Most eCos

configurations require a clock signal of some sort. There must also be

some way of outputting diagnostics to the user, often but not always

via a serial port. Unless special debug hardware is being used, source

level debugging will require bidirectional communication between a

host machine and the target hardware, usually via a serial port or an

ethernet device.

All the above is not actually very useful yet because there is no way

for the embedded device to interact with the rest of the world, except

by generating diagnostics. Therefore an embedded device will have

additional I/O hardware. This may be fairly standard hardware such as

an ethernet or USB interface, or special hardware designed

specifically for the intended application, or quite often some

combination. Standard hardware such as ethernet or USB may be

supported by eCos device drivers and protocol stacks, whereas the

special hardware will be driven directly by application code.

Much of the above can be emulated on a typical PC running Linux.

Instead of running the embedded application being developed on a

target board of some sort, it can be run as a Linux process. The

processor will be the PC's own processor, for example an x86, and the

memory will be the process' address space. Some I/O facilities can be

emulated directly through system calls. For example clock hardware can

be emulated by setting up a SIGALRM signal, which

will cause the process to be interrupted at regular intervals. This

emulation of real hardware will not be particularly accurate, the

number of cpu cycles available to the eCos application between clock

ticks will vary widely depending on what else is running on the PC,

but for much development work it will be good enough.

Other I/O facilities are provided through an I/O auxiliary process,

ecosynth, that gets spawned by the eCos application during startup.

When an eCos device driver wants to perform some I/O operation, for

example send out an ethernet packet, it sends a request to the I/O

auxiliary. That is an ordinary Linux application so it has ready

access to all normal Linux I/O facilities. To emulate a device

interrupt the I/O auxiliary can raise a SIGIO

signal within the eCos application. The HAL's interrupt subsystem

installs a signal handler for this, which will then invoke the

standard eCos ISR/DSR mechanisms. The I/O auxiliary is based around

Tcl scripting, making it easy to extend and customize. It should be

possible to configure the synthetic target so that its I/O

functionality is similar to what will be available on the final target

hardware for the application being developed.

A key requirement for synthetic target code is that the embedded

application must not be linked with any of the standard Linux

libraries such as the GNU C library: that would lead to a confusing

situation where both eCos and the Linux libraries attempted to provide

functions such as printf. Instead the synthetic

target support must be implemented directly on top of the Linux

kernels' system call interface. For example, the kernel provides a

system call for write operations. The actual function

write is implemented in the system's C library,

but all it does is move its arguments on to the stack or into certain

registers and then execute a special trap instruction such as

int 0x80. When this instruction is executed

control transfers into the kernel, which will validate the arguments

and perform the appropriate operation. Now, a synthetic target

application cannot be linked with the system's C library. Instead it

contains a function cyg_hal_sys_write which, like

the C library's write function, pushes its

arguments on to the stack and executes the trap instruction. The Linux

kernel cannot tell the difference, so it will perform the I/O

operation requested by the synthetic target. With appropriate

knowledge of what system calls are available, this makes it possible

to emulate the required I/O facilities. For example, spawning the

ecosynth I/O auxiliary involves system calls

cyg_hal_sys_fork and

cyg_hal_sys_execve, and sending a request to the

auxiliary uses cyg_hal_sys_write.

In many ways developing for the synthetic target is no different from

developing for real embedded targets. eCos must be configured

appropriately: selecting a suitable target such as

i386linux will cause the configuration system

to load the appropriate packages for this hardware; this includes an

architectural HAL package and a platform-specific package; the

architectural package contains generic code applicable to all Linux

platforms, whereas the platform package is for specific Linux

implementations such as the x86 version and contains any

processor-specific code. Selecting this target will also bring in some

device driver packages. Other aspects of the configuration such as

which API's are supported are determined by the template, by adding

and removing packages, and by fine-grained configuration.

In other ways developing for the synthetic target can be much easier

than developing for a real embedded target. For example there is no

need to worry about building and installing suitable firmware on the

target hardware, and then downloading and debugging the actual

application over a serial line or a similar connection. Instead an

eCos application built for the synthetic target is mostly

indistinguishable from an ordinary Linux program. It can be run simply

by typing the name of the executable file at a shell prompt.

Alternatively you can debug the application using whichever version of

gdb is provided by your Linux distribution. There is no need to build

or install special toolchains. Essentially using the synthetic target

means that the various problems associated with real embedded hardware

can be bypassed for much of the development process.

The eCos synthetic target provides emulation, not simulation. It is

possible to run eCos in suitable architectural simulators but that

involves a rather different approach to software development. For

example, when running eCos on the psim PowerPC simulator you need

appropriate cross-compilation tools that allow you to build PowerPC

executables. These are then loaded into the simulator which interprets

every instruction and attempts to simulate what would happen if the

application were running on real hardware. This involves a lot of

processing overhead, but depending on the functionality provided by

the simulator it can give very accurate results. When developing for

the synthetic target the executable is compiled for the PC's own

processor and will be executed at full speed, with no need for a

simulator or special tools. This will be much faster and somewhat

simpler than using an architectural simulator, but no attempt is made

to accurately match the behaviour of a real embedded target.

    Installation

    Installation

    Preparing to use the synthetic target

To get the full functionality of the synthetic target, users must

build and install the I/O auxiliary ecosynth and various support

files. It is possible to develop applications for the synthetic target

without the auxiliary, but only limited I/O facilities will be

available. The relevant code resides in the 

class="directory">host subdirectory of the synthetic target

architectural HAL package, and building it involves the standard

configure, make, and

make install steps.

There are two main ways of building the host-side software. It is

possible to build both the generic host-side software and all

package-specific host-side software, including the I/O auxiliary. in a

single build tree. This involves using the

configure script at the toplevel of the eCos

repository, which will automatically search the 

class="directory">packages hierarchy for host-side

software. For more information on this, see the

README.host file at the top of the repository.

Note that if you have an existing build tree which does not include

the synthetic target architectural HAL package then it will be

necessary to rerun the toplevel configure script: the search for

appropriate packages happens at configure time.

The alternative is to build just the host-side for this package.

This involves creating a suitable build directory and running the

configure script. Note that building directly in

the source tree is not allowed.

$ cd <somewhere suitable>

$ mkdir synth_build

$ cd synth_build

$ <repo<>/packages/hal/synth/arch/<version>/host/configure <options>

$ make

$ make install

The code makes extensive use of Tcl/TK and requires version 8.3 or

later. This is checked by the configure script. By

default it will use the system's Tcl installation in 

class="directory">/usr. If a different, more recent Tcl

installation should be used then its location can be specified using

the options --with-tcl=<path>,

--with-tcl-header=<path> and

--with-tcl-lib=<path>. For more information on these options

see the README.host file at the toplevel of the

eCos repository.

Some users may also want to specify the install location using a

--prefix=<path> option. The default install

location is /usr/local. It is

essential that the bin

subdirectory of the install location is on the user's search

PATH, otherwise the eCos application will be unable to

locate and execute the I/O auxiliary ecosynth.

Because ecosynth is run automatically by an eCos application rather

than explicitly by the user, it is not installed in the 

class="directory">bin subdirectory itself. Instead it is

installed below libexec,

together with various support files such as images. At configure time

it is usually possible to specify an alternative location for

libexec using

--exec-prefix=<path> or

--libexecdir=<path>. These options should not

be used for this package because the eCos application is built

completely separately and does not know how the host-side was

configured.

When developing eCos applications for a normal embedded target it is

necessary to use a suitable cross-compiler and related tools such as

the linker. Developing for the synthetic target is easier because you

can just use the standard GNU tools (gcc, g++, ld, …) which

were provided with your Linux distribution, or which you used to build

your own Linux setup. Any reasonably recent version of the tools, for

example gcc 2.96(Red Hat) as shipped with Red Hat Linux 7, should be

sufficient.

There is one important limitation when using these tools: current gdb

will not support debugging of eCos threads on the synthetic target. As

far as gdb is concerned a synthetic target application is

indistinguishable from a normal Linux application, so it assumes that

any threads will be created by calls to the Linux

pthread_create function provided by the C

library. Obviously this is not the case since the application is never

linked with that library. Therefore gdb never notices the eCos thread

mechanisms and assumes the application is single-threaded. Fixing this

is possible but would involve non-trivial changes to gdb.

Theoretically it is possible to develop synthetic target applications

on, for example, a PC running Windows and then run the resulting

executables on another machine that runs Linux. This is rarely useful:

if a Linux machine is available then usually that machine will also be

used for building ecos and the application. However, if for some

reason it is necessary or desirable to build on another machine then

this requires a suitable cross-compiler and related tools. If the

application will be running on a typical PC with an x86 processor then

a suitable configure triplet would be

i686-pc-linux-gnu. The installation

instructions for the various GNU tools should be consulted for further

information.

Preparing a real embedded target for eCos development can be tricky.

Often the first step is to install suitable firmware, usually RedBoot.

This means creating and building a special configuration for eCos with

the RedBoot template, then somehow updating the target's flash chips

with the resulting RedBoot image. Typically it will also be necessary

to get a working serial connection, and possibly set up ethernet as

well. Although usually none of the individual steps are particularly

complicated, there are plenty of ways in which things can go wrong and

it can be hard to figure out what is actually happening. Of course

some board manufacturers make life easier for their developers by

shipping hardware with RedBoot preinstalled, but even then it is still

necessary to set up communication between host and target.

None of this is applicable to the synthetic target. Instead you can

just build a normal eCos configuration, link your application with the

resulting libraries, and you end up with an executable that you can

run directly on your Linux machine or via gdb. A useful side effect of

this is that application development can start before any real

embedded hardware is actually available.

Typically the memory map for a synthetic target application will be

set up such that there is a read-only ROM region containing all the

code and constant data, and a read-write RAM region for the data. The

default locations and sizes of these regions depend on the specific

platform being used for development. Note that the application always

executes out of ROM: on a real embedded target much of the development

would involve running RedBoot firmware there, with application code

and data loaded into RAM; usually this would change for the final

system; the firmware would be replaced by the eCos application itself,

configured for ROM bootstrap, and it would perform the appropriate

hardware initialization. Therefore the synthetic target actually

emulates the behaviour of a final system, not of a development

environment. In practice this is rarely significant, although having

the code in read-only memory can help catch some problems in

application code.

    Running a Synthetic Target Application

    Execution

    Arguments and configuration files

The procedure for configuring and building eCos and an application for

the synthetic target is the same as for any other eCos target. Once an

executable has been built it can be run like any Linux program, for

example from a shell prompt,

$ ecos_hello <options>

or using gdb:

$ gdb --nw --quiet --args ecos_hello <options>

(gdb) run

Starting program: ecos_hello <options>

By default use of the I/O auxiliary is disabled. If its I/O facilities

are required then the option --io must be used.

In future the default behaviour may change, with the I/O auxiliary

being started by default. The option --nio can be

used to prevent the auxiliary from being run.

The syntax for running a synthetic target application is:

$ <ecos_app> [options] [-- [app_options]]

Command line options up to the -- are passed on to

the I/O auxiliary. Subsequent arguments are not passed on to the

auxiliary, and hence can be used by the eCos application itself. The

full set of arguments can be accessed through the variables

cyg_hal_sys_argc and

cyg_hal_sys_argv.

The following options are accepted as standard:

        --io

This option causes the eCos application to spawn the I/O auxiliary

during HAL initialization. Without this option only limited I/O will

be available.

        --nio

This option prevents the eCos application from spawning the I/O

auxiliary. In the current version of the software this is the default.

        -nw, --no-windows

The I/O auxiliary can either provide a graphical user interface, or it

can run in a text-only mode. The default is to provide the graphical

interface, but this can be disabled with -nw.

Emulation of some devices, for example buttons connected to digital

inputs, requires the graphical interface.

        -w, --windows

The -w causes the I/O auxiliary to provide a

graphical user interface. This is the default.

        -v, --version

The -v option can be used to determine the version of

the I/O auxiliary being used and where it has been installed. Both the

auxiliary and the eCos application will exit immediately.

        -h, --help

-h causes the I/O auxiliary to list all accepted

command-line arguments. This happens after all devices have been

initialized, since the host-side support for some of the devices may

extend the list of recognised options. After this both the auxiliary

and the eCos application will exit immediately. This option implies

-nw.

        -k, --keep-going

If an error occurs in the I/O auxiliary while reading in any of the

configuration files or initializing devices, by default both the

auxiliary and the eCos application will exit. The -k

option can be used to make the auxiliary continue in spite of errors,

although obviously it may not be fully functional.

        -nr, --no-rc

Normally the auxiliary processes two 

linkend="synth-running-user-config">user configuration files

during startup: initrc.tcl and

mainrc.tcl. This can be suppressed using the

-nr option.

        -x, --exit

When providing a graphical user interface the I/O auxiliary will

normally continue running even after the eCos application has exited.

This allows the user to take actions such as saving the current

contents of the main text window. If run with -x then

the auxiliary will exit as soon the application exits.

        -nx, --no-exit

When the graphical user interface is disabled with

-nw the I/O auxiliary will normally exit immediately

when the eCos application exits. Without the graphical frontend there

is usually no way for the user to interact directly with the

auxiliary, so there is no point in continuing to run once the eCos

application will no longer request any I/O operations. Specifying the

-nx option causes the auxiliary to continue running

even after the application has exited.

        -V, --verbose

This option causes the I/O auxiliary to output some additional

information, especially during initialization.

        -l <file>, --logfile <file>

Much of the output of the eCos application and the I/O auxiliary is

simple text, for example resulting from eCos

printf or diag_printf calls.

When running in graphical mode this output goes to a central text

window, and can be saved to a file or edited via menus. The

-l can be used to automatically generate an

additional logfile containing all the text. If graphical

mode is disabled then by default all the text just goes to the current

standard output. Specifying -l causes most of the

text to go into a logfile instead, although some messages such as

errors generated by the auxiliary itself will still go to stdout as

well.

        -t <file>, --target <file>

During initialization the I/O auxiliary reads in a target definition

file. This file holds information such as which Linux devices should

be used to emulate the various eCos devices. The -t

option can be used to specify which target definition should be used

for the current run, defaulting to default.tdf.

It is not necessary to include the .tdf suffix,

this will be appended automatically if necessary.

        -geometry <geometry>

This option can be used to control the size and position of the main

window, as per X conventions.

The I/O auxiliary loads support for the various devices dynamically

and some devices may accept additional command line arguments. Details

of these can be obtained using the -h option or by

consulting the device-specific documentation. If an unrecognised

command line argument is used then a warning will be issued.

The eCos application will want to access devices such as

eth0 or /dev/ser0. These need to

be mapped on to Linux devices. For example some users may all traffic

on the eCos /dev/ser0 serial device to go via the

Linux serial device /dev/ttyS1, while ethernet I/O

for the eCos eth0 device should be mapped to the

Linux ethertap device tap3. Some devices may need

additional configuration information, for example to limit the

number of packets that should be buffered within the I/O auxiliary.

The target definition file provides all this information.

By default the I/O auxiliary will look for a file

default.tdf. An alternative target definition can

be specified on the command line using -t, for

example:

$ bridge_app --io -t twineth

A .tdf suffix will be appended automatically if

necessary. If a relative pathname is used then the I/O auxiliary will

search for the target definition file in the current directory, then

in ~/.ecos/synth/, and finally

in its install location.

A typical target definition file might look like this:

synth_device console {

    # appearance -foreground white -background black

    filter trace {^TRACE:.*} -foreground HotPink1 -hide 1

}

synth_device ethernet {

    eth0 real eth1

    eth1 ethertap tap4 00:01:02:03:FE:06

    ## Maximum number of packets that should be buffered per interface.

    ## Default 16

    #max_buffer 32

    ## Filters for the various recognised protocols.

    ## By default all filters are visible and use standard colours.

    filter ether  -hide 0

    #filter arp    -hide 1

    #filter ipv4   -hide 1

    #filter ipv6   -hide 1

}

A target definition file is actually a Tcl script that gets run in the

main interpreter of the I/O auxiliary during initialization. This

provides a lot of flexibility if necessary. For example the script

could open a socket to a resource management server of some sort to

determine which hardware facilities are already in use and adapt

accordingly. Another possibility is to adapt based on 

linkend="synth-new-host-args">command line arguments. Users who

are not familiar with Tcl programming should still be able to edit a

simple target definition file without too much difficulty, using a

mixture of cut'n'paste, commenting or uncommenting various lines, and

making small edits such as changing tap4 to

eth2.

Each type of device will have its own entry in the target definition

file, taking the form:

synth_device <device type> {

    <options>

}

The documentaton for each synthetic target device should provide

details of the options available for that device, and often a suitable

fragment that can be pasted into a target definition file and edited.

There is no specific set of options that a given device will always

provide. However in practice many devices will use common code

exported by the main I/O auxiliary, or their implementation will

involve some re-use of code for an existing device. Hence certain

types of option are common to many devices.

A good example of this is filters, which control the appearance of

text output. The above target definition file defines a filter

trace for output from the eCos application. The

regular expression will match output from the infrastructure package's

tracing facilities when CYGDBG_USE_TRACING and

CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE are enabled.

With the current settings this output will not be visible by default,

but can be made visible using the menu item System

Filters. If made visible the trace output will appear in

an unusual colour, so users can easily distinguish the trace output

from other text. All filters accept the following options:

         -hide [0|1]

This controls whether or not text matching this filter should be

invisible by default or not. At run-time the visibility of each filter

can be controlled using the System Filters

menu item.

         -foreground <colour>

This specifies the foreground colour for all text matching this

filter. The colour can be specified using an RGB value such as

#F08010, or a symbolic name such as

"light steel blue". The X11 utility

showrgb can be used to find out

about the available colours.

         -background <colour>

This specifies the background colour for all text matching the filter.

As with -foreground the colour can be specified using

a symbolic name or an RGB value.

Some devices may create their own subwindows, for example to monitor

ethernet traffic or to provide additional I/O facilities such as

emulated LED's or buttons. Usually the target definition file can be

used to control the layout of

these windows.

The I/O auxiliary will not normally warn about

synth_device entries in the target definition file

for devices that are not actually needed by the current eCos

application. This makes it easier to use a single file for several

different applications. However it can lead to confusion if an entry

is spelled incorrectly and hence does not actually get used. The

-V command line option can be used to get warnings

about unused device entries in the target definition file.

If the body of a synth_device command contains an

unrecognised option and the relevant device is in use, the I/O

auxiliary will always issue a warning about such options.

During initialization the I/O auxiliary will execute two user

configuration files, initrc.tcl and

mainrc.tcl. It will look for these files in the

directory ~/.ecos/synth/. If

that directory does not yet exist it will be created and populated

with initial dummy files.

Both of these configuration files are Tcl scripts and will be run in

the main interpreter used by the I/O auxiliary itself. This means that

they have full access to the internals of the auxiliary including the

various Tk widgets, and they can perform file or socket I/O if

desired. The section  contains

information about the facilities available on the host-side for

writing new device drivers, and these can also be used in the

initialization scripts.

The initrc.tcl script is run before the auxiliary

has processed any requests from the eCos application, and hence before

any devices have been instantiated. At this point the generic

command-line arguments has been processed, the target definition file

has been read in, and the hooks functionality has been initialized. If

running in graphical mode the main window will have been created, but

has been withdrawn from the screen to allow new widgets to be added

without annoying screen flicker. A typical

initrc.tcl script could add some menu or toolbar

options, or install a hook function that will be run when the

eCos application exits.

The mainrc.tcl script is run after eCos has

performed all its device initialization and after C++ static

constructors have run, and just before the call to

cyg_start which will end up transferring control

to the application itself. A typical mainrc.tcl

script could look at what interrupt vectors have been allocated to

which devices and create a little monitor window that shows interrupt

activity.

When running in graphical mode, the I/O auxiliary will read in a file

~/.ecos/synth/guisession containing session

information. This file should not normally be edited manually, instead

it gets updated automatically when the auxiliary exits. The purpose of

this file is to hold configuration options that are manipulated via

the graphical interface, for example which browser should be used to

display online help.

GUI session functionality is not yet available in the current release.

When that functionality is fully implemented it is possible that some

target definition file options may be removed, to be replaced by

graphical editing via a suitable preferences dialog, with the

current settings saved in the session file.

    The I/O Auxiliary's User Interface

    User Interface

    Controlling the I/O Auxiliary

The synthetic target auxiliary is designed to support both extensions

and user customization. Support for the desired devices is dynamically

loaded, and each device can extend the user interface. For example it

is possible for a device to add menu options, place new buttons on the

toolbar, create its own sub-window within the overall layout, or even

create entire new toplevel windows. These subwindows or toplevels

could show graphs of activity such as interrupts or packets being

transferred. They could also allow users to interact with the eCos

application, for example by showing a number of buttons which will be

mapped on to digital inputs in the eCos application. Different

applications will have their own I/O requirements, changing the

host-side support files that get loaded and that may modify the user

interface. The I/O auxiliary also reads in user configuration scripts

which can enhance the interface in the same way. Therefore the exact

user interface will depend on the user and on the eCos application

being run. However the overall layout is likely to remain the same.

The title bar identifies the window as belonging to an eCos synthetic

target application and lists both the application name and its process

id. The latter is especially useful if the application was started

directly from a shell prompt and the user now wants to attach a gdb

session. The window has a conventional menu bar with the usual

entries, plus a toolbar with buttons for common operations such as cut

and paste. Balloon help is supported.

There is a central text window,

possibly surrounded by various sub-windows for various devices. For

example there could be a row of emulated LED's above the text window,

and monitors of ethernet traffic and interrupt activity on the right.

At the bottom of the window is a status line, including a small

animation that shows whether or not the eCos application is still

running.

Usually there will be four menus on the menu bar:

File, Edit,

View and Help.

On the File menu there are three entries related to

saving the current contents of the central text window.