Running a Synthetic Target Application

Description

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.

Command-line Arguments

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:

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 Target Definition File

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 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:

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.

User Configuration Files

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 Writing New Devices - host 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.

Session Information

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.