doc/html/ref/io-serial-testing-with-serfilter.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Serial testing with ser_filter</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="How to Write a Driver"
  23 HREF="io-how-to-write-a-driver.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="How to Write a Driver"
  26 HREF="io-how-to-write-a-driver.html"><LINK
  27 REL="NEXT"
  28 TITLE="Device Driver Interface to the Kernel"
  29 HREF="devapi-device-driver-interface-to-the-kernel.html"></HEAD
  30 ><BODY
  31 CLASS="SECTION"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="io-how-to-write-a-driver.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 17. How to Write a Driver</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="devapi-device-driver-interface-to-the-kernel.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECTION"
  82 ><H1
  83 CLASS="SECTION"
  84 ><A
  85 NAME="IO-SERIAL-TESTING-WITH-SERFILTER">Serial testing with ser_filter</H1
  86 ><DIV
  87 CLASS="SECTION"
  88 ><H2
  89 CLASS="SECTION"
  90 ><A
  91 NAME="IO-SERFILTER-RATIONALE">Rationale</H2
  92 ><P
  93 >Since some targets only have one serial connection, a serial testing harness
  94 needs to be able to share the connection with <SPAN
  95 CLASS="APPLICATION"
  96 >GDB</SPAN
  97 >
  98 (however, the test and <SPAN
  99 CLASS="APPLICATION"
 100 >GDB</SPAN
 101 > can also run on separate
 102 lines).</P
 103 ><P
 104 >The <I
 105 CLASS="FIRSTTERM"
 106 >serial filter</I
 107 > (<SPAN
 108 CLASS="APPLICATION"
 109 >ser_filter</SPAN
 110 >)
 111 sits between the serial port and <SPAN
 112 CLASS="APPLICATION"
 113 >GDB</SPAN
 114 > and monitors
 115 the exchange of data between <SPAN
 116 CLASS="APPLICATION"
 117 >GDB</SPAN
 118 > and the target.
 119 Normally, no changes are made to the data.</P
 120 ><P
 121 >When a test request packet is sent from the test on the target, it is
 122 intercepted by the filter.</P
 123 ><P
 124 >The filter and target then enter a loop, exchanging protocol data between
 125 them which <SPAN
 126 CLASS="APPLICATION"
 127 >GDB</SPAN
 128 > never sees.</P
 129 ><P
 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
 133 CLASS="APPLICATION"
 134 >GDB</SPAN
 135 >. The
 136 filter will stay in the pass-though mode until <SPAN
 137 CLASS="APPLICATION"
 138 >GDB</SPAN
 139 >
 140 disconnects.</P
 141 ></DIV
 142 ><DIV
 143 CLASS="SECTION"
 144 ><H2
 145 CLASS="SECTION"
 146 ><A
 147 NAME="IO-SERFILTER-PROTOCOL">The Protocol</H2
 148 ><P
 149 >The protocol commands are prefixed with an <TT
 150 CLASS="LITERAL"
 151 >&quot;@&quot;</TT
 152 >
 153 character which the serial filter is looking for. The protocol
 154 commands include:</P
 155 ><P
 156 ></P
 157 ><DIV
 158 CLASS="VARIABLELIST"
 159 ><DL
 160 ><DT
 161 ><TT
 162 CLASS="LITERAL"
 163 >PING</TT
 164 ></DT
 165 ><DD
 166 ><P
 167 >Allows the test on the target to probe for the filter. The
 168       filter responds with <TT
 169 CLASS="LITERAL"
 170 >OK</TT
 171 >, while
 172       <SPAN
 173 CLASS="APPLICATION"
 174 >GDB</SPAN
 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
 178 ></DD
 179 ><DT
 180 ><TT
 181 CLASS="LITERAL"
 182 >CONFIG</TT
 183 ></DT
 184 ><DD
 185 ><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
 191 ></DD
 192 ><DT
 193 ><TT
 194 CLASS="LITERAL"
 195 >BINARY</TT
 196 ></DT
 197 ><DD
 198 ><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
 203 ><P
 204 ></P
 205 ><DIV
 206 CLASS="VARIABLELIST"
 207 ><DL
 208 ><DT
 209 ><TT
 210 CLASS="LITERAL"
 211 >NO_ECHO</TT
 212 ></DT
 213 ><DD
 214 ><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
 218 ></DD
 219 ><DT
 220 ><TT
 221 CLASS="LITERAL"
 222 >EOP_ECHO</TT
 223 ></DT
 224 ><DD
 225 ><P
 226 >(serial driver half-duplex receive and send test) As
 227             <TT
 228 CLASS="LITERAL"
 229 >NO_ECHO</TT
 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
 234             verifications.</P
 235 ></DD
 236 ><DT
 237 ><TT
 238 CLASS="LITERAL"
 239 >DUPLEX_ECHO</TT
 240 ></DT
 241 ><DD
 242 ><P
 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.
 248             </P
 249 ></DD
 250 ></DL
 251 ></DIV
 252 ></DD
 253 ><DT
 254 ><TT
 255 CLASS="LITERAL"
 256 >TEXT</TT
 257 ></DT
 258 ><DD
 259 ><P
 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.
 266       </P
 267 ></DD
 268 ></DL
 269 ></DIV
 270 ><P
 271 >The above commands may be extended, and new commands added, as
 272 required to test (new) parts of the serial drivers in
 273 <SPAN
 274 CLASS="PRODUCTNAME"
 275 >eCos</SPAN
 276 >.</P
 277 ></DIV
 278 ><DIV
 279 CLASS="SECTION"
 280 ><H2
 281 CLASS="SECTION"
 282 ><A
 283 NAME="IO-SERFILTER-SERIAL-TESTS">The Serial Tests</H2
 284 ><P
 285 >The serial tests are built as any other eCos test. After running the
 286 <B
 287 CLASS="COMMAND"
 288 >make tests</B
 289 > command, the tests can be found in
 290 <TT
 291 CLASS="FILENAME"
 292 >install/tests/io_serial/</TT
 293 ></P
 294 ><P
 295 ></P
 296 ><DIV
 297 CLASS="VARIABLELIST"
 298 ><DL
 299 ><DT
 300 ><TT
 301 CLASS="FILENAME"
 302 >serial1</TT
 303 ></DT
 304 ><DD
 305 ><P
 306 >A simple API test.</P
 307 ></DD
 308 ><DT
 309 ><TT
 310 CLASS="FILENAME"
 311 >serial2</TT
 312 ></DT
 313 ><DD
 314 ><P
 315 >A simple serial send test. It writes out two strings, one
 316       raw and one encoded as a <SPAN
 317 CLASS="APPLICATION"
 318 >GDB</SPAN
 319 >
 320       O-packet</P
 321 ></DD
 322 ><DT
 323 ><TT
 324 CLASS="FILENAME"
 325 >serial3</TT
 326 > [ requires the serial filter ]</DT
 327 ><DD
 328 ><P
 329 >This tests the half-duplex send and receive capabilities
 330       of the serial driver. </P
 331 ></DD
 332 ><DT
 333 ><TT
 334 CLASS="FILENAME"
 335 >serial4</TT
 336 > [ requires the serial filter ]</DT
 337 ><DD
 338 ><P
 339 >This test attempts to use a few different serial
 340       configurations, testing the driver's configuration/setup
 341       functionality. </P
 342 ></DD
 343 ><DT
 344 ><TT
 345 CLASS="FILENAME"
 346 >serial5</TT
 347 > [ requires the serial filter ]</DT
 348 ><DD
 349 ><P
 350 >This tests the duplex send and receive capabilities of the
 351       serial driver. </P
 352 ></DD
 353 ></DL
 354 ></DIV
 355 ><P
 356 >All tests should complete in less than 30 seconds.</P
 357 ></DIV
 358 ><DIV
 359 CLASS="SECTION"
 360 ><H2
 361 CLASS="SECTION"
 362 ><A
 363 NAME="IO-SERFILTER-USAGE">Serial Filter Usage</H2
 364 ><P
 365 >Running the ser_filter program with no (or wrong) arguments results in
 366 the following output:</P
 367 ><TABLE
 368 BORDER="5"
 369 BGCOLOR="#E0E0F0"
 370 WIDTH="70%"
 371 ><TR
 372 ><TD
 373 ><PRE
 374 CLASS="SCREEN"
 375 >Usage: ser_filter [-t -S] TcpIPport SerialPort BaudRate
 376 or: ser_filter -n [-t -S] SerialPort BaudRate
 377 -t: Enable tracing.
 378 -S: Output data read from serial line.
 379 -c: Output data on console instead of via GDB.
 380 -n: No GDB. </PRE
 381 ></TD
 382 ></TR
 383 ></TABLE
 384 ><P
 385 >The normal way to use it with GDB is to start the filter:</P
 386 ><TABLE
 387 BORDER="5"
 388 BGCOLOR="#E0E0F0"
 389 WIDTH="70%"
 390 ><TR
 391 ><TD
 392 ><PRE
 393 CLASS="SCREEN"
 394 >$ <TT
 395 CLASS="USERINPUT"
 396 ><B
 397 >ser_filter -t 9000 com1 38400</B
 398 ></TT
 399 ></PRE
 400 ></TD
 401 ></TR
 402 ></TABLE
 403 ><P
 404 >In this case, the filter will be listening on port 9000 and connect to the
 405 target via the serial port <TT
 406 CLASS="LITERAL"
 407 >COM1</TT
 408 > at 38400 baud. On a UNIX
 409 host, replace "<TT
 410 CLASS="LITERAL"
 411 >COM1</TT
 412 >" with a device such as
 413 "<TT
 414 CLASS="FILENAME"
 415 >/dev/ttyS0</TT
 416 >".</P
 417 ><P
 418 >The <TT
 419 CLASS="OPTION"
 420 >-t</TT
 421 > option enables tracing which will cause the
 422 filter to describe its actions on the console.</P
 423 ><P
 424 >Now start <SPAN
 425 CLASS="APPLICATION"
 426 >GDB</SPAN
 427 > with one of the tests as an
 428 argument:</P
 429 ><TABLE
 430 BORDER="5"
 431 BGCOLOR="#E0E0F0"
 432 WIDTH="70%"
 433 ><TR
 434 ><TD
 435 ><PRE
 436 CLASS="SCREEN"
 437 >$ <TT
 438 CLASS="USERINPUT"
 439 ><B
 440 >mips-tx39-elf-gdb -nw install/tests/io_serial/serial3</B
 441 ></TT
 442 ></PRE
 443 ></TD
 444 ></TR
 445 ></TABLE
 446 ><P
 447 >Then connect to the filter:</P
 448 ><TABLE
 449 BORDER="5"
 450 BGCOLOR="#E0E0F0"
 451 WIDTH="70%"
 452 ><TR
 453 ><TD
 454 ><PRE
 455 CLASS="SCREEN"
 456 >(gdb) <TT
 457 CLASS="USERINPUT"
 458 ><B
 459 >target remote localhost:9000</B
 460 ></TT
 461 ></PRE
 462 ></TD
 463 ></TR
 464 ></TABLE
 465 ><P
 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
 468 ><TABLE
 469 BORDER="5"
 470 BGCOLOR="#E0E0F0"
 471 WIDTH="70%"
 472 ><TR
 473 ><TD
 474 ><PRE
 475 CLASS="SCREEN"
 476 >(gdb) <TT
 477 CLASS="USERINPUT"
 478 ><B
 479 >c</B
 480 ></TT
 481 ></PRE
 482 ></TD
 483 ></TR
 484 ></TABLE
 485 ><P
 486 >Which should result in output similar to the below:</P
 487 ><TABLE
 488 BORDER="5"
 489 BGCOLOR="#E0E0F0"
 490 WIDTH="70%"
 491 ><TR
 492 ><TD
 493 ><PRE
 494 CLASS="SCREEN"
 495 >Continuing.
 496 INFO: &lt;BINARY:16:1!&gt;
 497 PASS: &lt;Binary test completed&gt;
 498 INFO: &lt;BINARY:128:1!&gt;
 499 PASS: &lt;Binary test completed&gt;
 500 INFO: &lt;BINARY:256:1!&gt;
 501 PASS: &lt;Binary test completed&gt;
 502 INFO: &lt;BINARY:1024:1!&gt;
 503 PASS: &lt;Binary test completed&gt;
 504 INFO: &lt;BINARY:512:0!&gt;
 505 PASS: &lt;Binary test completed&gt;
 506 ...
 507 PASS: &lt;Binary test completed&gt;
 508 INFO: &lt;BINARY:16384:0!&gt;
 509 PASS: &lt;Binary test completed&gt;
 510 PASS: &lt;serial13 test OK&gt;
 511 EXIT: &lt;done&gt;</PRE
 512 ></TD
 513 ></TR
 514 ></TABLE
 515 ><P
 516 >If any of the individual tests fail the testing will terminate with a
 517 <TT
 518 CLASS="COMPUTEROUTPUT"
 519 >FAIL</TT
 520 >.</P
 521 ><P
 522 >With tracing enabled, you would also see the filter's status output:</P
 523 ><P
 524 >The <TT
 525 CLASS="LITERAL"
 526 >PING</TT
 527 > command sent from the target to determine the
 528 presence of the filter:</P
 529 ><TABLE
 530 BORDER="5"
 531 BGCOLOR="#E0E0F0"
 532 WIDTH="70%"
 533 ><TR
 534 ><TD
 535 ><PRE
 536 CLASS="SCREEN"
 537 >[400 11:35:16] Dispatching command PING
 538 [400 11:35:16] Responding with status OK</PRE
 539 ></TD
 540 ></TR
 541 ></TABLE
 542 ><P
 543 >Each of the binary commands result in output similar to:</P
 544 ><TABLE
 545 BORDER="5"
 546 BGCOLOR="#E0E0F0"
 547 WIDTH="70%"
 548 ><TR
 549 ><TD
 550 ><PRE
 551 CLASS="SCREEN"
 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
 559 ></TD
 560 ></TR
 561 ></TABLE
 562 ><P
 563 >This tracing output is normally sent as O-packets to <SPAN
 564 CLASS="APPLICATION"
 565 >GDB</SPAN
 566 > which will display the tracing text. By using the
 567 <TT
 568 CLASS="OPTION"
 569 >-c </TT
 570 > option, the tracing text can be redirected to the
 571 console from which ser_filter was started.</P
 572 ></DIV
 573 ><DIV
 574 CLASS="SECTION"
 575 ><H2
 576 CLASS="SECTION"
 577 ><A
 578 NAME="IO-SERFILTER-FAILURES">A Note on Failures</H2
 579 ><P
 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
 584 ><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"
 589 >FAIL</TT
 590 >). It also
 591 means that you should be aware of random errors - a <TT
 592 CLASS="COMPUTEROUTPUT"
 593 >FAIL</TT
 594 > is not necessarily caused by a bug in the serial driver.</P
 595 ><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
 600 capability.</P
 601 ></DIV
 602 ><DIV
 603 CLASS="SECTION"
 604 ><H2
 605 CLASS="SECTION"
 606 ><A
 607 NAME="IO-SERFILTER-DEBUGGING">Debugging</H2
 608 ><P
 609 >If a test fails, the serial filter's output may provide some hints about
 610 what the problem is. If the option <TT
 611 CLASS="OPTION"
 612 >-S</TT
 613 > is used when starting
 614 the filter, data received from the target is printed out: </P
 615 ><TABLE
 616 BORDER="5"
 617 BGCOLOR="#E0E0F0"
 618 WIDTH="70%"
 619 ><TR
 620 ><TD
 621 ><PRE
 622 CLASS="SCREEN"
 623 >[400 11:35:16] 0000 50 41 53 53 3a 3c 42 69 'PASS:&lt;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&gt;..IN'
 627 [400 11:35:16] 0020 46 4f 3a 3c 42 49 4e 41 'FO:&lt;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
 632 ></TD
 633 ></TR
 634 ></TABLE
 635 ><P
 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
 639 is.</P
 640 ></DIV
 641 ></DIV
 642 ><DIV
 643 CLASS="NAVFOOTER"
 644 ><HR
 645 ALIGN="LEFT"
 646 WIDTH="100%"><TABLE
 647 SUMMARY="Footer navigation table"
 648 WIDTH="100%"
 649 BORDER="0"
 650 CELLPADDING="0"
 651 CELLSPACING="0"
 652 ><TR
 653 ><TD
 654 WIDTH="33%"
 655 ALIGN="left"
 656 VALIGN="top"
 657 ><A
 658 HREF="io-how-to-write-a-driver.html"
 659 ACCESSKEY="P"
 660 >Prev</A
 661 ></TD
 662 ><TD
 663 WIDTH="34%"
 664 ALIGN="center"
 665 VALIGN="top"
 666 ><A
 667 HREF="ecos-ref.html"
 668 ACCESSKEY="H"
 669 >Home</A
 670 ></TD
 671 ><TD
 672 WIDTH="33%"
 673 ALIGN="right"
 674 VALIGN="top"
 675 ><A
 676 HREF="devapi-device-driver-interface-to-the-kernel.html"
 677 ACCESSKEY="N"
 678 >Next</A
 679 ></TD
 680 ></TR
 681 ><TR
 682 ><TD
 683 WIDTH="33%"
 684 ALIGN="left"
 685 VALIGN="top"
 686 >How to Write a Driver</TD
 687 ><TD
 688 WIDTH="34%"
 689 ALIGN="center"
 690 VALIGN="top"
 691 ><A
 692 HREF="io-how-to-write-a-driver.html"
 693 ACCESSKEY="U"
 694 >Up</A
 695 ></TD
 696 ><TD
 697 WIDTH="33%"
 698 ALIGN="right"
 699 VALIGN="top"
 700 >Device Driver Interface to the Kernel</TD
 701 ></TR
 702 ></TABLE
 703 ></DIV
 704 ></BODY
 705 ></HTML
 706 >