Running a Synthetic Target Application

Name

Execution -- Arguments and configuration files

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.

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

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:

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

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

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.

Warning

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.