URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [io-serial-testing-with-serfilter.html] - Rev 598
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- 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 >
Go to most recent revision | Compare with Previous | Blame | View Log