synth-new-host.html

ecos 文档

><P
>Although it might seem more appropriate to use Tcl's
<B
CLASS="COMMAND"
>eval</B
> procedure and have the callback functions
invoked with the right number of arguments rather than a single list,
that would cause serious problems if any of the data contained special
characters such as <TT
CLASS="LITERAL"
>[</TT
> or <TT
CLASS="LITERAL"
>$</TT
>. The
current implementation of hooks avoids such problems, at the cost of
minor inconvenience when writing callbacks.
    </P
><P
>A number of hooks are defined as standard. Some devices will add
additional hooks, and the device-specific documentation should be
consulted for those. User scripts can add their own hooks if desired.
    </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>exit</TT
></DT
><DD
><P
>This hook is called just before the I/O auxiliary exits. Hence it
provides much the same functionality as <TT
CLASS="FUNCTION"
>atexit</TT
> in
C programs. The argument list passed to the callback function will be
empty. 
        </P
></DD
><DT
><TT
CLASS="LITERAL"
>ecos_exit</TT
></DT
><DD
><P
>This hook is called when the eCos application has exited. It is used
mainly to shut down I/O operations: if the application is no longer
running then there is no point in raising interrupts or storing
incoming packets. The callback argument list will be empty.
        </P
></DD
><DT
><TT
CLASS="LITERAL"
>ecos_initialized</TT
></DT
><DD
><P
>The synthetic target HAL will send a request to the I/O auxiliary once
the static constructors have been run. All devices should now have been
instantiated. A script could now check how many instances there are of
a given type of device, for example ethernet devices, and create a
little monitor window showing traffic on all the devices. The
<TT
CLASS="LITERAL"
>ecos_initialized</TT
> callbacks will be run just before
the user's <TT
CLASS="FILENAME"
>mainrc.tcl</TT
> script. The callback
argument list will be empty.
        </P
></DD
><DT
><TT
CLASS="LITERAL"
>help</TT
></DT
><DD
><P
>This hook is also invoked once static constructors have been run, but
only if the user specified <TT
CLASS="OPTION"
>-h</TT
> or
<TT
CLASS="OPTION"
>--help</TT
>. Any scripts that add their own command line
arguments should add a callback to this hook which outputs details of
the additional arguments. The callback argument list will be empty.
        </P
></DD
><DT
><TT
CLASS="LITERAL"
>interrupt</TT
></DT
><DD
><P
>Whenever a device calls <B
CLASS="COMMAND"
>synth::interrupt_raise</B
> the
<TT
CLASS="LITERAL"
>interrupt</TT
> hook will be called with a single
argument, the interrupt vector. The main use for this is to allow
user scripts to monitor interrupt traffic.
        </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-NEW-HOST-OUTPUT"
></A
><H2
>Output and Filters</H2
><P
>Scripts can use conventional facilities for sending text output to the
user, for example calling <B
CLASS="COMMAND"
>puts</B
> or directly
manipulating the central text widget
<TT
CLASS="VARNAME"
>.main.centre.text</TT
>. However in nearly all cases it
is better to use output facilities provided by the I/O auxiliary
itself: 
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>synth::report &lt;msg&gt;
synth::report_warning &lt;msg&gt;
synth::report_error &lt;msg&gt;
synth::internal_error &lt;msg&gt;
synth::output &lt;msg&gt; &lt;filter&gt;</PRE
></TD
></TR
></TABLE
><P
><B
CLASS="COMMAND"
>synth::report</B
> is intended for messages related to
the operation of the I/O auxiliary itself, especially additional
output resulting from <TT
CLASS="OPTION"
>-v</TT
> or
<TT
CLASS="OPTION"
>--verbose</TT
>. If running in text mode the output will go
to standard output. If running in graphical mode the output will go to
the central text window. In both modes, use of <TT
CLASS="OPTION"
>-l</TT
> or
<TT
CLASS="OPTION"
>--logfile</TT
> will modify the behaviour.
    </P
><P
><B
CLASS="COMMAND"
>synth::report_warning</B
>,
<B
CLASS="COMMAND"
>synth::report_error</B
> and
<B
CLASS="COMMAND"
>synth::internal_error</B
> have the obvious meaning,
including prepending strings such as <TT
CLASS="LITERAL"
>Warning:</TT
> and
<TT
CLASS="LITERAL"
>Error:</TT
>. When the eCos application informs the I/O
auxiliary that all static constructors have run, if at that point
there have been any calls to <B
CLASS="COMMAND"
>synth::error</B
> then the
I/O auxiliary will exit. This can be suppressed with command line
arguments <TT
CLASS="OPTION"
>-k</TT
> or <TT
CLASS="OPTION"
>--keep-going</TT
>.
<B
CLASS="COMMAND"
>synth::internal_error</B
> will output some information
about the current state of the I/O auxiliary and then exit
immediately. Of course it should never be necessary to call this
function. 
    </P
><P
><B
CLASS="COMMAND"
>synth::output</B
> is the main routine for outputting
text. The second argument identifies a filter. If running in text mode
the filter is ignored, but if running in graphical mode the filter can
be used to control the appearance of this output. A typical use would
be:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    synth::output $line "console"</PRE
></TD
></TR
></TABLE
><P
>This outputs a single line of text using the
<TT
CLASS="LITERAL"
>console</TT
> filter. If running in graphical mode the
default appearance of this text can be modified with the
<TT
CLASS="OPTION"
>appearance</TT
> option in the
<B
CLASS="COMMAND"
>synth_device&nbsp;console</B
> entry of the target
definition file. The <SPAN
CLASS="GUIMENUITEM"
>System filters</SPAN
> menu
option can be used to change the appearance at run-time.
    </P
><P
>Filters should be created before they are used. The procedures
available for this are:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>synth::filter_exists &lt;name&gt;
synth::filter_get_list
synth::filter_add &lt;name&gt; [options]
synth::filter_parse_options &lt;options&gt; &lt;parsed_options&gt; &lt;message&gt;
synth::filter_add_parsed &lt;name&gt; &lt;parsed_options&gt;</PRE
></TD
></TR
></TABLE
><P
><B
CLASS="COMMAND"
>synth::filter_exists</B
> can be used to check whether
or not a particular filter already exists: creating two filters with
the same name is not allowed.
<B
CLASS="COMMAND"
>synth::filter_get_list</B
> returns a list of the
current known filters. <B
CLASS="COMMAND"
>synth::filter_add</B
> can be
used to create a new filter. The first argument names the new filter,
and the remaining arguments control the initial appearance. A typical
use might be:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    synth::filter_add "my_device_tx" -foreground yellow -hide 1</PRE
></TD
></TR
></TABLE
><P
>It is assumed that the supplied arguments are valid, which typically
means that they are hard-wired in the script. If instead the data
comes out of a configuration file and hence may be invalid, the
I/O auxiliary provides a parsing utility. Typical usage would be:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    array set parsed_options [list]
    set message ""
    if { ![synth::filter_parse_options $console_appearance parsed_options message] } {
        synth::report_error \
	        "Invalid entry in target definition file $synth::target_definition\
	         \n  synth_device \"console\", entry \"appearance\"\n$message"
    } else {
        synth::filter_add_parsed "console" parsed_options
    }</PRE
></TD
></TR
></TABLE
><P
>On success <TT
CLASS="VARNAME"
>parsed_options</TT
> will be updated with an
internal representation of the desired appearance, which can then be
used in a call to <B
CLASS="COMMAND"
>synth::filter_add_parsed</B
>. On
failure <TT
CLASS="VARNAME"
>message</TT
> will be updated with details of the
parsing error that occurred.
    </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="SYNTH-NEW-HOST-GUI"
></A
><H2
>The Graphical Interface</H2
><P
>When the I/O auxiliary is running in graphical mode, many scripts will
want to update the user interface in some way. This may be as simple
as adding another entry to the help menu for the device, or adding a
new button to the toolbar. It may also involve adding new subwindows,
or even creating entire new toplevel windows. These may be simple
monitor windows, displaying additional information about what is going
on in the system in a graphical format. Alternatively they may emulate
actual I/O operations, for example button widgets could be used to
emulate real physical buttons.
    </P
><P
>The I/O auxiliary does not provide many procedures related to the
graphical interface. Instead it is expected that scripts will just
update the widget hierarchy directly.
    </P
><DIV
CLASS="INFORMALFIGURE"
><A
NAME="AEN18682"><P
></P
><DIV
CLASS="MEDIAOBJECT"
><P
><IMG
SRC="layout.gif"
ALIGN="CENTER"></P
></DIV
><P
></P
></DIV
><P
>So adding a new item to the <SPAN
CLASS="GUIMENU"
>Help</SPAN
> menu involves a
<B
CLASS="COMMAND"
>.menubar.help&nbsp;add</B
> operation with suitable
arguments. Adding a new button to the toolbar involves creating a
child window in <TT
CLASS="VARNAME"
>.toolbar</TT
> and packing it
appropriately. Scripts can create their own subwindows and then pack
it into one of <TT
CLASS="VARNAME"
>.main.nw</TT
>,
<TT
CLASS="VARNAME"
>.main.n</TT
>, <TT
CLASS="VARNAME"
>.main.ne</TT
>,
<TT
CLASS="VARNAME"
>.main.w</TT
>, <TT
CLASS="VARNAME"
>.main.e</TT
>,
<TT
CLASS="VARNAME"
>.main.sw</TT
>, <TT
CLASS="VARNAME"
>.main.s</TT
> or
<TT
CLASS="VARNAME"
>.main.se</TT
>. Normally the user should be allowed to
<A
HREF="synth-gui.html#SYNTH-GUI-LAYOUT"
>control</A
> this via the target
definition file. The central window <TT
CLASS="VARNAME"
>.main.centre</TT
>
should normally be left alone by other scripts since it gets used for
text output.
    </P
><P
>The following graphics-related utilities may be found useful:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>synth::load_image &lt;image name&gt; &lt;filename&gt;
synth::register_ballon_help &lt;widget&gt; &lt;message&gt;
synth::handle_help &lt;URL&gt;</PRE
></TD
></TR
></TABLE
><P
><B
CLASS="COMMAND"
>synth::load_image</B
> can be used to add a new image to
the current interpreter. If the specified file has a
<TT
CLASS="FILENAME"
>.xbm</TT
> extension then the image will be a
monochrome bitmap, otherwise it will be a colour image of some sort.
A boolean will be returned to indicate success or failure, and
suitable diagnostics will be generated if necessary.
    </P
><P
><B
CLASS="COMMAND"
>synth::register_balloon_help</B
> provides balloon help
for a specific widget, usually a button on the toolbar.
    </P
><P
><B
CLASS="COMMAND"
>synth::handle_help</B
> is a utility routine that can be
installed as the command for displaying online help, for example:
    </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>    .menubar.help add command -label "my device" -command \
        [list synth::handle_help "file://$path"]</PRE
></TD
></TR
></TABLE
></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-new-target.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-porting.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Writing New Devices - target</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"
>Porting</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>