doc/html/ref/synth-console.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >The Console Device</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="eCos Synthetic Target"
  23 HREF="hal-synth-arch.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="The I/O Auxiliary's User Interface"
  26 HREF="synth-gui.html"><LINK
  27 REL="NEXT"
  28 TITLE="System Calls"
  29 HREF="synth-syscalls.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="synth-gui.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="synth-syscalls.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="SYNTH-CONSOLE">The Console Device</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN18091"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >The console device &nbsp;--&nbsp;Show output from the eCos application</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="SYNTH-CONSOLE-DESCRIPTION"
  95 ></A
  96 ><H2
  97 >Description</H2
  98 ><P
  99 >The eCos application can generate text output in a variety of ways,
 100 including calling <TT
 101 CLASS="FUNCTION"
 102 >printf</TT
 103 > or
 104 <TT
 105 CLASS="FUNCTION"
 106 >diag_printf</TT
 107 >. When the I/O auxiliary is enabled
 108 the eCos startup code will instantiate a console device to process all
 109 such output. If operating in text mode the output will simply go to
 110 standard output, or to a logfile if the <TT
 111 CLASS="OPTION"
 112 >-l</TT
 113 > command
 114 line option is specified. If operating in graphical mode the output
 115 will go to the central text window, and optionally to a logfile as
 116 well. In addition it is possible to control the appearance of the main
 117 text via the target definition file, and to install extra filters for
 118 certain types of text.
 119     </P
 120 ><P
 121 >It should be noted that the console device is line-oriented, not
 122 character-oriented. This means that outputting partial lines is not
 123 supported, and some functions such as <TT
 124 CLASS="FUNCTION"
 125 >fflush</TT
 126 > and
 127 <TT
 128 CLASS="FUNCTION"
 129 >setvbuf</TT
 130 > will not operate as expected. This
 131 limitation prevents much possible confusion when using filters to
 132 control the appearance of the text window, and has some performance
 133 benefits - especially when the eCos application generates a great deal
 134 of output such as when tracing is enabled. For most applications this
 135 is not a problem, but it is something that developers should be aware
 136 of.
 137     </P
 138 ><P
 139 >The console device is output-only, it does not provide any support for
 140 keyboard input. If the application requires keyboard input then that
 141 should be handled by a separate eCos device package and matching
 142 host-side code.
 143     </P
 144 ></DIV
 145 ><DIV
 146 CLASS="REFSECT1"
 147 ><A
 148 NAME="SYNTH-CONSOLE-INSTALL"
 149 ></A
 150 ><H2
 151 >Installation</H2
 152 ><P
 153 >The eCos side of the console device is implemented by the
 154 architectural HAL itself, in the source file
 155 <TT
 156 CLASS="FILENAME"
 157 >synth_diag.c</TT
 158 >, rather than in a separate device
 159 package. Similarly the host-side implementation,
 160 <TT
 161 CLASS="FUNCTION"
 162 >console.tcl</TT
 163 >, is part of the architectural HAL's
 164 host-side support. It gets installed automatically alongside the I/O
 165 auxiliary itself, so no separate installation procedure is required.
 166     </P
 167 ></DIV
 168 ><DIV
 169 CLASS="REFSECT1"
 170 ><A
 171 NAME="SYNTH-CONSOLE-TDF"
 172 ></A
 173 ><H2
 174 >Target Definition File</H2
 175 ><P
 176 >The <A
 177 HREF="synth-running.html#SYNTH-RUNNING-TDF"
 178 >target definition file</A
 179 >
 180 can contain a number of entries related to the console device. These
 181 are all optional, they only control the appearance of text output. If
 182 such control is desired then the relevant options should appear in the
 183 body of a <B
 184 CLASS="COMMAND"
 185 >synth_device</B
 186 > entry:
 187     </P
 188 ><TABLE
 189 BORDER="5"
 190 BGCOLOR="#E0E0F0"
 191 WIDTH="70%"
 192 ><TR
 193 ><TD
 194 ><PRE
 195 CLASS="PROGRAMLISTING"
 196 >synth_device console {
 197     &#8230;
 198 }</PRE
 199 ></TD
 200 ></TR
 201 ></TABLE
 202 ><P
 203 >The first option is <B
 204 CLASS="COMMAND"
 205 >appearance</B
 206 >, used to control the
 207 appearance of any text generated by the eCos application that does not
 208 match one of the installed filters. This option takes the same
 209 argument as any other filter, for example:
 210     </P
 211 ><TABLE
 212 BORDER="5"
 213 BGCOLOR="#E0E0F0"
 214 WIDTH="70%"
 215 ><TR
 216 ><TD
 217 ><PRE
 218 CLASS="PROGRAMLISTING"
 219 >synth_device console {
 220     appearance -foreground white -background black
 221     &#8230;
 222 }</PRE
 223 ></TD
 224 ></TR
 225 ></TABLE
 226 ><P
 227 >Any number of additional filters can be created with a
 228 <B
 229 CLASS="COMMAND"
 230 >filter</B
 231 > option, for example:
 232     </P
 233 ><TABLE
 234 BORDER="5"
 235 BGCOLOR="#E0E0F0"
 236 WIDTH="70%"
 237 ><TR
 238 ><TD
 239 ><PRE
 240 CLASS="PROGRAMLISTING"
 241 >synth_device console {
 242     &#8230;
 243     filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
 244     &#8230;
 245 }</PRE
 246 ></TD
 247 ></TR
 248 ></TABLE
 249 ><P
 250 >The first argument gives the new filter a name which will be used in
 251 the <A
 252 HREF="synth-gui.html#SYNTH-GUI-TEXT"
 253 >filters dialog</A
 254 >. Filter names
 255 should be unique. The second argument is a Tcl regular expression. The
 256 console support will match each line of eCos output against this
 257 regular expression, and if a match is found then the filter will be
 258 used for this line of text. The above example matches any line of
 259 output that begins with <TT
 260 CLASS="LITERAL"
 261 >TRACE:</TT
 262 >, which corresponds
 263 to the eCos infrastructure's tracing facilities. The remaining options
 264 control the desired appearance for matched text. If some eCos output
 265 matches the regular expressions for several different filters then
 266 only the first match will be used.
 267     </P
 268 ></DIV
 269 ><DIV
 270 CLASS="REFSECT1"
 271 ><A
 272 NAME="SYNTH-CONSOLE-TARGET-CONFIG"
 273 ></A
 274 ><H2
 275 >Target-side
 276   Configuration Options</H2
 277 ><P
 278 >There are no target-side configuration options related to the console
 279 device.
 280     </P
 281 ></DIV
 282 ><DIV
 283 CLASS="REFSECT1"
 284 ><A
 285 NAME="SYNTH-CONSOLE-ARGUMENTS"
 286 ></A
 287 ><H2
 288 >Command Line Arguments</H2
 289 ><P
 290 >The console device does not use any command-line arguments.
 291     </P
 292 ></DIV
 293 ><DIV
 294 CLASS="REFSECT1"
 295 ><A
 296 NAME="SYNTH-CONSOLE-HOOKS"
 297 ></A
 298 ><H2
 299 >Hooks</H2
 300 ><P
 301 >The console device does not provide any hooks.
 302     </P
 303 ></DIV
 304 ><DIV
 305 CLASS="REFSECT1"
 306 ><A
 307 NAME="AEN18133"
 308 ></A
 309 ><H2
 310 >Additional Tcl Procedures</H2
 311 ><P
 312 >The console device does not provide any additional Tcl procedures that
 313 can be used by other scripts.
 314     </P
 315 ></DIV
 316 ><DIV
 317 CLASS="NAVFOOTER"
 318 ><HR
 319 ALIGN="LEFT"
 320 WIDTH="100%"><TABLE
 321 SUMMARY="Footer navigation table"
 322 WIDTH="100%"
 323 BORDER="0"
 324 CELLPADDING="0"
 325 CELLSPACING="0"
 326 ><TR
 327 ><TD
 328 WIDTH="33%"
 329 ALIGN="left"
 330 VALIGN="top"
 331 ><A
 332 HREF="synth-gui.html"
 333 ACCESSKEY="P"
 334 >Prev</A
 335 ></TD
 336 ><TD
 337 WIDTH="34%"
 338 ALIGN="center"
 339 VALIGN="top"
 340 ><A
 341 HREF="ecos-ref.html"
 342 ACCESSKEY="H"
 343 >Home</A
 344 ></TD
 345 ><TD
 346 WIDTH="33%"
 347 ALIGN="right"
 348 VALIGN="top"
 349 ><A
 350 HREF="synth-syscalls.html"
 351 ACCESSKEY="N"
 352 >Next</A
 353 ></TD
 354 ></TR
 355 ><TR
 356 ><TD
 357 WIDTH="33%"
 358 ALIGN="left"
 359 VALIGN="top"
 360 >The I/O Auxiliary's User Interface</TD
 361 ><TD
 362 WIDTH="34%"
 363 ALIGN="center"
 364 VALIGN="top"
 365 ><A
 366 HREF="hal-synth-arch.html"
 367 ACCESSKEY="U"
 368 >Up</A
 369 ></TD
 370 ><TD
 371 WIDTH="33%"
 372 ALIGN="right"
 373 VALIGN="top"
 374 >System Calls</TD
 375 ></TR
 376 ></TABLE
 377 ></DIV
 378 ></BODY
 379 ></HTML
 380 >