io.sgml

eCos操作系统源码

</SECTION>

<!-- }}} -->
<!-- {{{ TTY Drivers -->

<SECTION id="io-tty-driver">
<TITLE> TTY driver</TITLE>

<PARA>
Use the include file <filename>&lt;cyg/io/ttyio.h&gt;</filename> for
this driver.
</PARA>

<PARA>
This <!-- <index></index> -->driver is built on top of the simple
serial driver and is typically used for a device that interfaces with
humans such as a terminal. It provides some minimal formatting of data
on output and allows for line-oriented editing on input.
</PARA>

<!-- {{{ Runtime Configuration -->

<SECTION>
<TITLE>Runtime configuration</TITLE>

<para>
Runtime configuration is achieved by exchanging data structures with
the driver via the <function>cyg_io_set_config()</function> and
<function>cyg_io_get_config()</function> functions.
</para>


<PROGRAMLISTING>
typedef struct {
 cyg_uint32 tty_out_flags;
 cyg_uint32 tty_in_flags;
} cyg_tty_info_t;
</PROGRAMLISTING>

<PARA>The field <structfield><!-- <index></index> -->tty_out_flags</structfield>
is used to control what happens to data as it is send to the serial
port. It contains a bitmap comprised of the bits as defined by the
<literal>CYG_TTY_OUT_FLAGS_xxx</literal> values below. </PARA>

<PROGRAMLISTING>
#define CYG_TTY_OUT_FLAGS_CRLF 0x0001 // Map '\n' =&gt; '\r\n' on output
</PROGRAMLISTING>

<PARA>If this bit is set in <structfield>tty_out_flags</structfield>,
any occurrence of the character &quot;\n&quot; will
be replaced by the sequence &quot;\r\n&quot; before
being sent to the device.</PARA>

<PARA>The field <structfield><!-- <index></index> -->tty_in_flags</structfield>
is used to control how data is handled as it comes from the serial
port. It contains a bitmap comprised of the bits as defined by the
<literal>CYG_TTY_IN_FLAGS_xxx</literal> values below. </PARA>

<PROGRAMLISTING>
#define CYG_TTY_IN_FLAGS_CR 0x0001 // Map '\r' =&gt; '\n' on input
</PROGRAMLISTING>

<PARA>If this bit is set in <structfield>tty_in_flags</structfield>, the
character &quot;\r&quot; (&ldquo;return&rdquo; or &ldquo;enter&rdquo; on
most keyboards) will be mapped to &quot;\n&quot;.</PARA>

<PROGRAMLISTING>
#define CYG_TTY_IN_FLAGS_CRLF 0x0002 // Map '\r\n' =&gt; '\n' on input
</PROGRAMLISTING>

<PARA>
If this bit is set in <structfield>tty_in_flags</structfield>, the
character sequence &quot;\r\n&quot; (often sent by DOS/Windows
based terminals) will be mapped to &quot;\n&quot;. </PARA>

<PROGRAMLISTING>
#define CYG_TTY_IN_FLAGS_BINARY 0x0004 // No input processing
</PROGRAMLISTING>

<PARA>If this bit is set in <structfield>tty_in_flags</structfield>, the
input will not be manipulated in any way before being placed in
the user&rsquo;s buffer. </PARA>

<PROGRAMLISTING>
#define CYG_TTY_IN_FLAGS_ECHO 0x0008 // Echo characters as processed
</PROGRAMLISTING>

<PARA>
If this bit is set in <structfield>tty_in_flags</structfield>, characters
will be echoed back to the serial port as they are processed. </PARA>

</SECTION>

<!-- }}} -->
<!-- {{{ API Details -->

<SECTION>
<TITLE><!-- <index></index> -->API details</TITLE>

<PROGRAMLISTING>
cyg_io_read(handle, buf, len)
</PROGRAMLISTING>

<PARA>This function is used to read data from the device. In the
default case, data is read until an end-of-line character ("\n"
or "\r") is read. Additionally, the characters are echoed
back to the [terminal] device. Minimal editing
of the input is also supported. </PARA>

<NOTE>
<PARA>When connecting to a remote target via GDB it is not possible
to provide console input while GDB is connected. The GDB remote
protocol does not support input. Users must disconnect from GDB
if this functionality is required.</PARA>
</NOTE>

<PROGRAMLISTING>	
cyg_io_write(handle, buf, len)
</PROGRAMLISTING>

<PARA>This function is used to send data to the device. In the default
case, the end-of-line character "\n" is replaced by the
sequence "\r\n". </PARA>

<PROGRAMLISTING>
cyg_io_get_config(handle, key, buf, len)
</PROGRAMLISTING>

<PARA>This function is used to get information about the channel&rsquo;s
configuration at runtime. </PARA>

<VARIABLELIST>
  <VARLISTENTRY>
    <TERM><literal>CYG_IO_GET_CONFIG_TTY_INFO</literal></TERM>
    <LISTITEM>
      <variablelist>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>cyg_tty_info_t</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function:</TERM>
          <LISTITEM>
            <PARA>This function retrieves the current state of the
	    driver.
            </PARA>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
  </varlistentry>
</variablelist>

<PARA>Serial driver keys (see above) may also be specified
in which case the call is passed directly to the serial
driver. </PARA>

<PROGRAMLISTING>
cyg_io_set_config(handle, key, buf, len)
</PROGRAMLISTING>

<PARA>This function is used to modify the channel&rsquo;s configuration
at runtime. </PARA>


<VARIABLELIST>
  <VARLISTENTRY>
    <TERM><literal>CYG_IO_SET_CONFIG_TTY_INFO</literal></term>
    <LISTITEM>
      <VARIABLELIST>
        <VARLISTENTRY>
          <TERM>Buf type:</TERM>
          <LISTITEM>
            <PARA>cyg_tty_info_t</PARA>
          </LISTITEM>
        </VARLISTENTRY>
        <VARLISTENTRY>
          <TERM>Function: 	</TERM>
          <LISTITEM>
            <PARA>This function changes the current state of the
	    driver.</PARA>
          </LISTITEM>
        </VARLISTENTRY>
      </variablelist>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

<PARA>Serial driver
keys (see above) may also be specified in which case the
call is passed directly to the serial driver. </PARA>

</SECTION>

<!-- }}} -->

</SECTION>

<!-- }}} -->
<!-- {{{ DSP Driver -->


<!-- }}} -->

</CHAPTER>

<!-- }}} -->
<!-- {{{ How to Write a Driver -->

<CHAPTER id="io-how-to-write-a-driver">
<TITLE>How to Write a Driver</TITLE>

<!-- {{{ Intro -->

<PARA>
A <!-- <index></index> -->device driver is nothing more than a
named entity that supports the basic I/O functions - read, write, get
config, and set config. Typically a device driver also uses and
manages interrupts from the device. While the interface is generic and
device driver independent, the actual driver implementation is
completely up to the device driver designer. </PARA>

<PARA>That said, the reason for using a device driver is to provide
access to a device from application code in as general purpose a
fashion as reasonable. Most driver writers are also concerned with
making this access as simple as possible while being as efficient
as possible. </PARA>

<PARA>Most device drivers are concerned with the movement of information,
for example data bytes along a serial interface, or packets in a
network. In order to make the most efficient use of system resources,
interrupts are used. This will allow other application processing
to take place while the data transfers are under way, with interrupts
used to indicate when various events have occurred. For example,
a serial port typically generates an interrupt after a character
has been sent &ldquo;down the wire&rdquo; and the interface
is ready for another. It makes sense to allow further application
processing while the data is being sent since this can take quite
a long time. The interrupt can be used to allow the driver to send
a character as soon as the current one is complete, without any
active participation by the application code. </PARA>

<PARA>The main building blocks for device drivers are found in the
include file: <filename>&lt;cyg/io/devtab.h&gt;</filename></PARA>

<PARA>All device drivers in <EMPHASIS>eCos</EMPHASIS> are described
by a device table entry, using the <type>cyg_devtab_entry_t</type> type.
The entry should be created using the <FUNCTION>DEVTAB_ENTRY()</FUNCTION> macro,
like this:</PARA>

<PROGRAMLISTING><function>
DEVTAB_ENTRY</function>(l, name, dep_name, handlers, init, lookup, priv)
</PROGRAMLISTING>

<variablelist>
<title>Arguments</title>
  <varlistentry>
    <term><parameter>l</parameter></term>
    <listitem><para>The "C" label for this device table entry.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter></term>
    <listitem><para>The "C" string name for the device.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>dep_name</parameter></term>
    <listitem><para>For a layered device, the "C" string name of the
    device this device is built upon.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>handlers</parameter></term>
    <listitem><para>A pointer to the I/O function "handlers" (see below).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>init</parameter></term>
    <listitem><para>A function called when eCos is initialized. This
    function can query the device, setup hardware, etc.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>lookup</parameter></term>
    <listitem><para>A function called when <function>cyg_io_lookup()</function> is called
    for this device. </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>priv</parameter></term>
    <listitem><para>A placeholder for any device specific data
    required by the driver.</para></listitem>
  </varlistentry>
</variablelist>

<PARA>The interface to the driver is through the <structfield><!--
<index></index> -->handlers</structfield> field.  This is a pointer to
a set of functions which implement the various <function>cyg_io_XXX()</function>
routines. This table is defined by the macro:</PARA>


<PROGRAMLISTING>
DEVIO_TABLE(l, write, read, get_config, set_config)
</PROGRAMLISTING>

<variablelist>
<title>Arguments</title>
  <varlistentry>
    <term><parameter>l</parameter></term>
    <listitem><para>The "C" label for this table of handlers.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term>write</term>
    <listitem><para>The function called as a result of
    <function>cyg_io_write()</function>.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term>read</term>
    <listitem><para>The function called as a result of
    <function>cyg_io_read()</function>. </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>get_config</term>
    <listitem><para>The function called as a result of
    <function>cyg_io_get_config()</function>.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term>set_config</term>
    <listitem><para>The function called as a result of
    <function>cyg_io_set_config()</function>. </para></listitem>
  </varlistentry>
</variablelist>

<PARA>
When <EMPHASIS>eCos</EMPHASIS> is initialized (sometimes called
&ldquo;boot&rdquo; time), the <function>init()</function> function is called
for all devices in the system. The <function>init()</function> function is
allowed to return an error in which case the device will be placed
&ldquo;off line&rdquo; and all I/O requests to that device will be
considered in error.
</PARA>

<PARA>
The <function>lookup()</function> function is called whenever
the <FUNCTION>cyg_io_lookup()</FUNCTION> function
is called with this device name. The lookup function may cause the device
to come &ldquo;on line&rdquo; which would then allow I/O
operations to proceed. Future versions of the I/O system
will allow for other states, including power saving modes,
etc.
</PARA>

<!-- }}} -->
<!-- {{{ How to Write a Serial Hardware Interface Driver -->

<SECTION id="io-how-to-write-serial-interface-driver">
<TITLE>How to Write a Serial Hardware Interface Driver</TITLE>


<PARA>The standard serial driver supplied with
<EMPHASIS>eCos</EMPHASIS> is structured as a hardware independent
portion and a hardware dependent interface module. To add support for
a new serial port, the user should be able to use the existing
hardware independent portion and just add their own <!--
<index></index> -->interface driver which handles the details of the
actual device. The user should have no need to change the hardware
independent portion. </PARA>

<PARA>The interfaces used by the serial driver and serial implementation
modules are contained in the file <filename>&lt;cyg/io/serial.h&gt;</filename>
</PARA>

<NOTE>
<PARA>In the sections below we use the notation &lt;&lt;xx&gt;&gt; to
mean a module specific value, referred to as &ldquo;xx&rdquo; below.</PARA>
</NOTE>

<!-- {{{ DevTab Entry -->

<section>
<title>DevTab Entry</title>

<PARA>The interface module contains the devtab entry (or entries
if a single module supports more than one interface). This entry
should have the form: </PARA>

<PROGRAMLISTING>
DEVTAB_ENTRY(&lt;&lt;module_name&gt;&gt;, 
             &lt;&lt;device_name&gt;&gt;,
             0,
             &amp;serial_devio, 
             &lt;&lt;module_init&gt;&gt;, 
             &lt;&lt;module_lookup&gt;&gt;,
             &amp;&lt;&lt;serial_channel&gt;&gt;
            );
</PROGRAMLISTING>

<variablelist>
<title>Arguments</title>
  <varlistentry>
    <term><parameter>module_name</parameter></term>