synth.sgml

eCos操作系统源码

It is not necessary to include the <filename>.tdf</filename> suffix,
this will be appended automatically if necessary.
         </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-geometry &lt;geometry&gt;</option></term>
         <listitem><para>
This option can be used to control the size and position of the main
window, as per X conventions.
         </para></listitem>
      </varlistentry>
    </variablelist>
    <para>
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 <option>-h</option> option or by
consulting the device-specific documentation. If an unrecognised
command line argument is used then a warning will be issued.
    </para>
  </refsect1>

  <refsect1 id="synth-running-tdf"><title>The Target Definition File</title>
    <para>
The eCos application will want to access devices such as
<varname>eth0</varname> or <varname>/dev/ser0</varname>. These need to
be mapped on to Linux devices. For example some users may all traffic
on the eCos <varname>/dev/ser0</varname> serial device to go via the
Linux serial device <varname>/dev/ttyS1</varname>, while ethernet I/O
for the eCos <varname>eth0</varname> device should be mapped to the
Linux ethertap device <varname>tap3</varname>. 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.
    </para>
    <para>
By default the I/O auxiliary will look for a file
<filename>default.tdf</filename>. An alternative target definition can
be specified on the command line using <option>-t</option>, for
example:
    </para>
    <screen>
$ bridge_app --io -t twineth
</screen>
    <para>
A <filename>.tdf</filename> 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 <filename class="directory">~/.ecos/synth/</filename>, and finally
in its install location.
    </para>
    <para>
A typical target definition file might look like this:
    </para>
    <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
}
</programlisting>
    <para>
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 <link
linkend="synth-new-host-args">command line arguments</link>. 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 <literal>tap4</literal> to
<literal>eth2</literal>. 
    </para>
    <para>
Each type of device will have its own entry in the target definition
file, taking the form:
    </para>
    <programlisting>
synth_device &lt;device type&gt; {
    &lt;options&gt;
}
</programlisting>
    <para>
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.
    </para>
    <para>
A good example of this is filters, which control the appearance of
text output. The above target definition file defines a filter
<varname>trace</varname> for output from the eCos application. The
regular expression will match output from the infrastructure package's
tracing facilities when <varname>CYGDBG_USE_TRACING</varname> and
<varname>CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE</varname> are enabled.
With the current settings this output will not be visible by default,
but can be made visible using the menu item <guimenuitem>System
Filters</guimenuitem>. 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:
    </para>
    <variablelist>
      <varlistentry>
         <term><option>-hide [0|1]</option></term>
         <listitem><para>
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 <guimenuitem>System Filters</guimenuitem>
menu item.
         </para></listitem>
      </varlistentry>
      <varlistentry>
         <term><option>-foreground &lt;colour&gt;</option></term>
         <listitem><para>
This specifies the foreground colour for all text matching this
filter. The colour can be specified using an RGB value such as
<literal>#F08010</literal>, or a symbolic name such as
<literal>"light steel blue"</literal>. The X11 utility
<application>showrgb</application> can be used to find out
about the available colours.
         </para></listitem>
      </varlistentry>
      <varlistentry>
         <term><option>-background &lt;colour&gt;</option></term>
         <listitem><para>
This specifies the background colour for all text matching the filter.
As with <option>-foreground</option> the colour can be specified using
a symbolic name or an RGB value.
         </para></listitem>
      </varlistentry>
    </variablelist>
    <para>
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 <link linkend="synth-gui-layout">layout</link> of
these windows.
    </para>
    <para>
The I/O auxiliary will not normally warn about
<command>synth_device</command> 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
<option>-V</option> command line option can be used to get warnings
about unused device entries in the target definition file.
    </para>
    <para>
If the body of a <command>synth_device</command> command contains an
unrecognised option and the relevant device is in use, the I/O
auxiliary will always issue a warning about such options.
    </para>
  </refsect1>

  <refsect1 id="synth-running-user-config"><title>User Configuration Files</title>
    <para>
During initialization the I/O auxiliary will execute two user
configuration files, <filename>initrc.tcl</filename> and
<filename>mainrc.tcl</filename>. It will look for these files in the
directory <filename class="directory">~/.ecos/synth/</filename>. If
that directory does not yet exist it will be created and populated
with initial dummy files.
    </para>
    <para>
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 <xref linkend="synth-new-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.
    </para>
    <para>
The <filename>initrc.tcl</filename> 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
<filename>initrc.tcl</filename> script could add some menu or toolbar
options, or install a hook function that will be run when the
eCos application exits.
    </para>
    <para>
The <filename>mainrc.tcl</filename> script is run after eCos has
performed all its device initialization and after C++ static
constructors have run, and just before the call to
<function>cyg_start</function> which will end up transferring control
to the application itself. A typical <filename>mainrc.tcl</filename>
script could look at what interrupt vectors have been allocated to
which devices and create a little monitor window that shows interrupt
activity. 
    </para>
  </refsect1>

  <refsect1 id="synth-running-session"><title>Session Information</title>
    <para>
When running in graphical mode, the I/O auxiliary will read in a file
<filename>~/.ecos/synth/guisession</filename> 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.
    </para>
    <warning><para>
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.
    </para></warning>
  </refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ ecosynth user interface        -->

<refentry id="synth-gui">
  <refmeta>
    <refentrytitle>The I/O Auxiliary's User Interface</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>User Interface</refname>
    <refpurpose>Controlling the I/O Auxiliary</refpurpose>
  </refnamediv>

  <refsect1 id="synth-gui-description"><title>Description</title>
    <para>
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.
    </para>
    <informalfigure PgWide=1>
      <mediaobject>
        <imageobject>
          <imagedata fileref="screen_main.png" Scalefit=1 Align="Center">
        </imageobject>
      </mediaobject>
    </informalfigure>
    <para>
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.
    </para>
    <para>
There is a central <link linkend="synth-gui-text">text window</link>,