synth.sgml

开放源码实时操作系统源码.

<!-- {{{ The console device             -->

<refentry id="synth-console">
  <refmeta>
    <refentrytitle>The Console Device</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>The console device </refname>
    <refpurpose>Show output from the eCos application</refpurpose>
  </refnamediv>

  <refsect1 id="synth-console-description"><title>Description</title>
    <para>
The eCos application can generate text output in a variety of ways,
including calling <function>printf</function> or
<function>diag_printf</function>. When the I/O auxiliary is enabled
the eCos startup code will instantiate a console device to process all
such output. If operating in text mode the output will simply go to
standard output, or to a logfile if the <option>-l</option> command
line option is specified. If operating in graphical mode the output
will go to the central text window, and optionally to a logfile as
well. In addition it is possible to control the appearance of the main
text via the target definition file, and to install extra filters for
certain types of text.
    </para>
    <para>
It should be noted that the console device is line-oriented, not
character-oriented. This means that outputting partial lines is not
supported, and some functions such as <function>fflush</function> and
<function>setvbuf</function> will not operate as expected. This
limitation prevents much possible confusion when using filters to
control the appearance of the text window, and has some performance
benefits - especially when the eCos application generates a great deal
of output such as when tracing is enabled. For most applications this
is not a problem, but it is something that developers should be aware
of. 
    </para>
    <para>
The console device is output-only, it does not provide any support for
keyboard input. If the application requires keyboard input then that
should be handled by a separate eCos device package and matching
host-side code.
    </para>
  </refsect1>

  <refsect1 id="synth-console-install"><title>Installation</title>
    <para>
The eCos side of the console device is implemented by the
architectural HAL itself, in the source file
<filename>synth_diag.c</filename>, rather than in a separate device
package. Similarly the host-side implementation,
<function>console.tcl</function>, is part of the architectural HAL's
host-side support. It gets installed automatically alongside the I/O
auxiliary itself, so no separate installation procedure is required.
    </para>
  </refsect1>

  <refsect1 id="synth-console-tdf"><title>Target Definition File</title>
    <para>
The <link linkend="synth-running-tdf">target definition file</link>
can contain a number of entries related to the console device. These
are all optional, they only control the appearance of text output. If
such control is desired then the relevant options should appear in the
body of a <command>synth_device</command> entry:
    </para>
    <programlisting>
synth_device console {
    &hellip;
}
</programlisting>
    <para>
The first option is <command>appearance</command>, used to control the
appearance of any text generated by the eCos application that does not
match one of the installed filters. This option takes the same
argument as any other filter, for example:
    </para>
    <programlisting>
synth_device console {
    appearance -foreground white -background black
    &hellip;
}
</programlisting>
    <para>
Any number of additional filters can be created with a
<command>filter</command> option, for example:
    </para>
    <programlisting>
synth_device console {
    &hellip;
    filter trace {^TRACE:.*} -foreground HotPink1 -hide 1
    &hellip;
}
</programlisting>
    <para>
The first argument gives the new filter a name which will be used in
the <link linkend="synth-gui-text">filters dialog</link>. Filter names
should be unique. The second argument is a Tcl regular expression. The
console support will match each line of eCos output against this
regular expression, and if a match is found then the filter will be
used for this line of text. The above example matches any line of
output that begins with <literal>TRACE:</literal>, which corresponds
to the eCos infrastructure's tracing facilities. The remaining options
control the desired appearance for matched text. If some eCos output
matches the regular expressions for several different filters then
only the first match will be used.
    </para>
  </refsect1>

  <refsect1 id="synth-console-target-config"><title>Target-side
  Configuration Options</title>
    <para>
There are no target-side configuration options related to the console
device. 
    </para>
  </refsect1>

  <refsect1 id="synth-console-arguments"><title>Command Line Arguments</title>
    <para>
The console device does not use any command-line arguments.
    </para>
  </refsect1>

  <refsect1 id="synth-console-hooks"><title>Hooks</title>
    <para>
The console device does not provide any hooks.
    </para>
  </refsect1>

  <refsect1><title>Additional Tcl Procedures</title>
    <para>
The console device does not provide any additional Tcl procedures that
can be used by other scripts.
    </para>
  </refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ System calls                   -->

<refentry id="synth-syscalls">
  <refmeta>
    <refentrytitle>System Calls</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>cyg_hal_sys_xyz</refname>
    <refpurpose>Access Linux system facilities</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
#include &lt;cyg/hal/hal_io.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
        <funcdef>int <function>cyg_hal_sys_xyzzy</function></funcdef>
        <varargs>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1 id="synth-syscalls-description"><title>Description</title>
    <para>
On a real embedded target eCos interacts with the hardware by peeking
and poking various registers, manipulating special regions of memory,
and so on. The synthetic target does not access hardware directly.
Instead I/O and other operations are emulated by making appropriate
Linux system calls. The HAL package exports a number of functions
which allow other packages, or even application code, to make these
same system calls. However this facility must be used with care: any
code which calls, for example, <function>cyg_hal_sys_write</function>
will only ever run on the synthetic target; that functionality is
obviously not provided on any real hardware because there is no
underlying Linux kernel to implement it.
    </para>
    <para>
The synthetic target only provides a subset of the available system
calls, specifically those calls which have proved useful to implement
I/O emulation. This subset can be extended fairly easily if necessary.
All of the available calls, plus associated data structures and
macros, are defined in the header file <filename
class="headerfile">cyg/hal/hal_io.h</filename>. There is a simple
convention: given a Linux system call such as
<function>open</function>, the synthetic target will prefix
<literal>cyg_hal_sys</literal> and provide a function with that name.
The second argument to the <function>open</function> system call is
a set of flags such as <constant>O_RDONLY</constant>, and the header
file will define a matching constant
<constant>CYG_HAL_SYS_O_RDONLY</constant>. There are also data
structures such as <structname>cyg_hal_sys_sigset_t</structname>,
matching the Linux data structure <structname>sigset_t</structname>.
    </para>
    <para>
In most cases the functions provided by the synthetic target behave as
per the documentation for the Linux system calls, and section 2 of the
Linux man pages can be consulted for more information. There is one
important difference: typically the documentation will say that a
function returns <literal>-1</literal> to indicate an error, with the
actual error code held in <varname>errno</varname>; the actual
underlying system call and hence the
<function>cyg_hal_sys_xyz</function> provided by eCos instead returns
a negative number to indicate an error, with the absolute value of
that number corresponding to the error code; usually it is the C
library which handles this and manipulates errno, but of course
synthetic target applications are not linked with that Linux library.
    </para>
    <para>
However, there are some exceptions. The Linux kernel has evolved over
the years, and some of the original system call interfaces are no
longer appropriate. For example the original
<function>select</function> system call has been superseded by
<function>_newselect</function>, and that is what the
<function>select</function> function in the C library actually uses.
The old call is still available to preserve binary compatibility but,
like the C library, eCos makes use of the new one because it provides
the appropriate functionality. In an attempt to reduce confusion the
eCos function is called <function>cyg_hal_sys__newselect</function>,
in other words it matches the official system call naming scheme. The
authoritive source of information on such matters is the Linux kernel
sources themselves, and especially its header files.
    </para>
    <para>
eCos packages and applications should never
<literal>#include</literal> Linux header files directly. For example,
doing a <literal>#include&nbsp;&lt;/usr/include/fcntl.h&gt;</literal>
to access additional macros or structure definitions, or alternatively
manipulating the header file search path, will lead to problems
because the Linux header files are likely to duplicate and clash with
definitions in the eCos headers. Instead the appropriate functionality
should be extracted from the Linux headers and moved into either
<filename class="headerfile">cyg/hal/hal_io.h</filename> or into
application code, with suitable renaming to avoid clashes with eCos
names. Users should be aware that large-scale copying may involve
licensing complications.
    </para>
    <para>
Adding more system calls is usually straightforward and involves
adding one or more lines to the platform-specific file in the
appropriate platform HAL, for example
<filename>syscall-i386-linux-1.0.S</filename>. However it is necessary
to do some research first about the exact interface implemented by the
system call, because of issues such as old system calls that have been
superseded. The required information can usually be found fairly
easily by searching through the Linux kernel sources and possibly the
GNU C library sources.
    </para>
  </refsect1>
</refentry>

<!-- }}} -->
<!-- {{{ New devices - target-side      -->

<refentry id="synth-new-target">
  <refmeta>
    <refentrytitle>Writing New Devices - target</refentrytitle>
  </refmeta>
  <refnamediv>
    <refname>Writing New Devices</refname>
    <refpurpose>extending the synthetic target, target-side</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
#include &lt;cyg/hal/hal_io.h&gt;
      </funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>synth_auxiliary_instantiate</function></funcdef>
        <paramdef>const char* <parameter>package</parameter></paramdef>
        <paramdef>const char* <parameter>version</parameter></paramdef>
        <paramdef>const char* <parameter>device</parameter></paramdef>
        <paramdef>const char* <parameter>instance</parameter></paramdef>
        <paramdef>const char* <parameter>data</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>synth_auxiliary_xchgmsg</function></funcdef>
        <paramdef>int <parameter>device_id</parameter></paramdef>
        <paramdef>int <parameter>request</parameter></paramdef>
        <paramdef>int <para