1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Serial testing with ser_filter</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="How to Write a Driver"
23 HREF="io-how-to-write-a-driver.html"><LINK
25 TITLE="How to Write a Driver"
26 HREF="io-how-to-write-a-driver.html"><LINK
28 TITLE="Device Driver Interface to the Kernel"
29 HREF="devapi-device-driver-interface-to-the-kernel.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="io-how-to-write-a-driver.html"
65 >Chapter 17. How to Write a Driver</TD
71 HREF="devapi-device-driver-interface-to-the-kernel.html"
85 NAME="IO-SERIAL-TESTING-WITH-SERFILTER">Serial testing with ser_filter</H1
91 NAME="IO-SERFILTER-RATIONALE">Rationale</H2
93 >Since some targets only have one serial connection, a serial testing harness
94 needs to be able to share the connection with <SPAN
98 (however, the test and <SPAN
101 > can also run on separate
111 sits between the serial port and <SPAN
115 the exchange of data between <SPAN
119 Normally, no changes are made to the data.</P
121 >When a test request packet is sent from the test on the target, it is
122 intercepted by the filter.</P
124 >The filter and target then enter a loop, exchanging protocol data between
130 >In the event of a timeout, or a crash on the target, the filter falls
131 back into its pass-through mode. If this happens due to a crash it should be
132 possible to start regular debugging with <SPAN
136 filter will stay in the pass-though mode until <SPAN
147 NAME="IO-SERFILTER-PROTOCOL">The Protocol</H2
149 >The protocol commands are prefixed with an <TT
153 character which the serial filter is looking for. The protocol
167 >Allows the test on the target to probe for the filter. The
168 filter responds with <TT
175 > would just ignore the
176 command. This allows the tests to do nothing if they require the
177 filter and it is not present.</P
186 >Requests a change of serial line configuration. Arguments
187 to the command specify baud rate, data bits, stop bits, and
188 parity. [This command is not fully implemented yet - there is no
189 attempt made to recover if the new configuration turns out to
190 cause loss of data.]</P
199 >Requests data to be sent from the filter to the
200 target. The data is checksummed, allowing errors in the transfer
201 to be detected. Sub-options of this command control how the
202 data transfer is made:</P
215 >(serial driver receive test) Just send data from the
216 filter to the target. The test verifies the checksum and
217 PASS/FAIL depending on the result. </P
226 >(serial driver half-duplex receive and send test) As
230 > but the test echoes back the
231 data to the filter. The filter does a checksum on the
232 received data and sends the result to the target. The test
233 PASS/FAIL depending on the result of both checksum
243 >(serial driver duplex receive and send test) Smaller
244 packets of data are sent back and forth in a pattern that
245 ensures that the serial driver will be both sending and
246 receiving at the same time. Again, checksums are computed
247 and verified resulting in PASS/FAIL.
260 > This is a test of the text translations in the TTY layer.
261 Requests a transfer of text data from the target to the filter
262 and possibly back again. The filter treats this as a binary
263 transfer, while the target ma be doing translations on the
264 data. The target provides the filter with checksums for what it
265 should expect to see. This test is not implemented yet.
271 >The above commands may be extended, and new commands added, as
272 required to test (new) parts of the serial drivers in
283 NAME="IO-SERFILTER-SERIAL-TESTS">The Serial Tests</H2
285 >The serial tests are built as any other eCos test. After running the
289 > command, the tests can be found in
292 >install/tests/io_serial/</TT
306 >A simple API test.</P
315 >A simple serial send test. It writes out two strings, one
316 raw and one encoded as a <SPAN
326 > [ requires the serial filter ]</DT
329 >This tests the half-duplex send and receive capabilities
330 of the serial driver. </P
336 > [ requires the serial filter ]</DT
339 >This test attempts to use a few different serial
340 configurations, testing the driver's configuration/setup
347 > [ requires the serial filter ]</DT
350 >This tests the duplex send and receive capabilities of the
356 >All tests should complete in less than 30 seconds.</P
363 NAME="IO-SERFILTER-USAGE">Serial Filter Usage</H2
365 >Running the ser_filter program with no (or wrong) arguments results in
366 the following output:</P
375 >Usage: ser_filter [-t -S] TcpIPport SerialPort BaudRate
376 or: ser_filter -n [-t -S] SerialPort BaudRate
378 -S: Output data read from serial line.
379 -c: Output data on console instead of via GDB.
385 >The normal way to use it with GDB is to start the filter:</P
397 >ser_filter -t 9000 com1 38400</B
404 >In this case, the filter will be listening on port 9000 and connect to the
405 target via the serial port <TT
408 > at 38400 baud. On a UNIX
412 >" with a device such as
421 > option enables tracing which will cause the
422 filter to describe its actions on the console.</P
427 > with one of the tests as an
440 >mips-tx39-elf-gdb -nw install/tests/io_serial/serial3</B
447 >Then connect to the filter:</P
459 >target remote localhost:9000</B
466 >This should result in a connection in exactly the same way as if you
467 had connected directly to the target on the serial line.</P
486 >Which should result in output similar to the below:</P
496 INFO: <BINARY:16:1!>
497 PASS: <Binary test completed>
498 INFO: <BINARY:128:1!>
499 PASS: <Binary test completed>
500 INFO: <BINARY:256:1!>
501 PASS: <Binary test completed>
502 INFO: <BINARY:1024:1!>
503 PASS: <Binary test completed>
504 INFO: <BINARY:512:0!>
505 PASS: <Binary test completed>
507 PASS: <Binary test completed>
508 INFO: <BINARY:16384:0!>
509 PASS: <Binary test completed>
510 PASS: <serial13 test OK>
511 EXIT: <done></PRE
516 >If any of the individual tests fail the testing will terminate with a
518 CLASS="COMPUTEROUTPUT"
522 >With tracing enabled, you would also see the filter's status output:</P
527 > command sent from the target to determine the
528 presence of the filter:</P
537 >[400 11:35:16] Dispatching command PING
538 [400 11:35:16] Responding with status OK</PRE
543 >Each of the binary commands result in output similar to:</P
552 >[400 11:35:16] Dispatching command BINARY
553 [400 11:35:16] Binary data (Size:16, Flags:1).
554 [400 11:35:16] Sending CRC: '170231!', len: 7.
555 [400 11:35:16] Reading 16 bytes from target.
556 [400 11:35:16] Done. in_crc 170231, out_crc 170231.
557 [400 11:35:16] Responding with status OK
558 [400 11:35:16] Received DONE from target.</PRE
563 >This tracing output is normally sent as O-packets to <SPAN
566 > which will display the tracing text. By using the
570 > option, the tracing text can be redirected to the
571 console from which ser_filter was started.</P
578 NAME="IO-SERFILTER-FAILURES">A Note on Failures</H2
580 >A serial connection (especially when driven at a high baud rate) can garble the
581 transmitted data because of noise from the environment. It is not the job of
582 the serial driver to ensure data integrity - that is the job of protocols
583 layering on top of the serial driver. </P
585 >In the current implementation the serial tests and the serial filter are
586 not resilient to such data errors. This means that the test may crash or hang
587 (possibly without reporting a <TT
588 CLASS="COMPUTEROUTPUT"
591 means that you should be aware of random errors - a <TT
592 CLASS="COMPUTEROUTPUT"
594 > is not necessarily caused by a bug in the serial driver.</P
596 >Ideally, the serial testing infrastructure should be able to distinguish
597 random errors from consistent errors - the former are most likely due to noise
598 in the transfer medium, while the latter are more likely to be caused by faulty
599 drivers. The current implementation of the infrastructure does not have this
607 NAME="IO-SERFILTER-DEBUGGING">Debugging</H2
609 >If a test fails, the serial filter's output may provide some hints about
610 what the problem is. If the option <TT
613 > is used when starting
614 the filter, data received from the target is printed out: </P
623 >[400 11:35:16] 0000 50 41 53 53 3a 3c 42 69 'PASS:<Bi'
624 [400 11:35:16] 0008 6e 61 72 79 20 74 65 73 'nary.tes'
625 [400 11:35:16] 0010 74 20 63 6f 6d 70 6c 65 't.comple'
626 [400 11:35:16] 0018 74 65 64 3e 0d 0a 49 4e 'ted>..IN'
627 [400 11:35:16] 0020 46 4f 3a 3c 42 49 4e 41 'FO:<BINA'
628 [400 11:35:16] 0028 52 59 3a 31 32 38 3a 31 'RY:128:1'
629 [400 11:35:16] 0030 21 3e 0d 0a 40 42 49 4e '!..@BIN'
630 [400 11:35:16] 0038 41 52 59 3a 31 32 38 3a 'ARY:128:'
631 [400 11:35:16] 0040 31 21 .. .. .. .. .. .. '1!' </PRE
636 >In the case of an error during a testing command the data received by the
637 filter will be printed out, as will the data that was expected. This allows
638 the two data sets to be compared which may give some idea of what the problem
647 SUMMARY="Footer navigation table"
658 HREF="io-how-to-write-a-driver.html"
676 HREF="devapi-device-driver-interface-to-the-kernel.html"
686 >How to Write a Driver</TD
692 HREF="io-how-to-write-a-driver.html"
700 >Device Driver Interface to the Kernel</TD