URL
https://opencores.org/ocsvn/or1k/or1k/trunk
Subversion Repositories or1k
[/] [or1k/] [trunk/] [ecos-2.0/] [doc/] [html/] [ref/] [synth-running.html] - Rev 1765
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Running a Synthetic Target Application</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="eCos Synthetic Target"
HREF="hal-synth-arch.html"><LINK
REL="PREVIOUS"
TITLE="Installation"
HREF="synth-install.html"><LINK
REL="NEXT"
TITLE="The I/O Auxiliary's User Interface"
HREF="synth-gui.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="synth-install.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="synth-gui.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SYNTH-RUNNING">Running a Synthetic Target Application</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN17751"
></A
><H2
>Name</H2
>Execution -- Arguments and configuration files</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-RUNNING-DESCRIPTION"
></A
><H2
>Description</H2
><P
>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,
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>$ ecos_hello <options></PRE
></TD
></TR
></TABLE
><P
>or using gdb:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>$ gdb --nw --quiet --args ecos_hello <options>
(gdb) run
Starting program: ecos_hello <options></PRE
></TD
></TR
></TABLE
><P
>By default use of the I/O auxiliary is disabled. If its I/O facilities
are required then the option <TT
CLASS="OPTION"
>--io</TT
> must be used.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>In future the default behaviour may change, with the I/O auxiliary
being started by default. The option <TT
CLASS="OPTION"
>--nio</TT
> can be
used to prevent the auxiliary from being run.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-RUNNING-ARGUMENTS"
></A
><H2
>Command-line Arguments</H2
><P
>The syntax for running a synthetic target application is:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>$ <ecos_app> [options] [-- [app_options]]</PRE
></TD
></TR
></TABLE
><P
>Command line options up to the <TT
CLASS="OPTION"
>--</TT
> 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
<TT
CLASS="VARNAME"
>cyg_hal_sys_argc</TT
> and
<TT
CLASS="VARNAME"
>cyg_hal_sys_argv</TT
>.
</P
><P
>The following options are accepted as standard:
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="OPTION"
>--io</TT
></DT
><DD
><P
>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.
</P
></DD
><DT
><TT
CLASS="OPTION"
>--nio</TT
></DT
><DD
><P
>This option prevents the eCos application from spawning the I/O
auxiliary. In the current version of the software this is the default.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-nw</TT
>, <TT
CLASS="OPTION"
>--no-windows</TT
></DT
><DD
><P
>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 <TT
CLASS="OPTION"
>-nw</TT
>.
Emulation of some devices, for example buttons connected to digital
inputs, requires the graphical interface.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-w</TT
>, <TT
CLASS="OPTION"
>--windows</TT
></DT
><DD
><P
>The <TT
CLASS="OPTION"
>-w</TT
> causes the I/O auxiliary to provide a
graphical user interface. This is the default.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-v</TT
>, <TT
CLASS="OPTION"
>--version</TT
></DT
><DD
><P
>The <TT
CLASS="OPTION"
>-v</TT
> 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.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-h</TT
>, <TT
CLASS="OPTION"
>--help</TT
></DT
><DD
><P
><TT
CLASS="OPTION"
>-h</TT
> 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
<TT
CLASS="OPTION"
>-nw</TT
>.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-k</TT
>, <TT
CLASS="OPTION"
>--keep-going</TT
></DT
><DD
><P
>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 <TT
CLASS="OPTION"
>-k</TT
>
option can be used to make the auxiliary continue in spite of errors,
although obviously it may not be fully functional.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-nr</TT
>, <TT
CLASS="OPTION"
>--no-rc</TT
></DT
><DD
><P
>Normally the auxiliary processes two <A
HREF="synth-running.html#SYNTH-RUNNING-USER-CONFIG"
>user configuration files</A
>
during startup: <TT
CLASS="FILENAME"
>initrc.tcl</TT
> and
<TT
CLASS="FILENAME"
>mainrc.tcl</TT
>. This can be suppressed using the
<TT
CLASS="OPTION"
>-nr</TT
> option.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-x</TT
>, <TT
CLASS="OPTION"
>--exit</TT
></DT
><DD
><P
>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 <TT
CLASS="OPTION"
>-x</TT
> then
the auxiliary will exit as soon the application exits.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-nx</TT
>, <TT
CLASS="OPTION"
>--no-exit</TT
></DT
><DD
><P
>When the graphical user interface is disabled with
<TT
CLASS="OPTION"
>-nw</TT
> 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
<TT
CLASS="OPTION"
>-nx</TT
> option causes the auxiliary to continue running
even after the application has exited.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-V</TT
>, <TT
CLASS="OPTION"
>--verbose</TT
></DT
><DD
><P
>This option causes the I/O auxiliary to output some additional
information, especially during initialization.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-l <file></TT
>, <TT
CLASS="OPTION"
>--logfile <file></TT
></DT
><DD
><P
>Much of the output of the eCos application and the I/O auxiliary is
simple text, for example resulting from eCos
<TT
CLASS="FUNCTION"
>printf</TT
> or <TT
CLASS="FUNCTION"
>diag_printf</TT
> 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
<TT
CLASS="OPTION"
>-l</TT
> 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 <TT
CLASS="OPTION"
>-l</TT
> 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.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-t <file></TT
>, <TT
CLASS="OPTION"
>--target <file></TT
></DT
><DD
><P
>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 <TT
CLASS="OPTION"
>-t</TT
>
option can be used to specify which target definition should be used
for the current run, defaulting to <TT
CLASS="FILENAME"
>default.tdf</TT
>.
It is not necessary to include the <TT
CLASS="FILENAME"
>.tdf</TT
> suffix,
this will be appended automatically if necessary.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-geometry <geometry></TT
></DT
><DD
><P
>This option can be used to control the size and position of the main
window, as per X conventions.
</P
></DD
></DL
></DIV
><P
>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 <TT
CLASS="OPTION"
>-h</TT
> option or by
consulting the device-specific documentation. If an unrecognised
command line argument is used then a warning will be issued.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-RUNNING-TDF"
></A
><H2
>The Target Definition File</H2
><P
>The eCos application will want to access devices such as
<TT
CLASS="VARNAME"
>eth0</TT
> or <TT
CLASS="VARNAME"
>/dev/ser0</TT
>. These need to
be mapped on to Linux devices. For example some users may all traffic
on the eCos <TT
CLASS="VARNAME"
>/dev/ser0</TT
> serial device to go via the
Linux serial device <TT
CLASS="VARNAME"
>/dev/ttyS1</TT
>, while ethernet I/O
for the eCos <TT
CLASS="VARNAME"
>eth0</TT
> device should be mapped to the
Linux ethertap device <TT
CLASS="VARNAME"
>tap3</TT
>. 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.
</P
><P
>By default the I/O auxiliary will look for a file
<TT
CLASS="FILENAME"
>default.tdf</TT
>. An alternative target definition can
be specified on the command line using <TT
CLASS="OPTION"
>-t</TT
>, for
example:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>$ bridge_app --io -t twineth</PRE
></TD
></TR
></TABLE
><P
>A <TT
CLASS="FILENAME"
>.tdf</TT
> 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 <TT
CLASS="FILENAME"
>~/.ecos/synth/</TT
>, and finally
in its install location.
</P
><P
>A typical target definition file might look like this:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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
}</PRE
></TD
></TR
></TABLE
><P
>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 <A
HREF="synth-new-host.html#SYNTH-NEW-HOST-ARGS"
>command line arguments</A
>. 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 <TT
CLASS="LITERAL"
>tap4</TT
> to
<TT
CLASS="LITERAL"
>eth2</TT
>.
</P
><P
>Each type of device will have its own entry in the target definition
file, taking the form:
</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>synth_device <device type> {
<options>
}</PRE
></TD
></TR
></TABLE
><P
>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.
</P
><P
>A good example of this is filters, which control the appearance of
text output. The above target definition file defines a filter
<TT
CLASS="VARNAME"
>trace</TT
> for output from the eCos application. The
regular expression will match output from the infrastructure package's
tracing facilities when <TT
CLASS="VARNAME"
>CYGDBG_USE_TRACING</TT
> and
<TT
CLASS="VARNAME"
>CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE</TT
> are enabled.
With the current settings this output will not be visible by default,
but can be made visible using the menu item <SPAN
CLASS="GUIMENUITEM"
>System
Filters</SPAN
>. 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:
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="OPTION"
>-hide [0|1]</TT
></DT
><DD
><P
>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 <SPAN
CLASS="GUIMENUITEM"
>System Filters</SPAN
>
menu item.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-foreground <colour></TT
></DT
><DD
><P
>This specifies the foreground colour for all text matching this
filter. The colour can be specified using an RGB value such as
<TT
CLASS="LITERAL"
>#F08010</TT
>, or a symbolic name such as
<TT
CLASS="LITERAL"
>"light steel blue"</TT
>. The X11 utility
<SPAN
CLASS="APPLICATION"
>showrgb</SPAN
> can be used to find out
about the available colours.
</P
></DD
><DT
><TT
CLASS="OPTION"
>-background <colour></TT
></DT
><DD
><P
>This specifies the background colour for all text matching the filter.
As with <TT
CLASS="OPTION"
>-foreground</TT
> the colour can be specified using
a symbolic name or an RGB value.
</P
></DD
></DL
></DIV
><P
>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 <A
HREF="synth-gui.html#SYNTH-GUI-LAYOUT"
>layout</A
> of
these windows.
</P
><P
>The I/O auxiliary will not normally warn about
<B
CLASS="COMMAND"
>synth_device</B
> 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
<TT
CLASS="OPTION"
>-V</TT
> command line option can be used to get warnings
about unused device entries in the target definition file.
</P
><P
>If the body of a <B
CLASS="COMMAND"
>synth_device</B
> command contains an
unrecognised option and the relevant device is in use, the I/O
auxiliary will always issue a warning about such options.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-RUNNING-USER-CONFIG"
></A
><H2
>User Configuration Files</H2
><P
>During initialization the I/O auxiliary will execute two user
configuration files, <TT
CLASS="FILENAME"
>initrc.tcl</TT
> and
<TT
CLASS="FILENAME"
>mainrc.tcl</TT
>. It will look for these files in the
directory <TT
CLASS="FILENAME"
>~/.ecos/synth/</TT
>. If
that directory does not yet exist it will be created and populated
with initial dummy files.
</P
><P
>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 <A
HREF="synth-new-host.html"
>Writing New Devices - host</A
> 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.
</P
><P
>The <TT
CLASS="FILENAME"
>initrc.tcl</TT
> 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
<TT
CLASS="FILENAME"
>initrc.tcl</TT
> script could add some menu or toolbar
options, or install a hook function that will be run when the
eCos application exits.
</P
><P
>The <TT
CLASS="FILENAME"
>mainrc.tcl</TT
> script is run after eCos has
performed all its device initialization and after C++ static
constructors have run, and just before the call to
<TT
CLASS="FUNCTION"
>cyg_start</TT
> which will end up transferring control
to the application itself. A typical <TT
CLASS="FILENAME"
>mainrc.tcl</TT
>
script could look at what interrupt vectors have been allocated to
which devices and create a little monitor window that shows interrupt
activity.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-RUNNING-SESSION"
></A
><H2
>Session Information</H2
><P
>When running in graphical mode, the I/O auxiliary will read in a file
<TT
CLASS="FILENAME"
>~/.ecos/synth/guisession</TT
> 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.
</P
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Warning</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>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.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="synth-install.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="synth-gui.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Installation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="hal-synth-arch.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>The I/O Auxiliary's User Interface</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>