io.sgml

eCos操作系统源码

    <listitem><para>The "C" label for this devtab entry</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>device_name</parameter></term>
    <listitem><para>The "C" string for the
    device. E.g. <filename>/dev/serial0</filename>.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>serial_devio</parameter></term>
    <listitem><para>The table of I/O functions. This set is defined in
    the hardware independent serial driver and should be used.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>module_init</parameter></term>
    <listitem><para>The module initialization function.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>module_lookup</parameter></term>
    <listitem><para>The device lookup function. This function
    typically sets up the device for actual use, turning on
    interrupts, configuring the port, etc.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>serial_channel</parameter></term>
    <listitem><para>This table (defined below) contains the interface
    between the interface module and the serial driver proper.</para></listitem>
  </varlistentry>
</variablelist>

</section>

<!-- }}} -->
<!-- {{{ Serial Channel Structure -->

<section>
<title>Serial Channel Structure</title>

<PARA>Each serial device must have a &ldquo;serial channel&rdquo;.
This is a set of data which describes all operations on the device.
It also contains buffers, etc., if the device is to be buffered.
The serial channel is created by the macro: </PARA>

<PROGRAMLISTING>
SERIAL_CHANNEL_USING_INTERRUPTS(l, funs, dev_priv, baud,stop, parity, word_length,
                                flags, out_buf, out_buflen, in_buf, in_buflen)
</PROGRAMLISTING>

<variablelist>
  <title>Arguments</title>
  <varlistentry>
    <term><parameter>l</parameter></term>
    <listitem><para>The "C" label for this structure.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>funs</parameter></term>
    <listitem><para>The set of interface functions (see below).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>dev_priv</structfield></term>
    <listitem><para>A placeholder for any device specific data for
    this channel.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>baud</structfield></term>
    <listitem><para>The initial baud rate value
    (<type>cyg_serial_baud_t</type>).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>stop</structfield></term>
    <listitem><para>The initial stop bits value
    (<type>cyg_serial_stop_bits_t</type>).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>parity</structfield></term>
    <listitem><para>The initial parity mode value
    (<type>cyg_serial_parity_t</type>).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>word_length</structfield></term>
    <listitem><para>The initial word length value
    (<type>cyg_serial_word_length_t</type>).</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>flags</structfield></term>
    <listitem><para>The initial driver flags value.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>out_buf</structfield></term>
    <listitem><para>Pointer to the output
    buffer. <literal>NULL</literal> if none required.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>out_buflen</structfield></term>
    <listitem><para>The length of the output buffer.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>in_buf</structfield></term>
    <listitem><para>pointer to the input
    buffer. <literal>NULL</literal> if none required.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>in_buflen</structfield></term>
    <listitem><para>The length of the input buffer. </PARA></listitem>
  </varlistentry>
</variablelist>

<PARA>
If either buffer length is zero, no buffering will take place
in that direction and only polled mode functions will be used.
</PARA>

<PARA>
The interface from the hardware independent driver into the
hardware interface module is contained in the <structfield>funs</structfield> table.
This is defined by the macro:
</PARA>

</section>

<!-- }}} -->
<!-- {{{ Serial Functions Structure -->

<section>
<title>Serial Functions Structure</title>

<PROGRAMLISTING>
SERIAL_FUNS(l, putc, getc, set_config, start_xmit, stop_xmit)
</PROGRAMLISTING>


<variablelist>
  <title>Arguments</title>
  <varlistentry>
    <term><structfield>l</structfield></term>
    <listitem><para>The "C" label for this structure.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>putc</structfield></term>
    <listitem>
      <para><literal>bool (*putc)(serial_channel *priv, unsigned char
      c)</literal></para>
      <para>
      This function sends one character to the interface. It should
      return <literal>true</literal> if the character is actually consumed. It should
      return <literal>false</literal> if there is no space in the interface
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>getc</structfield></term>
    <listitem>
      <para><literal>unsigned char (*getc)(serial_channel *priv)</literal></para>
      <para>
      This function fetches one character from the interface. It will
      be only called in a non-interrupt driven mode, thus it should
      wait for a character by polling the device until ready.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><structfield>set_config</structfield></term>
    <listitem>
      <para><literal>bool (*set_config)(serial_channel
      *priv,cyg_serial_info_t *config)</literal></para>
      <para>
        This function is used to configure the port. It should return
        <literal>true</literal> if the hardware is updated to match the desired
        configuration. It should return <literal>false</literal> if the port cannot
        support some parameter specified by the given
        configuration. E.g. selecting 1.5 stop bits and 8 data bits is
        invalid for most serial devices and should not be allowed.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>start_xmit</parameter></term>
    <listitem><para><literal>void (*start_xmit)(serial_channel *priv)</literal></para>
      <para>
        In interrupt mode, turn on the transmitter and allow for
        transmit interrupts.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>stop_xmit</parameter></term>
    <listitem>
      <para><literal>void (*stop_xmit)(serial_channel *priv)</literal></para>
      <para>In interrupt mode, turn off the transmitter.</PARA>
    </listitem>
  </varlistentry>
</variablelist>

</section>

<!-- }}} -->
<!-- {{{ Callbacks -->

<section>
<title>Callbacks</title>

<PARA>
The device interface module can execute functions in the
hardware independent driver via <literal>chan-&gt;callbacks</literal>.
These functions are available:
</PARA>

<PROGRAMLISTING>
void (*serial_init)( serial_channel *chan )
</PROGRAMLISTING>

<PARA>This function is used to initialize the serial channel. It
is only required if the channel is being used in interrupt
mode.</PARA>

<PROGRAMLISTING>
void (*xmt_char)( serial_channel *chan )
</PROGRAMLISTING>

<PARA>
This function would be called from an interrupt handler after a
transmit interrupt indicating that additional characters may be
sent. The upper driver will call the <function>putc</function>
function as appropriate to send more data to the device.</PARA>

<PROGRAMLISTING>
void (*rcv_char)( serial_channel *chan, unsigned char c )
</PROGRAMLISTING>


<PARA>
This function is used to tell the driver that a character has arrived
at the interface. This function is typically called from the interrupt
handler. </PARA>

<PARA>
Furthermore, if the device has a FIFO it should require the hardware
independent driver to provide block transfer functionality (driver CDL
should include &quot;implements
CYGINT_IO_SERIAL_BLOCK_TRANSFER&quot;).  In that case, the following
functions are available as well:</PARA>

<PROGRAMLISTING>
bool (*data_xmt_req)(serial_channel *chan,
                     int space,
                     int* chars_avail,
                     unsigned char** chars)
void (*data_xmt_done)(serial_channel *chan)
</PROGRAMLISTING>

<PARA>
Instead of calling <function>xmt_char()</function> to get a single
character for transmission at a time, the driver should call
<function>data_xmt_req()</function> in a loop, requesting character
blocks for transfer. Call with a <parameter>space</parameter> argument of how much space
there is available in the FIFO.</PARA>

<PARA>If the call returns <literal>true</literal>, the driver can read
<parameter>chars_avail</parameter> characters from
<parameter>chars</parameter> and copy them into the FIFO.</PARA>

<PARA>If the call returns <literal>false</literal>, there are
no more buffered characters and the driver should continue without
filling up the FIFO.</PARA>

<PARA>When all data has been unloaded, the
driver must call <function>data_xmt_done()</function>.</PARA>


<PROGRAMLISTING>
bool (*data_rcv_req)(serial_channel *chan,
                     int avail,
                     int* space_avail,
                     unsigned char** space)
void (*data_rcv_done)(serial_channel *chan)
</PROGRAMLISTING>

<PARA>Instead of calling <function>rcv_char()</function> with a single
character at a time, the driver should call
<function>data_rcv_req()</function> in a loop, requesting space to
unload the FIFO to. <parameter>avail</parameter> is the number of
characters the driver wishes to unload.</PARA>


<PARA>If the call returns <literal>true</literal>, the driver can copy
<parameter>space_avail</parameter> characters to
<parameter>space</parameter>. </PARA>


<PARA>If the call returns <literal>false</literal>, the input buffer is
full. It is up to the driver to decide what to do in that case
(callback functions for registering overflow are being planned for
later versions of the serial driver).
</PARA>

<PARA>When all data has been unloaded, the driver must call
<function>data_rcv_done()</function>.</PARA>

</section>

<!-- }}} -->

</SECTION>

<!-- }}} -->
<!-- {{{ Serial Testing -->

<section id="io-serial-testing-with-serfilter">
<title>Serial testing with ser_filter</title>

<!-- {{{ Rationale -->

<section id="io-serfilter-rationale">
<title>Rationale</title>

<para>
Since some targets only have one serial connection, a serial testing harness
needs to be able to share the connection with <application>GDB</application>
(however, the test and <application>GDB</application> can also run on separate
lines).
</para>

<para>
The <firstterm>serial filter</firstterm> (<application>ser_filter</application>)
sits between the serial port and <application>GDB</application> and monitors
the exchange of data between <application>GDB</application> and the target.
Normally, no changes are made to the data.
</para>

<para>
When a test request packet is sent from the test on the target, it is 
intercepted by the filter.
</para>

<para>
The filter and target then enter a loop, exchanging protocol data between
them which <application>GDB</application> never sees.
</para>

<para>
In the event of a timeout, or a crash on the target, the filter falls
back into its pass-through mode. If this happens due to a crash it should be
possible to start regular debugging with <application>GDB</application>. The
filter will stay in the pass-though mode until <application>GDB</application>
disconnects.
</para>
</section>

<!-- }}} -->
<!-- {{{ The Protocol -->

<section id="io-serfilter-protocol">
<title>The Protocol</title>

<para>The protocol commands are prefixed with an <literal>&quot;@&quot;</literal>
character which the serial filter is looking for. The protocol
commands include:
</para>

<variablelist>
  <varlistentry>
    <term><literal>PING</literal></term>
    <listitem>
      <para>Allows the test on the target to probe for the filter. The
      filter responds with <literal>OK</literal>, while
      <application>GDB</application> would just ignore the
      command. This allows the tests to do nothing if they require the
      filter and it is not present.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>CONFIG</literal></term>
    <listitem>
      <para>Requests a change of serial line configuration. Arguments
      to the command specify baud rate, data bits, stop bits, and
      parity. [This command is not fully implemented yet - there is no
      attempt made to recover if the new configuration turns out to
      cause loss of data.]</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>BINARY</literal></term>
    <listitem>
      <para>Requests data to be sent from the filter to the
      target. The data is checksummed, allowing errors in the transfer
      to be detected.  Sub-options of this command control how the
      data transfer is made:</para>
      <variablelist>
        <varlistentry>
          <term><literal>NO_ECHO</literal></term>
          <listitem>
            <para>(serial driver receive test) Just send data from the
            filter to the target. The test verifies the checksum and
            PASS/FAIL depending on the result. </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>EOP_ECHO</literal></term>