+<!-- Copyright (C) 2003 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/). -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>Serial testing with ser_filter</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE="How to Write a Driver"
+HREF="io-how-to-write-a-driver.html"><LINK
+REL="PREVIOUS"
+TITLE="How to Write a Driver"
+HREF="io-how-to-write-a-driver.html"><LINK
+REL="NEXT"
+TITLE="Device Driver Interface to the Kernel"
+HREF="devapi-device-driver-interface-to-the-kernel.html"></HEAD
+><BODY
+CLASS="SECTION"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="io-how-to-write-a-driver.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 17. How to Write a Driver</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="devapi-device-driver-interface-to-the-kernel.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="IO-SERIAL-TESTING-WITH-SERFILTER">Serial testing with ser_filter</H1
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-RATIONALE">Rationale</H2
+><P
+>Since some targets only have one serial connection, a serial testing harness
+needs to be able to share the connection with <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+>
+(however, the test and <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> can also run on separate
+lines).</P
+><P
+>The <I
+CLASS="FIRSTTERM"
+>serial filter</I
+> (<SPAN
+CLASS="APPLICATION"
+>ser_filter</SPAN
+>)
+sits between the serial port and <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> and monitors
+the exchange of data between <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> and the target.
+Normally, no changes are made to the data.</P
+><P
+>When a test request packet is sent from the test on the target, it is
+intercepted by the filter.</P
+><P
+>The filter and target then enter a loop, exchanging protocol data between
+them which <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> never sees.</P
+><P
+>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 <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+>. The
+filter will stay in the pass-though mode until <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+>
+disconnects.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-PROTOCOL">The Protocol</H2
+><P
+>The protocol commands are prefixed with an <TT
+CLASS="LITERAL"
+>"@"</TT
+>
+character which the serial filter is looking for. The protocol
+commands include:</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+><TT
+CLASS="LITERAL"
+>PING</TT
+></DT
+><DD
+><P
+>Allows the test on the target to probe for the filter. The
+ filter responds with <TT
+CLASS="LITERAL"
+>OK</TT
+>, while
+ <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> would just ignore the
+ command. This allows the tests to do nothing if they require the
+ filter and it is not present.</P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>CONFIG</TT
+></DT
+><DD
+><P
+>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.]</P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>BINARY</TT
+></DT
+><DD
+><P
+>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:</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+><TT
+CLASS="LITERAL"
+>NO_ECHO</TT
+></DT
+><DD
+><P
+>(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. </P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>EOP_ECHO</TT
+></DT
+><DD
+><P
+>(serial driver half-duplex receive and send test) As
+ <TT
+CLASS="LITERAL"
+>NO_ECHO</TT
+> 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.</P
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>DUPLEX_ECHO</TT
+></DT
+><DD
+><P
+>(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.
+ </P
+></DD
+></DL
+></DIV
+></DD
+><DT
+><TT
+CLASS="LITERAL"
+>TEXT</TT
+></DT
+><DD
+><P
+> 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.
+ </P
+></DD
+></DL
+></DIV
+><P
+>The above commands may be extended, and new commands added, as
+required to test (new) parts of the serial drivers in
+<SPAN
+CLASS="PRODUCTNAME"
+>eCos</SPAN
+>.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-SERIAL-TESTS">The Serial Tests</H2
+><P
+>The serial tests are built as any other eCos test. After running the
+<B
+CLASS="COMMAND"
+>make tests</B
+> command, the tests can be found in
+<TT
+CLASS="FILENAME"
+>install/tests/io_serial/</TT
+></P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+><TT
+CLASS="FILENAME"
+>serial1</TT
+></DT
+><DD
+><P
+>A simple API test.</P
+></DD
+><DT
+><TT
+CLASS="FILENAME"
+>serial2</TT
+></DT
+><DD
+><P
+>A simple serial send test. It writes out two strings, one
+ raw and one encoded as a <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+>
+ O-packet</P
+></DD
+><DT
+><TT
+CLASS="FILENAME"
+>serial3</TT
+> [ requires the serial filter ]</DT
+><DD
+><P
+>This tests the half-duplex send and receive capabilities
+ of the serial driver. </P
+></DD
+><DT
+><TT
+CLASS="FILENAME"
+>serial4</TT
+> [ requires the serial filter ]</DT
+><DD
+><P
+>This test attempts to use a few different serial
+ configurations, testing the driver's configuration/setup
+ functionality. </P
+></DD
+><DT
+><TT
+CLASS="FILENAME"
+>serial5</TT
+> [ requires the serial filter ]</DT
+><DD
+><P
+>This tests the duplex send and receive capabilities of the
+ serial driver. </P
+></DD
+></DL
+></DIV
+><P
+>All tests should complete in less than 30 seconds.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-USAGE">Serial Filter Usage</H2
+><P
+>Running the ser_filter program with no (or wrong) arguments results in
+the following output:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="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. </PRE
+></TD
+></TR
+></TABLE
+><P
+>The normal way to use it with GDB is to start the filter:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>$ <TT
+CLASS="USERINPUT"
+><B
+>ser_filter -t 9000 com1 38400</B
+></TT
+></PRE
+></TD
+></TR
+></TABLE
+><P
+>In this case, the filter will be listening on port 9000 and connect to the
+target via the serial port <TT
+CLASS="LITERAL"
+>COM1</TT
+> at 38400 baud. On a UNIX
+host, replace "<TT
+CLASS="LITERAL"
+>COM1</TT
+>" with a device such as
+"<TT
+CLASS="FILENAME"
+>/dev/ttyS0</TT
+>".</P
+><P
+>The <TT
+CLASS="OPTION"
+>-t</TT
+> option enables tracing which will cause the
+filter to describe its actions on the console.</P
+><P
+>Now start <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> with one of the tests as an
+argument:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>$ <TT
+CLASS="USERINPUT"
+><B
+>mips-tx39-elf-gdb -nw install/tests/io_serial/serial3</B
+></TT
+></PRE
+></TD
+></TR
+></TABLE
+><P
+>Then connect to the filter:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>(gdb) <TT
+CLASS="USERINPUT"
+><B
+>target remote localhost:9000</B
+></TT
+></PRE
+></TD
+></TR
+></TABLE
+><P
+>This should result in a connection in exactly the same way as if you
+had connected directly to the target on the serial line.</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>(gdb) <TT
+CLASS="USERINPUT"
+><B
+>c</B
+></TT
+></PRE
+></TD
+></TR
+></TABLE
+><P
+>Which should result in output similar to the below:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>Continuing.
+INFO: <BINARY:16:1!>
+PASS: <Binary test completed>
+INFO: <BINARY:128:1!>
+PASS: <Binary test completed>
+INFO: <BINARY:256:1!>
+PASS: <Binary test completed>
+INFO: <BINARY:1024:1!>
+PASS: <Binary test completed>
+INFO: <BINARY:512:0!>
+PASS: <Binary test completed>
+...
+PASS: <Binary test completed>
+INFO: <BINARY:16384:0!>
+PASS: <Binary test completed>
+PASS: <serial13 test OK>
+EXIT: <done></PRE
+></TD
+></TR
+></TABLE
+><P
+>If any of the individual tests fail the testing will terminate with a
+<TT
+CLASS="COMPUTEROUTPUT"
+>FAIL</TT
+>.</P
+><P
+>With tracing enabled, you would also see the filter's status output:</P
+><P
+>The <TT
+CLASS="LITERAL"
+>PING</TT
+> command sent from the target to determine the
+presence of the filter:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>[400 11:35:16] Dispatching command PING
+[400 11:35:16] Responding with status OK</PRE
+></TD
+></TR
+></TABLE
+><P
+>Each of the binary commands result in output similar to:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="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.</PRE
+></TD
+></TR
+></TABLE
+><P
+>This tracing output is normally sent as O-packets to <SPAN
+CLASS="APPLICATION"
+>GDB</SPAN
+> which will display the tracing text. By using the
+<TT
+CLASS="OPTION"
+>-c </TT
+> option, the tracing text can be redirected to the
+console from which ser_filter was started.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-FAILURES">A Note on Failures</H2
+><P
+>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. </P
+><P
+>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 <TT
+CLASS="COMPUTEROUTPUT"
+>FAIL</TT
+>). It also
+means that you should be aware of random errors - a <TT
+CLASS="COMPUTEROUTPUT"
+>FAIL</TT
+> is not necessarily caused by a bug in the serial driver.</P
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="IO-SERFILTER-DEBUGGING">Debugging</H2
+><P
+>If a test fails, the serial filter's output may provide some hints about
+what the problem is. If the option <TT
+CLASS="OPTION"
+>-S</TT
+> is used when starting
+the filter, data received from the target is printed out: </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="SCREEN"
+>[400 11:35:16] 0000 50 41 53 53 3a 3c 42 69 'PASS:<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>..IN'
+[400 11:35:16] 0020 46 4f 3a 3c 42 49 4e 41 'FO:<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!' </PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="io-how-to-write-a-driver.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="devapi-device-driver-interface-to-the-kernel.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>How to Write a Driver</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="io-how-to-write-a-driver.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Device Driver Interface to the Kernel</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff