1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Running a Synthetic Target Application</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos Synthetic Target"
23 HREF="hal-synth-arch.html"><LINK
26 HREF="synth-install.html"><LINK
28 TITLE="The I/O Auxiliary's User Interface"
29 HREF="synth-gui.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="synth-install.html"
82 NAME="SYNTH-RUNNING">Running a Synthetic Target Application</H1
90 >Execution -- Arguments and configuration files</DIV
94 NAME="SYNTH-RUNNING-DESCRIPTION"
99 >The procedure for configuring and building eCos and an application for
100 the synthetic target is the same as for any other eCos target. Once an
101 executable has been built it can be run like any Linux program, for
102 example from a shell prompt,
112 >$ ecos_hello <options></PRE
127 >$ gdb --nw --quiet --args ecos_hello <options>
129 Starting program: ecos_hello <options></PRE
134 >By default use of the I/O auxiliary is disabled. If its I/O facilities
135 are required then the option <TT
147 >In future the default behaviour may change, with the I/O auxiliary
148 being started by default. The option <TT
152 used to prevent the auxiliary from being run.
160 NAME="SYNTH-RUNNING-ARGUMENTS"
163 >Command-line Arguments</H2
165 >The syntax for running a synthetic target application is:
175 >$ <ecos_app> [options] [-- [app_options]]</PRE
180 >Command line options up to the <TT
184 the I/O auxiliary. Subsequent arguments are not passed on to the
185 auxiliary, and hence can be used by the eCos application itself. The
186 full set of arguments can be accessed through the variables
189 >cyg_hal_sys_argc</TT
193 >cyg_hal_sys_argv</TT
197 >The following options are accepted as standard:
211 >This option causes the eCos application to spawn the I/O auxiliary
212 during HAL initialization. Without this option only limited I/O will
223 >This option prevents the eCos application from spawning the I/O
224 auxiliary. In the current version of the software this is the default.
237 >The I/O auxiliary can either provide a graphical user interface, or it
238 can run in a text-only mode. The default is to provide the graphical
239 interface, but this can be disabled with <TT
243 Emulation of some devices, for example buttons connected to digital
244 inputs, requires the graphical interface.
260 > causes the I/O auxiliary to provide a
261 graphical user interface. This is the default.
277 > option can be used to determine the version of
278 the I/O auxiliary being used and where it has been installed. Both the
279 auxiliary and the eCos application will exit immediately.
295 > causes the I/O auxiliary to list all accepted
296 command-line arguments. This happens after all devices have been
297 initialized, since the host-side support for some of the devices may
298 extend the list of recognised options. After this both the auxiliary
299 and the eCos application will exit immediately. This option implies
316 >If an error occurs in the I/O auxiliary while reading in any of the
317 configuration files or initializing devices, by default both the
318 auxiliary and the eCos application will exit. The <TT
322 option can be used to make the auxiliary continue in spite of errors,
323 although obviously it may not be fully functional.
336 >Normally the auxiliary processes two <A
337 HREF="synth-running.html#SYNTH-RUNNING-USER-CONFIG"
338 >user configuration files</A
347 >. This can be suppressed using the
364 >When providing a graphical user interface the I/O auxiliary will
365 normally continue running even after the eCos application has exited.
366 This allows the user to take actions such as saving the current
367 contents of the main text window. If run with <TT
371 the auxiliary will exit as soon the application exits.
384 >When the graphical user interface is disabled with
388 > the I/O auxiliary will normally exit immediately
389 when the eCos application exits. Without the graphical frontend there
390 is usually no way for the user to interact directly with the
391 auxiliary, so there is no point in continuing to run once the eCos
392 application will no longer request any I/O operations. Specifying the
396 > option causes the auxiliary to continue running
397 even after the application has exited.
410 >This option causes the I/O auxiliary to output some additional
411 information, especially during initialization.
420 >--logfile <file></TT
424 >Much of the output of the eCos application and the I/O auxiliary is
425 simple text, for example resulting from eCos
433 When running in graphical mode this output goes to a central text
434 window, and can be saved to a file or edited via menus. The
438 > can be used to automatically generate an
439 additional logfile containing all the text. If graphical
440 mode is disabled then by default all the text just goes to the current
441 standard output. Specifying <TT
445 text to go into a logfile instead, although some messages such as
446 errors generated by the auxiliary itself will still go to stdout as
456 >--target <file></TT
460 >During initialization the I/O auxiliary reads in a target definition
461 file. This file holds information such as which Linux devices should
462 be used to emulate the various eCos devices. The <TT
466 option can be used to specify which target definition should be used
467 for the current run, defaulting to <TT
471 It is not necessary to include the <TT
475 this will be appended automatically if necessary.
481 >-geometry <geometry></TT
485 >This option can be used to control the size and position of the main
486 window, as per X conventions.
492 >The I/O auxiliary loads support for the various devices dynamically
493 and some devices may accept additional command line arguments. Details
494 of these can be obtained using the <TT
498 consulting the device-specific documentation. If an unrecognised
499 command line argument is used then a warning will be issued.
505 NAME="SYNTH-RUNNING-TDF"
508 >The Target Definition File</H2
510 >The eCos application will want to access devices such as
518 be mapped on to Linux devices. For example some users may all traffic
522 > serial device to go via the
523 Linux serial device <TT
526 >, while ethernet I/O
530 > device should be mapped to the
531 Linux ethertap device <TT
534 >. Some devices may need
535 additional configuration information, for example to limit the
536 number of packets that should be buffered within the I/O auxiliary.
537 The target definition file provides all this information.
540 >By default the I/O auxiliary will look for a file
544 >. An alternative target definition can
545 be specified on the command line using <TT
559 >$ bridge_app --io -t twineth</PRE
567 > suffix will be appended automatically if
568 necessary. If a relative pathname is used then the I/O auxiliary will
569 search for the target definition file in the current directory, then
574 in its install location.
577 >A typical target definition file might look like this:
586 CLASS="PROGRAMLISTING"
587 >synth_device console {
588 # appearance -foreground white -background black
589 filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
592 synth_device ethernet {
594 eth1 ethertap tap4 00:01:02:03:FE:06
596 ## Maximum number of packets that should be buffered per interface.
600 ## Filters for the various recognised protocols.
601 ## By default all filters are visible and use standard colours.
611 >A target definition file is actually a Tcl script that gets run in the
612 main interpreter of the I/O auxiliary during initialization. This
613 provides a lot of flexibility if necessary. For example the script
614 could open a socket to a resource management server of some sort to
615 determine which hardware facilities are already in use and adapt
616 accordingly. Another possibility is to adapt based on <A
617 HREF="synth-new-host.html#SYNTH-NEW-HOST-ARGS"
618 >command line arguments</A
620 are not familiar with Tcl programming should still be able to edit a
621 simple target definition file without too much difficulty, using a
622 mixture of cut'n'paste, commenting or uncommenting various lines, and
623 making small edits such as changing <TT
633 >Each type of device will have its own entry in the target definition
634 file, taking the form:
643 CLASS="PROGRAMLISTING"
644 >synth_device <device type> {
651 >The documentaton for each synthetic target device should provide
652 details of the options available for that device, and often a suitable
653 fragment that can be pasted into a target definition file and edited.
654 There is no specific set of options that a given device will always
655 provide. However in practice many devices will use common code
656 exported by the main I/O auxiliary, or their implementation will
657 involve some re-use of code for an existing device. Hence certain
658 types of option are common to many devices.
661 >A good example of this is filters, which control the appearance of
662 text output. The above target definition file defines a filter
666 > for output from the eCos application. The
667 regular expression will match output from the infrastructure package's
668 tracing facilities when <TT
670 >CYGDBG_USE_TRACING</TT
674 >CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE</TT
676 With the current settings this output will not be visible by default,
677 but can be made visible using the menu item <SPAN
681 >. If made visible the trace output will appear in
682 an unusual colour, so users can easily distinguish the trace output
683 from other text. All filters accept the following options:
697 >This controls whether or not text matching this filter should be
698 invisible by default or not. At run-time the visibility of each filter
699 can be controlled using the <SPAN
701 >System Filters</SPAN
709 >-foreground <colour></TT
713 >This specifies the foreground colour for all text matching this
714 filter. The colour can be specified using an RGB value such as
718 >, or a symbolic name such as
721 >"light steel blue"</TT
726 > can be used to find out
727 about the available colours.
733 >-background <colour></TT
737 >This specifies the background colour for all text matching the filter.
741 > the colour can be specified using
742 a symbolic name or an RGB value.
748 >Some devices may create their own subwindows, for example to monitor
749 ethernet traffic or to provide additional I/O facilities such as
750 emulated LED's or buttons. Usually the target definition file can be
751 used to control the <A
752 HREF="synth-gui.html#SYNTH-GUI-LAYOUT"
758 >The I/O auxiliary will not normally warn about
762 > entries in the target definition file
763 for devices that are not actually needed by the current eCos
764 application. This makes it easier to use a single file for several
765 different applications. However it can lead to confusion if an entry
766 is spelled incorrectly and hence does not actually get used. The
770 > command line option can be used to get warnings
771 about unused device entries in the target definition file.
777 > command contains an
778 unrecognised option and the relevant device is in use, the I/O
779 auxiliary will always issue a warning about such options.
785 NAME="SYNTH-RUNNING-USER-CONFIG"
788 >User Configuration Files</H2
790 >During initialization the I/O auxiliary will execute two user
791 configuration files, <TT
798 >. It will look for these files in the
803 that directory does not yet exist it will be created and populated
804 with initial dummy files.
807 >Both of these configuration files are Tcl scripts and will be run in
808 the main interpreter used by the I/O auxiliary itself. This means that
809 they have full access to the internals of the auxiliary including the
810 various Tk widgets, and they can perform file or socket I/O if
811 desired. The section <A
812 HREF="synth-new-host.html"
813 >Writing New Devices - host</A
815 information about the facilities available on the host-side for
816 writing new device drivers, and these can also be used in the
817 initialization scripts.
823 > script is run before the auxiliary
824 has processed any requests from the eCos application, and hence before
825 any devices have been instantiated. At this point the generic
826 command-line arguments has been processed, the target definition file
827 has been read in, and the hooks functionality has been initialized. If
828 running in graphical mode the main window will have been created, but
829 has been withdrawn from the screen to allow new widgets to be added
830 without annoying screen flicker. A typical
834 > script could add some menu or toolbar
835 options, or install a hook function that will be run when the
836 eCos application exits.
842 > script is run after eCos has
843 performed all its device initialization and after C++ static
844 constructors have run, and just before the call to
848 > which will end up transferring control
849 to the application itself. A typical <TT
853 script could look at what interrupt vectors have been allocated to
854 which devices and create a little monitor window that shows interrupt
861 NAME="SYNTH-RUNNING-SESSION"
864 >Session Information</H2
866 >When running in graphical mode, the I/O auxiliary will read in a file
869 >~/.ecos/synth/guisession</TT
871 information. This file should not normally be edited manually, instead
872 it gets updated automatically when the auxiliary exits. The purpose of
873 this file is to hold configuration options that are manipulated via
874 the graphical interface, for example which browser should be used to
896 >GUI session functionality is not yet available in the current release.
897 When that functionality is fully implemented it is possible that some
898 target definition file options may be removed, to be replaced by
899 graphical editing via a suitable preferences dialog, with the
900 current settings saved in the session file.
912 SUMMARY="Footer navigation table"
923 HREF="synth-install.html"
941 HREF="synth-gui.html"
957 HREF="hal-synth-arch.html"
965 >The I/O Auxiliary's User Interface</TD