URL
https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk
Subversion Repositories openrisc_2011-10-31
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [synth-gui.html] - Rev 575
Go to most recent revision | 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 >The I/O Auxiliary's User Interface</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="Running a Synthetic Target Application" HREF="synth-running.html"><LINK REL="NEXT" TITLE="The Console Device" HREF="synth-console.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-running.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="synth-console.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="SYNTH-GUI">The I/O Auxiliary's User Interface</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN17960" ></A ><H2 >Name</H2 >User Interface -- Controlling the I/O Auxiliary</DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-GUI-DESCRIPTION" ></A ><H2 >Description</H2 ><P >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. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN17966"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="screen_main.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >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. </P ><P >There is a central <A HREF="synth-gui.html#SYNTH-GUI-TEXT" >text window</A >, possibly surrounded by various sub-windows for various devices. For example there could be a row of emulated LED's above the text window, and monitors of ethernet traffic and interrupt activity on the right. At the bottom of the window is a status line, including a small animation that shows whether or not the eCos application is still running. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-GUI-MENUS" ></A ><H2 >Menus and the Toolbar</H2 ><P >Usually there will be four menus on the menu bar: <SPAN CLASS="GUIMENU" >File</SPAN >, <SPAN CLASS="GUIMENU" >Edit</SPAN >, <SPAN CLASS="GUIMENU" >View</SPAN > and <SPAN CLASS="GUIMENU" >Help</SPAN >. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN17980"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="menu_file.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >On the <SPAN CLASS="GUIMENU" >File</SPAN > menu there are three entries related to saving the current contents of the central text window. <SPAN CLASS="GUIMENUITEM" >Save</SPAN > is used to save the currently visible contents of the text window. Any text that is hidden because of filters will not be written to the savefile. If there has been a previous <SPAN CLASS="GUIMENUITEM" >Save</SPAN > or <SPAN CLASS="GUIMENUITEM" >Save As</SPAN > operation then the existing savefile will be re-used, otherwise the user will be asked to select a suitable file. <SPAN CLASS="GUIMENUITEM" >Save As</SPAN > also saves just the currently visible contents but will always prompt the user for a filename. <SPAN CLASS="GUIMENUITEM" >Save All</SPAN > can be used to save the full contents of the text window, including any text that is currently hidden. It will always prompt for a new filename, to avoid confusion with partial savefiles. </P ><P >Usually the eCos application will be run from inside gdb or from a shell prompt. Killing off the application while it is being debugged in a gdb session is not a good idea, it would be better to use gdb's own <B CLASS="COMMAND" >kill</B > command. Alternatively the eCos application itself can use the <TT CLASS="FUNCTION" >CYG_TEST_EXIT</TT > or <TT CLASS="FILENAME" >cyg_hal_sys_exit</TT > functionality. However it is possible to terminate the application from the I/O auxiliary using <SPAN CLASS="GUIMENUITEM" >Kill eCos</SPAN >. A clean shutdown will be attempted, but that can fail if the application is currently halted inside gdb or if it has crashed completely. As a last resort <TT CLASS="CONSTANT" >SIGKILL</TT > will be used. </P ><P >When operating in graphical mode the I/O auxiliary will normally continue to run even after the eCos application has exited. This allows the user to examine the last few lines of output, and perhaps perform actions such as saving the output to a file. The <SPAN CLASS="GUIMENUITEM" >Exit</SPAN > menu item can be used to shut down the auxiliary. Note that this behaviour can be changed with command line arguments <A HREF="synth-running.html#SYNTH-RUNNING-ARGUMENTS" ><TT CLASS="OPTION" >--exit</TT ></A > and <A HREF="synth-running.html#SYNTH-RUNNING-ARGUMENTS" ><TT CLASS="OPTION" >--no-exit</TT ></A >. </P ><P >If <SPAN CLASS="GUIMENUITEM" >Exit</SPAN > is used while the eCos application is still running then the I/O auxiliary will first attempt to terminate the application cleanly, and then exit. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18005"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="menu_edit.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >The <SPAN CLASS="GUIMENU" >Edit</SPAN > menu contains the usual entries for text manipulation: <SPAN CLASS="GUIMENUITEM" >Cut</SPAN >, <SPAN CLASS="GUIMENUITEM" >Copy</SPAN >, <SPAN CLASS="GUIMENUITEM" >Paste</SPAN >, <SPAN CLASS="GUIMENUITEM" >Clear</SPAN > and <SPAN CLASS="GUIMENUITEM" >Select All</SPAN >. These all operate on the central text window. By default this window cannot be edited so the cut, paste and clear operations are disabled. If the user wants to edit the contents of the text window then the <SPAN CLASS="GUIMENUITEM" >Read Only</SPAN > checkbutton should be toggled. </P ><P >The <SPAN CLASS="GUIMENUITEM" >Preferences</SPAN > menu item brings up a miscellaneous preferences dialog. One of the preferences relates to online help: the I/O auxiliary does not currently have a built-in html viewer; instead it will execute an external browser of some sort. With the example settings shown, the I/O auxiliary will first attempt to interact with an existing mozilla session. If that fails it will try to run a new mozilla instance, or as a last result use the Gnome help viewer. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18019"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="preferences.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >The <SPAN CLASS="GUIMENU" >View</SPAN > menu contains the <SPAN CLASS="GUIMENUITEM" >System Filters</SPAN > entry, used to edit the settings for the current <A HREF="synth-gui.html#SYNTH-GUI-TEXT" >filters</A >. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18027"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="menu_view.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >The <SPAN CLASS="GUIMENU" >Help</SPAN > menu can be used to activate online help for eCos generally, for the synthetic target as a whole, and for specific devices supported by the generic target. The Preferences dialog can be used to select the browser that will be used. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18033"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="menu_help.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >At the time of writing there is no well-defined toplevel index file for all eCos documentation. Hence the relevant menu item is disabled. Documentation for the synthetic target and the supported devices is stored as part of the package itself so can usually be found fairly easily. It may be necessary to set the <TT CLASS="ENVAR" >ECOS_REPOSITORY</TT > environment variable. </P ></BLOCKQUOTE ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-GUI-TEXT" ></A ><H2 >The Main Text Window</H2 ><P >The central text window holds the console output from the eCos application: the screen shot above shows DHCP initialization data from the TCP/IP stack, and some output from the <TT CLASS="FUNCTION" >main</TT > thread at the bottom. Some devices can insert text of their own, for example the ethernet device support can be configured to show details of incoming and outgoing packets. Mixing the output from the eCos application and the various devices can make it easier to understand the order in which events occur. </P ><P >The appearance of text from different sources can be controlled by means of filters, and it is also possible to hide some of the text. For example, if tracing is enabled in the eCos configuration then the trace output can be given its own colour scheme, making it stand out from the rest of the output. In addition the trace output is generally voluminous so it can be hidden by default, made visible only to find out more about what was happening when a particular problem occurred. Similarly the ethernet device support can output details of the various packets being transferred, and using a different background colour for this output again makes it easier to distinguish from console output. </P ><P >The default appearance for most filters is controlled via the <A HREF="synth-running.html#SYNTH-RUNNING-TDF" >target definition file</A >. An example entry might be: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" > filter trace {^TRACE:.*} -foreground HotPink1 -hide 1</PRE ></TD ></TR ></TABLE ><P >The various colours and the hide flag for each filter can be changed at run-time, using the <SPAN CLASS="GUIMENUITEM" >System Filters</SPAN > item on the <SPAN CLASS="GUIMENU" >View</SPAN > menu. This will bring up a dialog like the following: </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18051"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="filters.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >It should be noted that the text window is line-oriented, not character-oriented. If an eCos application sends a partial line of text then that will remain buffered until a newline character is received, rather than being displayed immediately. This avoids confusion when there is concurrent output from several sources. </P ><P >By default the text window is read-only. This means it will not allow cut, paste and clear operations, and keyboard input will be ignored. The <SPAN CLASS="GUIMENU" >Edit</SPAN > menu has a checkbutton <SPAN CLASS="GUIMENUITEM" >Read Only</SPAN > which can be toggled to allow write operations. For example, a user could type in a reminder of what was happening at this time, or paste in part of a gdb session. Such keyboard input does not get forwarded to the eCos application: if the latter requires keyboard input then that should happen via a separate keyboard device. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-GUI-LAYOUT" ></A ><H2 >Positioning Optional Windows</H2 ><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. This requires an understanding of the overall layout of the display. </P ><DIV CLASS="INFORMALFIGURE" ><A NAME="AEN18063"><P ></P ><DIV CLASS="MEDIAOBJECT" ><P ><IMG SRC="layout.png" ALIGN="CENTER"></P ></DIV ><P ></P ></DIV ><P >Subwindows are generally packed in one of eight frames surrounding the central text window: <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 >, and <TT CLASS="VARNAME" >.main.se</TT >. To position a row of LED's above the text window and towards the left, a target definition file could contain an entry such as: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >synth_device led { pack -in .main.n -side left … }</PRE ></TD ></TR ></TABLE ><P >Similarly, to put a traffic monitor window on the right of the text window would involve something like: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" > … monitor_pack -in .main.e -side bottom …</PRE ></TD ></TR ></TABLE ><P >Often it will be sufficient to specify a container frame and one of <TT CLASS="CONSTANT" >left</TT >, <TT CLASS="CONSTANT" >right</TT >, <TT CLASS="CONSTANT" >top</TT > or <TT CLASS="CONSTANT" >bottom</TT >. Full control over the positioning requires an understanding of Tcl/Tk and in particular the packing algorithm, and an appropriate reference work should be consulted. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="SYNTH-GUI-GLOBAL-CONFIG" ></A ><H2 >Global Settings</H2 ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >This section still to be written - it should document the interaction between X resources and ecosynth, and how users can control settings such as the main foreground and background colours. </P ></BLOCKQUOTE ></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-running.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-console.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Running a Synthetic Target Application</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 Console Device</TD ></TR ></TABLE ></DIV ></BODY ></HTML >
Go to most recent revision | Compare with Previous | Blame | View Log