io.sgml

eCos操作系统源码

          <listitem>
            <para>(serial driver half-duplex receive and send test) As
            <literal>NO_ECHO</literal> but the test echoes back the
            data to the filter.  The filter does a checksum on the
            received data and sends the result to the target. The test
            PASS/FAIL depending on the result of both checksum
            verifications.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>DUPLEX_ECHO</literal></term>
          <listitem>
            <para>(serial driver duplex receive and send test) Smaller
            packets of data are sent back and forth in a pattern that
            ensures that the serial driver will be both sending and
            receiving at the same time. Again, checksums are computed
            and verified resulting in PASS/FAIL.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><literal>TEXT</literal></term>
    <listitem>
      <para> This is a test of the text translations in the TTY layer.
      Requests a transfer of text data from the target to the filter
      and possibly back again. The filter treats this as a binary
      transfer, while the target ma be doing translations on the
      data. The target provides the filter with checksums for what it
      should expect to see. This test is not implemented yet.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>The above commands may be extended, and new commands added, as
required to test (new) parts of the serial drivers in
<productname>eCos</productname>.
</para>

</section>

<!-- }}} -->
<!-- {{{ The Serial Tests -->

<section id="io-serfilter-serial-tests">
<title>The Serial Tests</title>

<para>
The serial tests are built as any other eCos test. After running the
<command>make tests</command> command, the tests can be found in
<filename>install/tests/io_serial/</filename></para>

<variablelist>
  <varlistentry>
    <term><filename>serial1</filename></term>
    <listitem><para>A simple API test.</para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>serial2</filename></term>
    <listitem>
      <para>A simple serial send test. It writes out two strings, one
      raw and one encoded as a <application>GDB</application>
      O-packet</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>serial3</filename> [ requires the serial filter ]</term>
    <listitem>
      <para>This tests the half-duplex send and receive capabilities
      of the serial driver. </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>serial4</filename> [ requires the serial filter ]</term>
    <listitem>
      <para>This test attempts to use a few different serial
      configurations, testing the driver's configuration/setup
      functionality. </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>serial5</filename> [ requires the serial filter ]</term>
    <listitem>
      <para>This tests the duplex send and receive capabilities of the
      serial driver. </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>All tests should complete in less than 30 seconds.</para>

</section>

<!-- }}} -->
<!-- {{{ Serial Filter Usage-->

<section id="io-serfilter-usage">
<title>Serial Filter Usage</title>

<para>Running the ser_filter program with no (or wrong) arguments results in
the following output:
</para>

<screen>
Usage: ser_filter [-t -S] TcpIPport SerialPort BaudRate 
or: ser_filter -n [-t -S] SerialPort BaudRate 
-t: Enable tracing. 
-S: Output data read from serial line. 
-c: Output data on console instead of via GDB. 
-n: No GDB. 
</screen>

<para>The normal way to use it with GDB is to start the filter:</para>

<screen>
$ <userinput>ser_filter -t 9000 com1 38400</userinput>
</screen>

<para>
In this case, the filter will be listening on port 9000 and connect to the
target via the serial port <literal>COM1</literal> at 38400 baud. On a UNIX
host, replace "<literal>COM1</literal>" with a device such as 
"<filename>/dev/ttyS0</filename>".
</para>

<para>
The <option>-t</option> option enables tracing which will cause the
filter to describe its actions on the console.
</para>

<para>Now start <application>GDB</application> with one of the tests as an
argument:
</para>

<screen>
$ <userinput>mips-tx39-elf-gdb -nw install/tests/io_serial/serial3</userinput>
</screen>

<para>Then connect to the filter:</para>

<screen>
(gdb) <userinput>target remote localhost:9000</userinput>
</screen>

<para>
This should result in a connection in exactly the same way as if you
had connected directly to the target on the serial line.
</para>

<screen>
(gdb) <userinput>c</userinput>
</screen>

<para>
Which should result in output similar to the below:
</para>

<screen>
Continuing. 
INFO: &lt;BINARY:16:1!&gt; 
PASS: &lt;Binary test completed&gt;
INFO: &lt;BINARY:128:1!&gt; 
PASS: &lt;Binary test completed&gt;
INFO: &lt;BINARY:256:1!&gt; 
PASS: &lt;Binary test completed&gt;
INFO: &lt;BINARY:1024:1!&gt; 
PASS: &lt;Binary test completed&gt;
INFO: &lt;BINARY:512:0!&gt;
PASS: &lt;Binary test completed&gt;
... 
PASS: &lt;Binary test completed&gt;
INFO: &lt;BINARY:16384:0!&gt;
PASS: &lt;Binary test completed&gt;
PASS: &lt;serial13 test OK&gt;
EXIT: &lt;done&gt;
</screen>

<para>
If any of the individual tests fail the testing will terminate with a 
<computeroutput>FAIL</computeroutput>.
</para>

<para>
With tracing enabled, you would also see the filter's status output:
</para>

<para>
The <literal>PING</literal> command sent from the target to determine the
presence of the filter:
</para>

<screen>
[400 11:35:16] Dispatching command PING 
[400 11:35:16] Responding with status OK
</screen>

<para>Each of the binary commands result in output similar to:</para>

<screen>
[400 11:35:16] Dispatching command BINARY 
[400 11:35:16] Binary data (Size:16, Flags:1). 
[400 11:35:16] Sending CRC: '170231!', len: 7. 
[400 11:35:16] Reading 16 bytes from target. 
[400 11:35:16] Done. in_crc 170231, out_crc 170231. 
[400 11:35:16] Responding with status OK 
[400 11:35:16] Received DONE from target.
</screen>

<para>
This tracing output is normally sent as O-packets to <application>GDB
</application> which will display the tracing text. By using the
<option>-c </option> option, the tracing text can be redirected to the
console from which ser_filter was started.
</para>

</section>

<!-- }}} -->
<!-- {{{ A Note on Failures -->

<section id="io-serfilter-failures">
<title>A Note on Failures</title>

<para>
A serial connection (especially when driven at a high baud rate) can garble the
transmitted data because of noise from the environment. It is not the job of
the serial driver to ensure data integrity - that is the job of protocols
layering on top of the serial driver. </para>

<para>In the current implementation the serial tests and the serial filter are
not resilient to such data errors. This means that the test may crash or hang
(possibly without reporting a <computeroutput>FAIL</computeroutput>). It also
means that you should be aware of random errors - a <computeroutput>FAIL
</computeroutput> is not necessarily caused by a bug in the serial driver.
</para>

<para>Ideally, the serial testing infrastructure should be able to distinguish
random errors from consistent errors - the former are most likely due to noise
in the transfer medium, while the latter are more likely to be caused by faulty
drivers. The current implementation of the infrastructure does not have this
capability.</para>

</section>

<!-- }}} -->
<!-- {{{ Debugging -->

<section id="io-serfilter-debugging">
<title>Debugging</title>

<para>If a test fails, the serial filter's output may provide some hints about
what the problem is. If the option <option>-S</option> is used when starting
the filter, data received from the target is printed out: 
</para>

<screen>
[400 11:35:16] 0000 50 41 53 53 3a 3c 42 69 'PASS:&lt;Bi'
[400 11:35:16] 0008 6e 61 72 79 20 74 65 73 'nary.tes' 
[400 11:35:16] 0010 74 20 63 6f 6d 70 6c 65 't.comple' 
[400 11:35:16] 0018 74 65 64 3e 0d 0a 49 4e 'ted&gt;..IN' 
[400 11:35:16] 0020 46 4f 3a 3c 42 49 4e 41 'FO:&lt;BINA'
[400 11:35:16] 0028 52 59 3a 31 32 38 3a 31 'RY:128:1' 
[400 11:35:16] 0030 21 3e 0d 0a 40 42 49 4e '!..@BIN' 
[400 11:35:16] 0038 41 52 59 3a 31 32 38 3a 'ARY:128:' 
[400 11:35:16] 0040 31 21 .. .. .. .. .. .. '1!' 
</screen>

<para>In the case of an error during a testing command the data received by the
filter will be printed out, as will the data that was expected. This allows
the two data sets to be compared which may give some idea of what the problem
is.</para>

</section>

<!-- }}} -->

</section>

<!-- }}} -->

</chapter>

<!-- }}} -->
<!-- {{{ Device Driver API -->

<CHAPTER id="devapi-device-driver-interface-to-the-kernel">
<TITLE>Device Driver Interface to the Kernel</TITLE>

<PARA>
This chapter describes the API that device drivers may use
to interact with the kernel and HAL. It is primarily concerned with
the control and management of interrupts and the synchronization of
ISRs, DSRs and threads.
</PARA>

<PARA>
The same API will be present in configurations where the kernel
is not present. In this case the functions will be supplied by code
acting directly on the HAL.
</PARA>


<!-- {{{ Interrupt Model -->

<SECTION id="devapi-interrupt-model">
<TITLE>Interrupt Model</TITLE>

<PARA>
<EMPHASIS>eCos</EMPHASIS> presents a three level interrupt model to
<!-- <index></index> -->device drivers. This consists of <!--
<index></index> -->Interrupt Service Routines (ISRs) that are invoked
in response to a hardware interrupt; <!-- <index></index> -->Deferred
Service Routines (DSRs) that are invoked in response to a request by
an ISR; and threads that are the clients of the driver. </PARA>

<PARA>
Hardware interrupts are delivered with minimal intervention to an
ISR. The HAL decodes the hardware source of the interrupt and calls
the ISR of the attached interrupt object. This ISR may manipulate the
hardware but is only allowed to make a restricted set of calls on the
driver API. When it returns, an ISR may request that its DSR should be
scheduled to run.
</PARA>

<PARA>
A DSR will be run when it is safe to do so without interfering with
the scheduler. Most of the time the DSR will run immediately after the
ISR, but if the current thread is in the scheduler, it will be delayed
until the thread is finished. A DSR is allowed to make a larger set of
driver API calls, including, in particular, being able to call
<FUNCTION>cyg_drv_cond_signal()</FUNCTION> to wake up waiting
threads.
</PARA>

<PARA>
Finally, threads are able to make all API calls and in particular are
allowed to wait on mutexes and condition variables. </PARA>


<PARA>
For a device driver to receive interrupts it must first define ISR and
DSR routines as shown below, and then call
<FUNCTION>cyg_drv_interrupt_create()</FUNCTION>.  Using the handle
returned, the driver must then call
<FUNCTION>cyg_drv_interrupt_attach()</FUNCTION> to actually attach the
interrupt to the hardware vector.
</PARA>


</SECTION>

<!-- }}} -->
<!-- {{{ Synchronization -->

<SECTION id="devapi-synchronization">
<TITLE><!-- <index></index> -->Synchronization</TITLE>

<PARA>There are three levels of synchronization supported:</PARA>

<ORDEREDLIST>
  <LISTITEM>
    <PARA>
    Synchronization with ISRs. This normally means disabling
    interrupts to prevent the ISR running during a critical
    section. In an SMP environment, this will also require the use of
    a spinlock to synchronize with ISRs, DSRs or threads running on
    other CPUs.  This is implemented by the
    <FUNCTION>cyg_drv_isr_lock()</FUNCTION> and
    <FUNCTION>cyg_drv_isr_unlock()</FUNCTION> functions. This
    mechanism should be used sparingly and for short periods only.
    For finer grained synchronization, individual spinlocks are also
    supplied.
    </PARA>
  </LISTITEM>

  <LISTITEM>
    <PARA>
    Synchronization with DSRs. This will be implemented in the kernel
    by taking the scheduler lock to prevent DSRs running during
    critical sections. In non-kernel configurations it will be
    implemented by non-kernel code. This is implemented by the
    <FUNCTION>cyg_drv_dsr_lock()</FUNCTION> and
    <FUNCTION>cyg_drv_dsr_unlock()</FUNCTION> functions. As with ISR
    synchronization, this mechanism should be used sparingly. Only
    DSRs and threads may use this synchronization mechanism, ISRs are
    not allowed to do this.
    </PARA>
  </LISTITEM>
  <LISTITEM>
    <PARA>
    Synchronization with threads. This is implemented with mutexes
    and condition variables. Only threads may lo