unified MX27, MX25, MX37 trees
[karo-tx-redboot.git] / packages / io / usb / slave / v2_0 / doc / usbs-testing.html
1 <!-- Copyright (C) 2002 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 substantively modified versions of this         -->
7 <!-- document is prohibited without the explicit permission of the   -->
8 <!-- copyright holder.                                               -->
9 <!-- Distribution of the work or derivative of the work in any       -->
10 <!-- standard (paper) book form is prohibited unless prior           -->
11 <!-- permission is obtained from the copyright holder.               -->
12 <HTML
13 ><HEAD
14 ><TITLE
15 >Testing</TITLE
16 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
17 <META
18 NAME="GENERATOR"
19 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
20 "><LINK
21 REL="HOME"
22 TITLE="eCos USB Slave Support"
23 HREF="io-usb-slave.html"><LINK
24 REL="PREVIOUS"
25 TITLE="Writing a USB Device Driver"
26 HREF="usbs-writing.html"></HEAD
27 ><BODY
28 CLASS="REFENTRY"
29 BGCOLOR="#FFFFFF"
30 TEXT="#000000"
31 LINK="#0000FF"
32 VLINK="#840084"
33 ALINK="#0000FF"
34 ><DIV
35 CLASS="NAVHEADER"
36 ><TABLE
37 WIDTH="100%"
38 BORDER="0"
39 CELLPADDING="0"
40 CELLSPACING="0"
41 ><TR
42 ><TH
43 COLSPAN="3"
44 ALIGN="center"
45 >eCos USB Slave Support</TH
46 ></TR
47 ><TR
48 ><TD
49 WIDTH="10%"
50 ALIGN="left"
51 VALIGN="bottom"
52 ><A
53 HREF="usbs-writing.html"
54 >Prev</A
55 ></TD
56 ><TD
57 WIDTH="80%"
58 ALIGN="center"
59 VALIGN="bottom"
60 ></TD
61 ><TD
62 WIDTH="10%"
63 ALIGN="right"
64 VALIGN="bottom"
65 >&nbsp;</TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><H1
72 ><A
73 NAME="USBS-TESTING"
74 >Testing</A
75 ></H1
76 ><DIV
77 CLASS="REFNAMEDIV"
78 ><A
79 NAME="AEN831"
80 ></A
81 ><H2
82 >Name</H2
83 >Testing&nbsp;--&nbsp;Testing of USB Device Drivers</DIV
84 ><DIV
85 CLASS="REFSECT1"
86 ><A
87 NAME="AEN834"
88 ></A
89 ><H2
90 >Introduction</H2
91 ><P
92 >The support for USB testing provided by the eCos USB common slave
93 package is somewhat different in nature from the kind of testing used
94 in many other packages. One obvious problem is that USB tests cannot
95 be run on just a bare target platform: instead the target platform
96 must be connected to a suitable USB host machine, and that host
97 machine must be running appropriate software for the test code to
98 interact with. This is very different from say a kernel test which
99 typically will have no external dependencies. Another important
100 difference between USB testing and say a C library
101 <TT
102 CLASS="FUNCTION"
103 >strcmp</TT
104 > test is sensitivity to timing and to
105 hardware boundary conditions: although a simple test case that just
106 performs a small number of USB transfers is better than no testing at
107 all, it should also be possible to run tests for hours or days on end,
108 under a variety of loads. In order to provide the required
109 functionality the basic architecture of the USB testing support is as
110 follows: </P
111 ><P
112 ></P
113 ><OL
114 TYPE="1"
115 ><LI
116 ><P
117 >    There is a single target-side program
118     <SPAN
119 CLASS="APPLICATION"
120 >usbtarget</SPAN
121 >. By default when this is run
122     on a target platform it will appear to do nothing. In fact it is
123     waiting to be contacted by another program
124     <SPAN
125 CLASS="APPLICATION"
126 >usbhost</SPAN
127 > which will tell it what test or
128     tests to run. <SPAN
129 CLASS="APPLICATION"
130 >usbtarget</SPAN
131 > provides
132     mechanisms for running a wide range of tests.
133   </P
134 ></LI
135 ><LI
136 ><P
137 >    <SPAN
138 CLASS="APPLICATION"
139 >usbtarget</SPAN
140 > is a generic program, but USB
141     testing depends to some extent on the functionality provided by the
142     hardware. For example there is no point in testing bulk transmits
143     to endpoint 12 if the target hardware does not support an endpoint
144     12. Therefore each USB device driver should supply information about
145     what the hardware is actually capable of, in the form of an array of
146     <SPAN
147 CLASS="STRUCTNAME"
148 >usbs_testing_endpoint</SPAN
149 > data structures.
150   </P
151 ></LI
152 ><LI
153 ><P
154 >    There is a single host-side program
155     <SPAN
156 CLASS="APPLICATION"
157 >usbhost</SPAN
158 >, which acts as a counterpart to
159     <SPAN
160 CLASS="APPLICATION"
161 >usbtarget</SPAN
162 >. Again
163     <SPAN
164 CLASS="APPLICATION"
165 >usbhost</SPAN
166 > has no built-in knowledge of
167     the test or tests that are supposed to run, it only provides
168     mechanisms for running a wide range of tests. On start-up
169     <SPAN
170 CLASS="APPLICATION"
171 >usbhost</SPAN
172 > will search the USB bus for
173     hardware running the target-side program, specifically a USB device
174     that identifies itself as the product <TT
175 CLASS="LITERAL"
176 >&quot;Red Hat eCos
177     USB test&quot;</TT
178 >.
179   </P
180 ></LI
181 ><LI
182 ><P
183 >    <SPAN
184 CLASS="APPLICATION"
185 >usbhost</SPAN
186 > contains a Tcl interpreter, and
187     will execute any Tcl scripts specified on the command line
188     together with appropriate arguments. The Tcl interpreter has been
189     extended with various commands such as
190     <TT
191 CLASS="LITERAL"
192 >usbtest::bulktest</TT
193 >, so the script can perform
194     the desired test or tests.
195   </P
196 ></LI
197 ><LI
198 ><P
199 >    Adding a new test simply involves writing a short Tcl script that
200     invokes the appropriate USB-specific commands. Running multiple
201     tests involves passing appropriate arguments to
202     <SPAN
203 CLASS="APPLICATION"
204 >usbhost</SPAN
205 >, or alternatively writing a
206     single script that just invokes other scripts.
207   </P
208 ></LI
209 ></OL
210 ><P
211 >The current implementation of <SPAN
212 CLASS="APPLICATION"
213 >usbhost</SPAN
214 >
215 depends heavily on functionality provided by the Linux kernel and in
216 particular the usbdevfs support. It uses
217 <TT
218 CLASS="FILENAME"
219 >/proc/bus/usb/devices</TT
220 > to find out what devices
221 are attached to the bus, and will then access the device by opening
222 <TT
223 CLASS="FILENAME"
224 >/proc/bus/usb/xxx/yyy</TT
225 > and performing
226 <TT
227 CLASS="FUNCTION"
228 >ioctl</TT
229 > operations. This allows USB testing to take
230 place without having to write a new host-side device driver, but
231 getting the code working on host machines not running Linux would
232 obviously be problematical.</P
233 ></DIV
234 ><DIV
235 CLASS="REFSECT1"
236 ><A
237 NAME="AEN867"
238 ></A
239 ><H2
240 >Building and Running the Target-side Code</H2
241 ><P
242 >The target-side component of the USB testing software consists of a
243 single program <SPAN
244 CLASS="APPLICATION"
245 >usbtarget</SPAN
246 > which contains
247 support for a range of different tests, under the control of host-side
248 software. This program is not built by default alongside other eCos
249 test cases since it will only operate in certain environments,
250 specifically when the target board's connector is plugged into a Linux
251 host, and when the appropriate host-side software has been installed
252 on that host. Instead the user must enable a configuration option
253 <TT
254 CLASS="LITERAL"
255 >CYGBLD_IO_USB_SLAVE_USBTEST</TT
256 > to add the program to
257 the list of tests for the current configuration.</P
258 ><P
259 >Starting the <SPAN
260 CLASS="APPLICATION"
261 >usbtarget</SPAN
262 > program does not
263 require anything unusual, so it can be run in a normal
264 <SPAN
265 CLASS="APPLICATION"
266 >gdb</SPAN
267 > session just like any eCos application.
268 After initialization the program will wait for activity from the host.
269 Depending on the hardware, the Linux host will detect that a new USB
270 peripheral is present on the bus either when the
271 <SPAN
272 CLASS="APPLICATION"
273 >usbtarget</SPAN
274 > initialization is complete or
275 when the cable between target and host is connected. The host will
276 perform the normal USB enumeration sequence and discover that the
277 peripheral does not match any known vendor or product id and that
278 there is no device driver for <TT
279 CLASS="LITERAL"
280 >&quot;Red Hat eCos USB
281 test&quot;</TT
282 >, so it will ignore the peripheral. When the
283 <SPAN
284 CLASS="APPLICATION"
285 >usbhost</SPAN
286 > program is run on the host it will
287 connect to the target-side software, and testing can now commence.</P
288 ></DIV
289 ><DIV
290 CLASS="REFSECT1"
291 ><A
292 NAME="AEN878"
293 ></A
294 ><H2
295 >Building and Running the Host-side Code</H2
296 ><DIV
297 CLASS="NOTE"
298 ><BLOCKQUOTE
299 CLASS="NOTE"
300 ><P
301 ><B
302 >Note: </B
303 >In theory the host-side software should be built when the package is
304 installed in the component repository, and removed when a package
305 is uninstalled. The current eCos administration tool does not provide
306 this functionality.</P
307 ></BLOCKQUOTE
308 ></DIV
309 ><P
310 >The host-side software should be built via the usual sequence of
311 &quot;configure/make/make install&quot;. It can only be built on a
312 Linux host and the <B
313 CLASS="COMMAND"
314 >configure</B
315 > script contains an
316 explicit test for this. Because the eCos component repository should
317 generally be treated as a read-only resource the configure script will
318 also prevent you from trying to build inside the source tree. Instead
319 a separate build tree is required. Hence a typical sequence for
320 building the host-side software would be as follows:</P
321 ><TABLE
322 BORDER="0"
323 BGCOLOR="#E0E0E0"
324 WIDTH="100%"
325 ><TR
326 ><TD
327 ><PRE
328 CLASS="SCREEN"
329 >$ mkdir usbhost_build
330 $ cd usbhost_build
331 $ &lt;repo&gt;packages/io/usb/slave/current/host/configure <A
332 NAME="PATH"
333 ><IMG
334 SRC="../images/callouts/1.gif"
335 HSPACE="0"
336 VSPACE="0"
337 BORDER="0"
338 ALT="(1)"></A
339 > <A
340 NAME="VERSION"
341 ><IMG
342 SRC="../images/callouts/2.gif"
343 HSPACE="0"
344 VSPACE="0"
345 BORDER="0"
346 ALT="(2)"></A
347 > &lt;args&gt; <A
348 NAME="ARGS"
349 ><IMG
350 SRC="../images/callouts/3.gif"
351 HSPACE="0"
352 VSPACE="0"
353 BORDER="0"
354 ALT="(3)"></A
355 >
356 $ make
357 &lt;output from make&gt;
358 $ su <A
359 NAME="ROOT"
360 ><IMG
361 SRC="../images/callouts/4.gif"
362 HSPACE="0"
363 VSPACE="0"
364 BORDER="0"
365 ALT="(4)"></A
366 >
367 $ make install
368 &lt;output from make install&gt;
369 $</PRE
370 ></TD
371 ></TR
372 ></TABLE
373 ><DIV
374 CLASS="CALLOUTLIST"
375 ><DL
376 COMPACT="COMPACT"
377 ><DT
378 ><A
379 HREF="usbs-testing.html#PATH"
380 ><IMG
381 SRC="../images/callouts/1.gif"
382 HSPACE="0"
383 VSPACE="0"
384 BORDER="0"
385 ALT="(1)"></A
386 ></DT
387 ><DD
388 >The location of the eCos component repository should be substituted
389 for <TT
390 CLASS="LITERAL"
391 >&lt;repo&gt;</TT
392 >.</DD
393 ><DT
394 ><A
395 HREF="usbs-testing.html#VERSION"
396 ><IMG
397 SRC="../images/callouts/2.gif"
398 HSPACE="0"
399 VSPACE="0"
400 BORDER="0"
401 ALT="(2)"></A
402 ></DT
403 ><DD
404 >If the package has been obtained via CVS or anonymous CVS then the
405 package version will be <TT
406 CLASS="FILENAME"
407 >current</TT
408 >, as per the
409 example. If instead the package has been obtained as part of a full
410 eCos release or as a separate <TT
411 CLASS="FILENAME"
412 >.epk</TT
413 > file then the
414 appropriate package version should be used instead of
415 <TT
416 CLASS="FILENAME"
417 >current</TT
418 >.</DD
419 ><DT
420 ><A
421 HREF="usbs-testing.html#ARGS"
422 ><IMG
423 SRC="../images/callouts/3.gif"
424 HSPACE="0"
425 VSPACE="0"
426 BORDER="0"
427 ALT="(3)"></A
428 ></DT
429 ><DD
430 >The <B
431 CLASS="COMMAND"
432 >configure</B
433 > script takes the usual arguments such
434 as <TT
435 CLASS="PARAMETER"
436 ><I
437 >--prefix=</I
438 ></TT
439 > to specify where the executables
440 and support files should be installed. The only other parameter that
441 some users may wish to specify is the location of a suitable Tcl
442 installation. By default <SPAN
443 CLASS="APPLICATION"
444 >usbhost</SPAN
445 > will use
446 the existing Tcl installation in <TT
447 CLASS="FILENAME"
448 >/usr</TT
449 >,
450 as provided by your Linux distribution. An alternative Tcl
451 installation can be specified using the parameter
452 <TT
453 CLASS="PARAMETER"
454 ><I
455 >--with-tcl=</I
456 ></TT
457 >, or alternatively using some
458 combination of <TT
459 CLASS="PARAMETER"
460 ><I
461 >--with-tcl-include</I
462 ></TT
463 >,
464 <TT
465 CLASS="PARAMETER"
466 ><I
467 >--with-tcl-lib</I
468 ></TT
469 > and
470 <TT
471 CLASS="PARAMETER"
472 ><I
473 >--with-tcl-version</I
474 ></TT
475 >. </DD
476 ><DT
477 ><A
478 HREF="usbs-testing.html#ROOT"
479 ><IMG
480 SRC="../images/callouts/4.gif"
481 HSPACE="0"
482 VSPACE="0"
483 BORDER="0"
484 ALT="(4)"></A
485 ></DT
486 ><DD
487 >One of the host-side executables that gets built,
488 <SPAN
489 CLASS="APPLICATION"
490 >usbchmod</SPAN
491 >, needs to be installed with suid
492 root privileges. Although the Linux kernel makes it possible for
493 applications to perform low-level USB operations such as transmitting
494 bulk packets, by default access to this functionality is restricted to
495 programs with superuser privileges. It is undesirable to run a complex
496 program such as <SPAN
497 CLASS="APPLICATION"
498 >usbhost</SPAN
499 > with such
500 privileges, especially since the program contains a general-purpose
501 Tcl interpreter. Therefore when <SPAN
502 CLASS="APPLICATION"
503 >usbhost</SPAN
504 >
505 starts up and discovers that it does not have sufficient access to the
506 appropriate entries in <TT
507 CLASS="FILENAME"
508 >/proc/bus/usb</TT
509 >, 
510 it spawns an instance of <SPAN
511 CLASS="APPLICATION"
512 >usbchmod</SPAN
513 > to modify
514 the permissions on these entries. <SPAN
515 CLASS="APPLICATION"
516 >usbchmod</SPAN
517 >
518 will only do this for a USB device <TT
519 CLASS="LITERAL"
520 >&quot;Red Hat eCos USB
521 test&quot;</TT
522 >, so installing this program suid root should not
523 introduce any security problems.</DD
524 ></DL
525 ></DIV
526 ><P
527 >During <B
528 CLASS="COMMAND"
529 >make install</B
530 > the following actions will take
531 place: </P
532 ><P
533 ></P
534 ><OL
535 TYPE="1"
536 ><LI
537 ><P
538 ><SPAN
539 CLASS="APPLICATION"
540 >usbhost</SPAN
541 > will be installed in <TT
542 CLASS="FILENAME"
543 >/usr/local/bin</TT
544 >,
545 or some other <TT
546 CLASS="FILENAME"
547 >bin</TT
548 > directory if
549 the default location is changed at configure-time using a
550 <TT
551 CLASS="PARAMETER"
552 ><I
553 >--prefix=</I
554 ></TT
555 > or similar option. It will be
556 installed as the executable
557 <SPAN
558 CLASS="APPLICATION"
559 >usbhost_&lt;version&gt;</SPAN
560 >, for example
561 <SPAN
562 CLASS="APPLICATION"
563 >usbhost_current</SPAN
564 >, thus allowing several
565 releases of the USB slave package to co-exist. For convenience a
566 symbolic link from <TT
567 CLASS="FILENAME"
568 >usbhost</TT
569 > to this executable
570 will be created, so users can just run <B
571 CLASS="COMMAND"
572 >usbhost</B
573 > to
574 access the most recently-installed version.</P
575 ></LI
576 ><LI
577 ><P
578 ><SPAN
579 CLASS="APPLICATION"
580 >usbchmod</SPAN
581 > will be installed in
582 <TT
583 CLASS="FILENAME"
584 >/usr/local/libexec/ecos/io_usb_slave_&lt;version&gt;</TT
585 >.
586 This program should only be run by <SPAN
587 CLASS="APPLICATION"
588 >usbhost</SPAN
589 >,
590 not invoked directly, so it is not placed in the <TT
591 CLASS="FILENAME"
592 >bin</TT
593
594 directory. Again the presence of the package version in the directory
595 name allows multiple releases of the package to co-exist.</P
596 ></LI
597 ><LI
598 ><P
599 >A Tcl script <TT
600 CLASS="FILENAME"
601 >usbhost.tcl</TT
602 > will get installed in
603 the same directory as <SPAN
604 CLASS="APPLICATION"
605 >usbchmod</SPAN
606 >. This Tcl
607 script is loaded automatically by the
608 <SPAN
609 CLASS="APPLICATION"
610 >usbhost</SPAN
611 > executable. </P
612 ></LI
613 ><LI
614 ><P
615 >A number of additional Tcl scripts, for example
616 <TT
617 CLASS="FILENAME"
618 >list.tcl</TT
619 > will get installed alongside
620 <TT
621 CLASS="FILENAME"
622 >usbhost.tcl</TT
623 >. These correspond to various test
624 cases provided as standard. If a given test case is specified on the
625 command line and cannot be found relative to the current directory
626 then <SPAN
627 CLASS="APPLICATION"
628 >usbhost</SPAN
629 > will search the install
630 directory for these test cases.</P
631 ><DIV
632 CLASS="NOTE"
633 ><BLOCKQUOTE
634 CLASS="NOTE"
635 ><P
636 ><B
637 >Note: </B
638 >Strictly speaking installing the <TT
639 CLASS="FILENAME"
640 >usbhost.tcl</TT
641 > and
642 other Tcl scripts below the <TT
643 CLASS="FILENAME"
644 >libexec</TT
645 >
646 directory deviates from standard practice: they are
647 architecture-independent data files so should be installed below
648 the <TT
649 CLASS="FILENAME"
650 >share</TT
651 > subdirectory. In
652 practice the files are sufficiently small that there is no point in
653 sharing them, and keeping them below <TT
654 CLASS="FILENAME"
655 >libexec</TT
656 >
657 simplifies the host-side software somewhat.</P
658 ></BLOCKQUOTE
659 ></DIV
660 ></LI
661 ></OL
662 ><P
663 >The <B
664 CLASS="COMMAND"
665 >usbhost</B
666 > should be run only when there is a
667 suitable target attached to the USB bus and running the
668 <SPAN
669 CLASS="APPLICATION"
670 >usbtarget</SPAN
671 > program. It will search
672 <TT
673 CLASS="FILENAME"
674 >/proc/bus/usb/devices</TT
675 > for an entry corresponding
676 to this program, invoke <SPAN
677 CLASS="APPLICATION"
678 >usbchmod</SPAN
679 > if
680 necessary to change the access rights, and then interact with
681 <SPAN
682 CLASS="APPLICATION"
683 >usbtarget</SPAN
684 > over the USB bus.
685 <B
686 CLASS="COMMAND"
687 >usbhost</B
688 > should be invoked as follows:</P
689 ><TABLE
690 BORDER="0"
691 BGCOLOR="#E0E0E0"
692 WIDTH="100%"
693 ><TR
694 ><TD
695 ><PRE
696 CLASS="SCREEN"
697 >$ usbhost [-v|--version] [-h|--help] [-V|--verbose] &lt;test&gt; [&lt;test parameters&gt;]</PRE
698 ></TD
699 ></TR
700 ></TABLE
701 ><P
702 ></P
703 ><OL
704 TYPE="1"
705 ><LI
706 ><P
707 >The <TT
708 CLASS="PARAMETER"
709 ><I
710 >-v</I
711 ></TT
712 > or <TT
713 CLASS="PARAMETER"
714 ><I
715 >--version</I
716 ></TT
717 >
718 option will display version information for
719 <SPAN
720 CLASS="APPLICATION"
721 >usbhost</SPAN
722 > including the version of the USB
723 slave package that was used to build the executable.</P
724 ></LI
725 ><LI
726 ><P
727 >The <TT
728 CLASS="PARAMETER"
729 ><I
730 >-h</I
731 ></TT
732 > or <TT
733 CLASS="PARAMETER"
734 ><I
735 >--help</I
736 ></TT
737 > option
738 will display usage information.</P
739 ></LI
740 ><LI
741 ><P
742 >The <TT
743 CLASS="PARAMETER"
744 ><I
745 >-V</I
746 ></TT
747 > or <TT
748 CLASS="PARAMETER"
749 ><I
750 >--verbose</I
751 ></TT
752 >
753 option can be used to obtain more information at run-time, for example
754 some output for every USB transfer. This option can be repeated
755 multiple times to increase the amount of output.</P
756 ></LI
757 ><LI
758 ><P
759 >The first argument that does not begin with a hyphen specifies a test
760 that should be run, in the form of a Tcl script. For example an
761 argument of <TT
762 CLASS="PARAMETER"
763 ><I
764 >list.tcl</I
765 ></TT
766 > will cause
767 <SPAN
768 CLASS="APPLICATION"
769 >usbhost</SPAN
770 > to look for a script with that
771 name, adding a <TT
772 CLASS="FILENAME"
773 >.tcl</TT
774 > suffix if necessarary, and
775 run that script. <SPAN
776 CLASS="APPLICATION"
777 >usbhost</SPAN
778 > will look in the
779 current directory first, then in the install tree for standard test
780 scripts provided by the USB slave package.</P
781 ></LI
782 ><LI
783 ><P
784 >Some test scripts may want their own parameters, for example a
785 duration in seconds. These can be passed on the command line after
786 the name of the test, for example
787 <B
788 CLASS="COMMAND"
789 >usbhost&nbsp;mytest&nbsp;60</B
790 >. </P
791 ></LI
792 ></OL
793 ></DIV
794 ><DIV
795 CLASS="REFSECT1"
796 ><A
797 NAME="AEN983"
798 ></A
799 ><H2
800 >Writing a Test</H2
801 ><P
802 >Each test is defined by a Tcl script, running inside an interpreter
803 provided by <SPAN
804 CLASS="APPLICATION"
805 >usbhost</SPAN
806 >. In addition to the
807 normal Tcl functionality this interpreter provides a number of
808 variables and functions related to USB testing. For example there is a
809 variable <TT
810 CLASS="VARNAME"
811 >bulk_in_endpoints</TT
812 > that lists all the
813 endpoints on the target that can perform bulk IN operations, and a
814 related array <TT
815 CLASS="VARNAME"
816 >bulk_in</TT
817 > which contains information
818 such as the minimum and maximum packets sizes. There is a function
819 <TT
820 CLASS="FUNCTION"
821 >bulktest</TT
822 > which can be used to perform bulk tests
823 on a particular endpoint. A simple test script aimed at specific
824 hardware could ignore the information variables since it would know
825 exactly what USB hardware is available on the target, whereas a
826 general-purpose script would use the information to adapt to the
827 hardware capabilities.</P
828 ><P
829 >To avoid namespace pollution all USB-related Tcl variables and
830 functions live in the <TT
831 CLASS="VARNAME"
832 >usbtest::</TT
833 > namespace.
834 Therefore accessing requires either explicitly including the
835 namespace any references, for example
836 <TT
837 CLASS="LITERAL"
838 >$usbtest::bulk_in_endpoints</TT
839 >, or by using Tcl's
840 <TT
841 CLASS="FUNCTION"
842 >namespace import</TT
843 > facility.</P
844 ><P
845 >A very simple test script might look like this:</P
846 ><TABLE
847 BORDER="0"
848 BGCOLOR="#E0E0E0"
849 WIDTH="100%"
850 ><TR
851 ><TD
852 ><PRE
853 CLASS="PROGRAMLISTING"
854 >usbtest::bulktest 1 out 4000
855 usbtest::bulktest 2 in  4000
856 if { [usbtest::start 60] } {
857     puts "Test successful"
858 } else
859     puts "Test failed"
860     foreach result $usbtest::results {
861         puts $result
862     }
863 }</PRE
864 ></TD
865 ></TR
866 ></TABLE
867 ><P
868 >This would perform a test run involving 4000 bulk transfers from the
869 host to the target's endpoint 1, and concurrently 4000 bulk transfers
870 from endpoint 2. Default settings for packet sizes, contents, and
871 delays would be used. The actual test would not start running until
872 <TT
873 CLASS="FILENAME"
874 >usbtest</TT
875 > is invoked, and it is expected that the
876 test would complete within 60 seconds. If any failures occur then they
877 are reported.</P
878 ></DIV
879 ><DIV
880 CLASS="REFSECT1"
881 ><A
882 NAME="AEN998"
883 ></A
884 ><H2
885 >Available Hardware</H2
886 ><P
887 >Each target-side USB device driver provides information about the
888 actual capabilities of the hardware, for example which endpoints are
889 available. Strictly speaking it provides information about what is
890 actually supported by the device driver, which may be a subset of what
891 the hardware is capable of. For example, the hardware may support
892 isochronous transfers on a particular endpoint but if there is no
893 software support for this in the driver then this endpoint will not be
894 listed. When <SPAN
895 CLASS="APPLICATION"
896 >usbhost</SPAN
897 > first contacts the
898 <SPAN
899 CLASS="APPLICATION"
900 >usbtarget</SPAN
901 > program running on the target
902 platform, it obtains this information and makes it available to test
903 scripts via Tcl variables:</P
904 ><P
905 ></P
906 ><DIV
907 CLASS="VARIABLELIST"
908 ><DL
909 ><DT
910 ><TT
911 CLASS="VARNAME"
912 >bulk_in_endpoints</TT
913 ></DT
914 ><DD
915 ><P
916 >    This is a simple list of the endpoints which can support bulk IN
917     transfers. For example if the target-side hardware supports
918     these transfers on endpoints 3 and 5 then the value would be
919     <TT
920 CLASS="LITERAL"
921 >&quot;3 5&quot;</TT
922 > Typical test scripts would
923     iterate over the list using something like:
924   </P
925 ><TABLE
926 BORDER="0"
927 BGCOLOR="#E0E0E0"
928 WIDTH="90%"
929 ><TR
930 ><TD
931 ><PRE
932 CLASS="PROGRAMLISTING"
933 >  if { 0 != [llength $usbtest::bulk_in_endpoints] } {
934       puts"Bulk IN endpoints: $usbtest::bulk_in_endpoints"
935       foreach endpoint $usbtest:bulk_in_endpoints {
936           &#8230;
937       }
938   }
939   </PRE
940 ></TD
941 ></TR
942 ></TABLE
943 ></DD
944 ><DT
945 ><TT
946 CLASS="VARNAME"
947 >bulk_in()</TT
948 ></DT
949 ><DD
950 ><P
951 >  This array holds additional information about each bulk IN endpoint.
952   The array is indexed by two fields, the endpoint number and one of
953   <TT
954 CLASS="LITERAL"
955 >min_size</TT
956 >, <TT
957 CLASS="LITERAL"
958 >max_size</TT
959 >,
960   <TT
961 CLASS="LITERAL"
962 >max_in_padding</TT
963 > and <TT
964 CLASS="LITERAL"
965 >devtab</TT
966 >:
967   </P
968 ><P
969 ></P
970 ><DIV
971 CLASS="VARIABLELIST"
972 ><DL
973 ><DT
974 ><TT
975 CLASS="LITERAL"
976 >min_size</TT
977 ></DT
978 ><DD
979 ><P
980 >    This field specifies a lower bound on the size of bulk transfers,
981     and will typically will have a value of 1.
982     </P
983 ><DIV
984 CLASS="NOTE"
985 ><BLOCKQUOTE
986 CLASS="NOTE"
987 ><P
988 ><B
989 >Note: </B
990 >    The typical minimum transfer size of a single byte is not strictly
991     speaking correct, since under some circumstances it can make sense
992     to have a transfer size of zero bytes. However current target-side
993     device drivers interpret a request to transfer zero bytes as a way
994     for higher-level code to determine whether or not an endpoint is
995     stalled, so it is not actually possible to perform zero-byte
996     transfers. This issue will be addressed at some future point.
997     </P
998 ></BLOCKQUOTE
999 ></DIV
1000 ></DD
1001 ><DT
1002 ><TT
1003 CLASS="LITERAL"
1004 >max_size</TT
1005 ></DT
1006 ><DD
1007 ><P
1008 >    This field specifies an upper bound on the size of bulk transfers.
1009     Some target-side drivers may be limited to transfers of say
1010     0x0FFFF bytes because of hardware limitations. In practice the
1011     transfer size is likely to be limited primarily to limit memory
1012     consumption of the test code on the target hardware, and to ensure
1013     that tests complete reasonably quickly. At the time of writing
1014     transfers are limited to 4K.
1015     </P
1016 ></DD
1017 ><DT
1018 ><TT
1019 CLASS="LITERAL"
1020 >max_in_padding</TT
1021 ></DT
1022 ><DD
1023 ><P
1024 >    On some hardware it may be necessary for the target-side device
1025     driver to send more data than is actually intended. For example
1026     the SA11x0 USB hardware cannot perform bulk transfers that are
1027     an exact multiple of 64 bytes, instead it must pad such
1028     transfers with an extra byte and the host must be ready to
1029     accept and discard this byte. The
1030     <TT
1031 CLASS="LITERAL"
1032 >max_in_padding</TT
1033 > field indicates the amount of
1034     padding that is required. The low-level code inside
1035     <SPAN
1036 CLASS="APPLICATION"
1037 >usbhost</SPAN
1038 > will use this field
1039     automatically, and there is no need for test scripts to adjust
1040     packet sizes for padding. The field is provided for
1041     informational purposes only.
1042     </P
1043 ></DD
1044 ><DT
1045 ><TT
1046 CLASS="LITERAL"
1047 >devtab</TT
1048 ></DT
1049 ><DD
1050 ><P
1051 >    This is a string indicating whether or not the
1052     target-side USB device driver supports access to this endpoint
1053     via entries in the device table, in other words through
1054     conventional calls like <TT
1055 CLASS="FUNCTION"
1056 >open</TT
1057 > and
1058     <TT
1059 CLASS="FUNCTION"
1060 >write</TT
1061 >. Some device drivers may only
1062     support low-level USB access because typically that is what gets
1063     used by USB class-specific packages such as USB-ethernet.
1064     An empty string indicates that no devtab entry is available,
1065     otherwise it will be something like
1066     <TT
1067 CLASS="LITERAL"
1068 >&quot;/dev/usbs2w&quot;</TT
1069 >. 
1070     </P
1071 ></DD
1072 ></DL
1073 ></DIV
1074 ><P
1075 >  Typical test scripts would access this data using something like:
1076   </P
1077 ><TABLE
1078 BORDER="0"
1079 BGCOLOR="#E0E0E0"
1080 WIDTH="90%"
1081 ><TR
1082 ><TD
1083 ><PRE
1084 CLASS="PROGRAMLISTING"
1085 >  foreach endpoint $usbtest:bulk_in_endpoints {
1086       puts "Endpoint $endpoint: "
1087       puts "    minimum transfer size $usbtest::bulk_in($endpoint,min_size)"
1088       puts "    maximum transfer size $usbtest::bulk_in($endpoint,max_size)"
1089       if { 0 == $usbtest::bulk_in($endpoint,max_in_padding) } {
1090           puts "    no IN padding required"
1091       } else {
1092           puts "    $usbtest::bulk_in($endpoint,max_in_padding) bytes of IN padding required"
1093       }
1094       if { "" == $usbtest::bulk_in($endpoint,devtab) } {
1095           puts "    no devtab entry provided"
1096       } else {
1097           puts "    corresponding devtab entry is $usbtest::bulk_in($endpoint,devtab)"
1098       }
1099   }
1100   </PRE
1101 ></TD
1102 ></TR
1103 ></TABLE
1104 ></DD
1105 ><DT
1106 ><TT
1107 CLASS="VARNAME"
1108 >bulk_out_endpoint</TT
1109 ></DT
1110 ><DD
1111 ><P
1112 >    This is a simple list of the endpoints which can support bulk OUT
1113     transfers. It is analogous to
1114     <TT
1115 CLASS="VARNAME"
1116 >bulk_in_endpoints</TT
1117 >.
1118   </P
1119 ></DD
1120 ><DT
1121 ><TT
1122 CLASS="VARNAME"
1123 >bulk_out()</TT
1124 ></DT
1125 ><DD
1126 ><P
1127 >  This array holds additional information about each bulk OUT
1128   endpoint. It can be accessed in the same way as
1129   <TT
1130 CLASS="VARNAME"
1131 >bulk_in()</TT
1132 >, except that there is no
1133   <TT
1134 CLASS="LITERAL"
1135 >max_in_padding</TT
1136 > field because that field only
1137   makes sense for IN transfers.
1138   </P
1139 ></DD
1140 ><DT
1141 ><TT
1142 CLASS="VARNAME"
1143 >control()</TT
1144 ></DT
1145 ><DD
1146 ><P
1147 >  This array holds information about the control endpoint. It contains
1148   two fields, <TT
1149 CLASS="LITERAL"
1150 >min_size</TT
1151 > and
1152   <TT
1153 CLASS="LITERAL"
1154 >max_size</TT
1155 >. Note that there is no variable
1156   <TT
1157 CLASS="VARNAME"
1158 >control_endpoints</TT
1159 > because a USB target always
1160   supports a single control endpoint <TT
1161 CLASS="LITERAL"
1162 >0</TT
1163 >. Similarly
1164   the <TT
1165 CLASS="VARNAME"
1166 >control</TT
1167 > array does not use an endpoint number
1168   as the first index because that would be redundant.
1169   </P
1170 ></DD
1171 ><DT
1172 ><TT
1173 CLASS="VARNAME"
1174 >isochronous_in_endpoints</TT
1175 > and
1176         <TT
1177 CLASS="VARNAME"
1178 >isochronous_in()</TT
1179 ></DT
1180 ><DD
1181 ><P
1182 >  These variables provide the same information as
1183   <TT
1184 CLASS="VARNAME"
1185 >bulk_in_endpoints</TT
1186 > and <TT
1187 CLASS="VARNAME"
1188 >bulk_in</TT
1189 >,
1190   but for endpoints that support isochronous IN transfers.
1191   </P
1192 ></DD
1193 ><DT
1194 ><TT
1195 CLASS="VARNAME"
1196 >isochronous_out_endpoints</TT
1197 > and
1198         <TT
1199 CLASS="VARNAME"
1200 >isochronous_out()</TT
1201 ></DT
1202 ><DD
1203 ><P
1204 >  These variables provide the same information as
1205   <TT
1206 CLASS="VARNAME"
1207 >bulk_out_endpoints</TT
1208 > and <TT
1209 CLASS="VARNAME"
1210 >bulk_out</TT
1211 >,
1212   but for endpoints that support isochronous OUT transfers.
1213   </P
1214 ></DD
1215 ><DT
1216 ><TT
1217 CLASS="VARNAME"
1218 >interrupt_in_endpoints</TT
1219 > and
1220         <TT
1221 CLASS="VARNAME"
1222 >interrupt_in()</TT
1223 ></DT
1224 ><DD
1225 ><P
1226 >  These variables provide the same information as
1227   <TT
1228 CLASS="VARNAME"
1229 >bulk_in_endpoints</TT
1230 > and <TT
1231 CLASS="VARNAME"
1232 >bulk_in</TT
1233 >,
1234   but for endpoints that support interrupt IN transfers.
1235   </P
1236 ></DD
1237 ><DT
1238 ><TT
1239 CLASS="VARNAME"
1240 >interrupt_out_endpoints</TT
1241 > and
1242         <TT
1243 CLASS="VARNAME"
1244 >interrupt_out()</TT
1245 ></DT
1246 ><DD
1247 ><P
1248 >  These variables provide the same information as
1249   <TT
1250 CLASS="VARNAME"
1251 >bulk_out_endpoints</TT
1252 > and <TT
1253 CLASS="VARNAME"
1254 >bulk_out</TT
1255 >,
1256   but for endpoints that support interrupt OUT transfers.
1257   </P
1258 ></DD
1259 ></DL
1260 ></DIV
1261 ></DIV
1262 ><DIV
1263 CLASS="REFSECT1"
1264 ><A
1265 NAME="AEN1105"
1266 ></A
1267 ><H2
1268 >Testing Bulk Transfers</H2
1269 ><P
1270 >The main function for initiating a bulk test is
1271 <TT
1272 CLASS="FUNCTION"
1273 >usbtest::bulktest</TT
1274 >. This takes three compulsory
1275 arguments, and can be given a number of additional arguments to
1276 control the exact behaviour. The compulsory arguments are:</P
1277 ><P
1278 ></P
1279 ><DIV
1280 CLASS="VARIABLELIST"
1281 ><DL
1282 ><DT
1283 >endpoint</DT
1284 ><DD
1285 ><P
1286 >    This specifies the endpoint to use. It should correspond to
1287     one of the entries in
1288     <TT
1289 CLASS="VARNAME"
1290 >usbtest::bulk_in_endpoints</TT
1291 > or
1292     <TT
1293 CLASS="VARNAME"
1294 >usbtest::bulk_out_endpoints</TT
1295 >, depending on the
1296     transfer direction.
1297   </P
1298 ></DD
1299 ><DT
1300 >direction</DT
1301 ><DD
1302 ><P
1303 >  This should be either <TT
1304 CLASS="LITERAL"
1305 >in</TT
1306 > or <TT
1307 CLASS="LITERAL"
1308 >out</TT
1309 >.
1310   </P
1311 ></DD
1312 ><DT
1313 >number of transfers</DT
1314 ><DD
1315 ><P
1316 >  This specifies the number of transfers that should take place. The
1317   testing software does not currently support the concept of performing
1318   transfers for a given period of time because synchronising this on
1319   both the host and a wide range of targets is difficult. However it
1320   is relatively easy to work out the approximate time a number of bulk
1321   transfers should take place, based on a typical bandwidth of
1322   1MB/second and assuming say a 1ms overhead per transfer.
1323   Alternatively a test script could perform a small initial run to
1324   determine what performance can actually be expected from a given
1325   target, and then use this information to run a much longer test.
1326   </P
1327 ></DD
1328 ></DL
1329 ></DIV
1330 ><P
1331 >Additional arguments can be used to control the exact transfer. For
1332 example a <TT
1333 CLASS="PARAMETER"
1334 ><I
1335 >txdelay+</I
1336 ></TT
1337 > argument can be used to
1338 slowly increase the delay between transfers. All such arguments involve
1339 a value which can be passed either as part of the argument itself,
1340 for example <TT
1341 CLASS="LITERAL"
1342 >txdelay+=5</TT
1343 >, or as a subsequent
1344 argument, <TT
1345 CLASS="LITERAL"
1346 >txdelay+ 5</TT
1347 >. The possible arguments fall
1348 into a number of categories: data, I/O mechanism, transmit size,
1349 receive size, transmit delay, and receive delay.</P
1350 ><DIV
1351 CLASS="REFSECT2"
1352 ><A
1353 NAME="AEN1130"
1354 ></A
1355 ><H3
1356 >Data</H3
1357 ><P
1358 >An obvious parameter to control is the actual data that gets sent.
1359 This can be controlled by the argument <TT
1360 CLASS="PARAMETER"
1361 ><I
1362 >format</I
1363 ></TT
1364 >
1365 which can take one of five values: <TT
1366 CLASS="LITERAL"
1367 >none</TT
1368 >,
1369 <TT
1370 CLASS="LITERAL"
1371 >bytefill</TT
1372 >, <TT
1373 CLASS="LITERAL"
1374 >intfill</TT
1375 >,
1376 <TT
1377 CLASS="LITERAL"
1378 >byteseq</TT
1379 > and <TT
1380 CLASS="LITERAL"
1381 >wordseq</TT
1382 >. The default
1383 value is <TT
1384 CLASS="LITERAL"
1385 >none</TT
1386 >.</P
1387 ><P
1388 ></P
1389 ><DIV
1390 CLASS="VARIABLELIST"
1391 ><DL
1392 ><DT
1393 ><TT
1394 CLASS="LITERAL"
1395 >none</TT
1396 ></DT
1397 ><DD
1398 ><P
1399 >  The transmit code will not attempt to fill the buffer in any way,
1400   and the receive code will not check it. The actual data that gets
1401   transferred will be whatever happened to be in the buffer before
1402   the transfer started.
1403   </P
1404 ></DD
1405 ><DT
1406 ><TT
1407 CLASS="LITERAL"
1408 >bytefill</TT
1409 ></DT
1410 ><DD
1411 ><P
1412 >  The entire buffer will be filled with a single byte, as per
1413   <TT
1414 CLASS="FUNCTION"
1415 >memset</TT
1416 >. 
1417   </P
1418 ></DD
1419 ><DT
1420 ><TT
1421 CLASS="LITERAL"
1422 >intfill</TT
1423 ></DT
1424 ><DD
1425 ><P
1426 >  The buffer will be treated as an array of 32-bit integers, and will
1427   be filled with the same integer repeated the appropriate number of
1428   times. If the buffer size is not a multiple of four bytes then
1429   the last few bytes will be set to 0.
1430   </P
1431 ></DD
1432 ><DT
1433 ><TT
1434 CLASS="LITERAL"
1435 >byteseq</TT
1436 ></DT
1437 ><DD
1438 ><P
1439 >  The buffer will be filled with a sequence of bytes, generated by
1440   a linear congruential generator. If the first byte in the buffer is
1441   filled with the value <TT
1442 CLASS="LITERAL"
1443 >x</TT
1444 >, the next byte will be
1445   <TT
1446 CLASS="LITERAL"
1447 >(m*x)+i</TT
1448 >. For example a sequence of slowly
1449   incrementing bytes can be achieved by setting both the multiplier
1450   and the increment to 1. Alternatively a pseudo-random number
1451   sequence can be achieved using values 1103515245 and 12345, as
1452   per the standard C library <TT
1453 CLASS="FUNCTION"
1454 >rand</TT
1455 > function.
1456   For convenience these two constants are available as Tcl
1457   variables <TT
1458 CLASS="VARNAME"
1459 >usbtest::MULTIPLIER</TT
1460 > and
1461   <TT
1462 CLASS="VARNAME"
1463 >usbtest::INCREMENT</TT
1464 >.
1465   </P
1466 ></DD
1467 ><DT
1468 ><TT
1469 CLASS="LITERAL"
1470 >wordseq</TT
1471 ></DT
1472 ><DD
1473 ><P
1474 >  This acts like <TT
1475 CLASS="LITERAL"
1476 >byteseq</TT
1477 >, except that the buffer is
1478   treated as an array of 32-bit integers rather than as an array of
1479   bytes. If the buffer is not a multiple of four bytes then the last
1480   few bytes will be filled with zeroes.
1481   </P
1482 ></DD
1483 ></DL
1484 ></DIV
1485 ><P
1486 >The above requires three additional parameters
1487 <TT
1488 CLASS="PARAMETER"
1489 ><I
1490 >data1</I
1491 ></TT
1492 >, <TT
1493 CLASS="PARAMETER"
1494 ><I
1495 >data*</I
1496 ></TT
1497 > and
1498 <TT
1499 CLASS="PARAMETER"
1500 ><I
1501 >data+</I
1502 ></TT
1503 >. <TT
1504 CLASS="PARAMETER"
1505 ><I
1506 >data1</I
1507 ></TT
1508 > specifies
1509 the value to be used for byte or word fills, or the first number when
1510 calculating a sequence. The default value is <TT
1511 CLASS="LITERAL"
1512 >0</TT
1513 >.
1514 <TT
1515 CLASS="PARAMETER"
1516 ><I
1517 >data*</I
1518 ></TT
1519 > and <TT
1520 CLASS="PARAMETER"
1521 ><I
1522 >data+</I
1523 ></TT
1524 > specify
1525 the multiplier and increment for a sequence, and have default values
1526 of <TT
1527 CLASS="LITERAL"
1528 >1</TT
1529 > and <TT
1530 CLASS="LITERAL"
1531 >0</TT
1532 > respectively. For
1533 example, to perform a bulk transfer of a pseudo-random sequence of
1534 integers starting with 42 the following code could be used:</P
1535 ><TABLE
1536 BORDER="0"
1537 BGCOLOR="#E0E0E0"
1538 WIDTH="100%"
1539 ><TR
1540 ><TD
1541 ><PRE
1542 CLASS="PROGRAMLISTING"
1543 >bulktest 2 IN 1000 format=wordseq data1=42 \
1544     data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT</PRE
1545 ></TD
1546 ></TR
1547 ></TABLE
1548 ><P
1549 >The above parameters define what data gets transferred for the first
1550 transfer, but a test can involve multiple transfers. The data format
1551 will be the same for all transfers, but it is possible to adjust the
1552 current value, the multiplier, and the increment between each
1553 transfer. This is achieved with parameters <TT
1554 CLASS="PARAMETER"
1555 ><I
1556 >data1*</I
1557 ></TT
1558 >,
1559 <TT
1560 CLASS="PARAMETER"
1561 ><I
1562 >data1+</I
1563 ></TT
1564 >, <TT
1565 CLASS="PARAMETER"
1566 ><I
1567 >data**</I
1568 ></TT
1569 >,
1570 <TT
1571 CLASS="PARAMETER"
1572 ><I
1573 >data*+</I
1574 ></TT
1575 >, <TT
1576 CLASS="PARAMETER"
1577 ><I
1578 >data+*</I
1579 ></TT
1580 >, and
1581 <TT
1582 CLASS="PARAMETER"
1583 ><I
1584 >data++</I
1585 ></TT
1586 >, with default values of 1 for each
1587 multiplier and 0 for each increment. For example, if the multiplier
1588 for the first transfer is set to <TT
1589 CLASS="LITERAL"
1590 >2</TT
1591 > using
1592 <TT
1593 CLASS="PARAMETER"
1594 ><I
1595 >data*</I
1596 ></TT
1597 >, and arguments
1598 <TT
1599 CLASS="LITERAL"
1600 >data**&nbsp;2</TT
1601 > and <TT
1602 CLASS="LITERAL"
1603 >data*+&nbsp;-1</TT
1604 > are also
1605 supplied, then the multiplier for subsequent transfers will be
1606 <TT
1607 CLASS="LITERAL"
1608 >3</TT
1609 >, <TT
1610 CLASS="LITERAL"
1611 >5</TT
1612 >, <TT
1613 CLASS="LITERAL"
1614 >9</TT
1615 >,
1616 &#8230;.</P
1617 ><DIV
1618 CLASS="NOTE"
1619 ><BLOCKQUOTE
1620 CLASS="NOTE"
1621 ><P
1622 ><B
1623 >Note: </B
1624 >Currently it is not possible for a test script to send specific data,
1625 for example a specific sequence of bytes captured by a protocol analyser
1626 that caused a problem. If the transfer was from host to target then
1627 the target would have to know the exact sequence of bytes to expect,
1628 which means transferring data over the USB bus when that data is known
1629 to have caused problems in the past. Similarly for target to host
1630 transfers the target would have to know what bytes to send. A possible
1631 future extension of the USB testing support would allow for bounce
1632 operations, where a given message is first sent to the target and then
1633 sent back to the host, with only the host checking that the data was
1634 returned correctly.</P
1635 ></BLOCKQUOTE
1636 ></DIV
1637 ></DIV
1638 ><DIV
1639 CLASS="REFSECT2"
1640 ><A
1641 NAME="AEN1200"
1642 ></A
1643 ><H3
1644 >I/O Mechanism</H3
1645 ><P
1646 >On the target side USB transfers can happen using either low-level
1647 USB calls such as <TT
1648 CLASS="FUNCTION"
1649 >usbs_start_rx_buffer</TT
1650 >, or by
1651 higher-level calls which go through the device table. By default the
1652 target-side code will use the low-level calls. If it is desired to
1653 test the higher-level calls instead, for example because those are
1654 what the application uses, then that can be achieved with an
1655 argument <TT
1656 CLASS="PARAMETER"
1657 ><I
1658 >mechanism=devtab</I
1659 ></TT
1660 >.</P
1661 ></DIV
1662 ><DIV
1663 CLASS="REFSECT2"
1664 ><A
1665 NAME="AEN1205"
1666 ></A
1667 ><H3
1668 >Transmit Size</H3
1669 ><P
1670 >The next set of arguments can be used to control the size of the
1671 transmitted buffer: <TT
1672 CLASS="PARAMETER"
1673 ><I
1674 >txsize1</I
1675 ></TT
1676 >,
1677 <TT
1678 CLASS="PARAMETER"
1679 ><I
1680 >txsize&gt;=</I
1681 ></TT
1682 >, <TT
1683 CLASS="PARAMETER"
1684 ><I
1685 >txsize&lt;=</I
1686 ></TT
1687 >
1688 <TT
1689 CLASS="PARAMETER"
1690 ><I
1691 >txsize*</I
1692 ></TT
1693 >, <TT
1694 CLASS="PARAMETER"
1695 ><I
1696 >txsize/</I
1697 ></TT
1698 >,
1699 and <TT
1700 CLASS="PARAMETER"
1701 ><I
1702 >txsize+</I
1703 ></TT
1704 >.</P
1705 ><P
1706 ><TT
1707 CLASS="PARAMETER"
1708 ><I
1709 >txsize1</I
1710 ></TT
1711 > determines the size of the first
1712 transfer, and has a default value of 32 bytes. The size of the next
1713 transfer is calculated by first multiplying by the
1714 <TT
1715 CLASS="PARAMETER"
1716 ><I
1717 >txsize*</I
1718 ></TT
1719 > value, then dividing by the
1720 <TT
1721 CLASS="PARAMETER"
1722 ><I
1723 >txsize/</I
1724 ></TT
1725 > value, and finally adding the
1726 <TT
1727 CLASS="PARAMETER"
1728 ><I
1729 >txsize+</I
1730 ></TT
1731 > value. The defaults for these are
1732 <TT
1733 CLASS="LITERAL"
1734 >1</TT
1735 >, <TT
1736 CLASS="LITERAL"
1737 >1</TT
1738 >, and <TT
1739 CLASS="LITERAL"
1740 >0</TT
1741 >
1742 respectively, which means that the transfer size will remain
1743 unchanged. If for example the transfer size should increase by
1744 approximately 50 per cent each time then suitable values might be
1745 <TT
1746 CLASS="LITERAL"
1747 >txsize*&nbsp;3</TT
1748 >, <TT
1749 CLASS="LITERAL"
1750 >txsize/&nbsp;2</TT
1751 >,
1752 and <TT
1753 CLASS="LITERAL"
1754 >txsize+&nbsp;1</TT
1755 >. </P
1756 ><P
1757 >The <TT
1758 CLASS="PARAMETER"
1759 ><I
1760 >txsize&gt;=</I
1761 ></TT
1762 > and
1763 <TT
1764 CLASS="PARAMETER"
1765 ><I
1766 >txsize&lt;=</I
1767 ></TT
1768 > arguments can be used to impose
1769 lower and upper bounds on the transfer. By default the
1770 <TT
1771 CLASS="LITERAL"
1772 >min_size</TT
1773 > and <TT
1774 CLASS="LITERAL"
1775 >max_size</TT
1776 > values
1777 appropriate for the endpoint will be used. If at any time the
1778 current size falls outside the bounds then it will be normalized.</P
1779 ></DIV
1780 ><DIV
1781 CLASS="REFSECT2"
1782 ><A
1783 NAME="AEN1230"
1784 ></A
1785 ><H3
1786 >Receive Size</H3
1787 ><P
1788 >The receive size, in other words the number of bytes that either host
1789 or target will expect to receive as opposed to the number of bytes
1790 that actually get sent, can be adjusted using a similar set of
1791 arguments: <TT
1792 CLASS="PARAMETER"
1793 ><I
1794 >rxsize1</I
1795 ></TT
1796 >,
1797 <TT
1798 CLASS="PARAMETER"
1799 ><I
1800 >rxsize&gt;=</I
1801 ></TT
1802 >,
1803 <TT
1804 CLASS="PARAMETER"
1805 ><I
1806 >rxsize&lt;=</I
1807 ></TT
1808 >,
1809 <TT
1810 CLASS="PARAMETER"
1811 ><I
1812 >rxsize*</I
1813 ></TT
1814 >, <TT
1815 CLASS="PARAMETER"
1816 ><I
1817 >rxsize/</I
1818 ></TT
1819 > and
1820 <TT
1821 CLASS="PARAMETER"
1822 ><I
1823 >rxsize+</I
1824 ></TT
1825 >. The current receive size will be
1826 adjusted between transfers just like the transmit size. However when
1827 communicating over USB it is not a good idea to attempt to receive
1828 less data than will actually be sent: typically neither the hardware
1829 nor the software will be able to do anything useful with the excess,
1830 so there will be problems. Therefore if at any time the calculated
1831 receive size is less than the transmit size, the actual receive will
1832 be for the exact number of bytes that will get transmitted. However
1833 this will not affect the calculations for the next receive size.</P
1834 ><P
1835 >The default values for <TT
1836 CLASS="PARAMETER"
1837 ><I
1838 >rxsize1</I
1839 ></TT
1840 >,
1841 <TT
1842 CLASS="PARAMETER"
1843 ><I
1844 >rxsize*</I
1845 ></TT
1846 >, <TT
1847 CLASS="PARAMETER"
1848 ><I
1849 >rxsize/</I
1850 ></TT
1851 > and
1852 <TT
1853 CLASS="PARAMETER"
1854 ><I
1855 >rxsize+</I
1856 ></TT
1857 > are <TT
1858 CLASS="LITERAL"
1859 >0</TT
1860 >,
1861 <TT
1862 CLASS="LITERAL"
1863 >1</TT
1864 >, <TT
1865 CLASS="LITERAL"
1866 >1</TT
1867 > and <TT
1868 CLASS="LITERAL"
1869 >0</TT
1870 >
1871 respectively. This means that the calculated receive size will always
1872 be less than the transmit size, so the receive operation will be for
1873 the exact number of bytes transmitted. For some USB protocols this
1874 would not accurately reflect the traffic that will happen. For example
1875 with USB-ethernet transfer sizes will vary between 16 and 1516 bytes,
1876 so the receiver will always expect up to 1516 bytes. This can be
1877 achieved using <TT
1878 CLASS="LITERAL"
1879 >rxsize1&nbsp;1516</TT
1880 >, leaving the
1881 other parameters at their default values.</P
1882 ><P
1883 >For target hardware which involves non-zero
1884 <TT
1885 CLASS="LITERAL"
1886 >max_in_padding</TT
1887 >, on the host side the padding will
1888 be added automatically to the receive size if necessary.</P
1889 ></DIV
1890 ><DIV
1891 CLASS="REFSECT2"
1892 ><A
1893 NAME="AEN1251"
1894 ></A
1895 ><H3
1896 >Transmit and Receive Delays</H3
1897 ><P
1898 >Typically during the testing there will be some minor delays between
1899 transfers on both host and target. Some of these delays will be caused
1900 by timeslicing, for example another process running on the host, or a
1901 concurrent test thread running inside the target. Other delays will be
1902 caused by the USB bus itself, for example activity from another device
1903 on the bus. However it is desirable that test cases be allowed to
1904 inject additional and somewhat more controlled delays into the system,
1905 for example to make sure that the target behaves correctly even if the
1906 target is not yet ready to receive data from the host.</P
1907 ><P
1908 >The transmit delay is controlled by six parameters:
1909 <TT
1910 CLASS="PARAMETER"
1911 ><I
1912 >txdelay1</I
1913 ></TT
1914 >, <TT
1915 CLASS="PARAMETER"
1916 ><I
1917 >txdelay*</I
1918 ></TT
1919 >,
1920 <TT
1921 CLASS="PARAMETER"
1922 ><I
1923 >txdelay/</I
1924 ></TT
1925 >, <TT
1926 CLASS="PARAMETER"
1927 ><I
1928 >txdelay+</I
1929 ></TT
1930 >,
1931 <TT
1932 CLASS="PARAMETER"
1933 ><I
1934 >txdelay&gt;=</I
1935 ></TT
1936 > and
1937 <TT
1938 CLASS="PARAMETER"
1939 ><I
1940 >txdelay&lt;=</I
1941 ></TT
1942 >. The default values for these are
1943 <TT
1944 CLASS="LITERAL"
1945 >0</TT
1946 >, <TT
1947 CLASS="LITERAL"
1948 >1</TT
1949 >, <TT
1950 CLASS="LITERAL"
1951 >1</TT
1952 >,
1953 <TT
1954 CLASS="LITERAL"
1955 >0</TT
1956 >, <TT
1957 CLASS="LITERAL"
1958 >0</TT
1959 > and
1960 <TT
1961 CLASS="LITERAL"
1962 >1000000000</TT
1963 > respectively, so that by default
1964 transmits will happen as quickly as possible. Delays are measured in
1965 nanoseconds, so a value of <TT
1966 CLASS="LITERAL"
1967 >1000000</TT
1968 > would correspond
1969 to a delay of 0.001 seconds or one millisecond. By default delays have
1970 an upper bound of one second. Between transfers the transmit delay is
1971 updated in much the same was as the transfer sizes.</P
1972 ><P
1973 >The receive delay is controlled by a similar set of six parameters:
1974 <TT
1975 CLASS="PARAMETER"
1976 ><I
1977 >rxdelay1</I
1978 ></TT
1979 >, <TT
1980 CLASS="PARAMETER"
1981 ><I
1982 >rxdelay*</I
1983 ></TT
1984 >,
1985 <TT
1986 CLASS="PARAMETER"
1987 ><I
1988 >rxdelay/</I
1989 ></TT
1990 >, <TT
1991 CLASS="PARAMETER"
1992 ><I
1993 >rxdelay+</I
1994 ></TT
1995 >,
1996 <TT
1997 CLASS="PARAMETER"
1998 ><I
1999 >rxdelay&gt;=</I
2000 ></TT
2001 > and
2002 <TT
2003 CLASS="PARAMETER"
2004 ><I
2005 >rxdelay&lt;=</I
2006 ></TT
2007 >. The default values for these are
2008 the same as for transmit delays.</P
2009 ><P
2010 >The transmit delay is used on the side which sends data over the USB
2011 bus, so for a bulk IN transfer it is the target that sends data and
2012 hence sleeps for the specified transmit delay, while the host receives
2013 data sleeps for the receive delay. For an OUT transfer the positions
2014 are reversed.</P
2015 ><P
2016 >It should be noted that although the delays are measured in
2017 nanoseconds, the actual delays will be much less precise and are
2018 likely to be of the order of milliseconds. The exact details will
2019 depend on the kernel clock speed.</P
2020 ></DIV
2021 ></DIV
2022 ><DIV
2023 CLASS="REFSECT1"
2024 ><A
2025 NAME="AEN1277"
2026 ></A
2027 ><H2
2028 >Other Types of Transfer</H2
2029 ><P
2030 >Support for testing other types of USB traffic such as isochronous
2031 transfers is not yet implemented.</P
2032 ></DIV
2033 ><DIV
2034 CLASS="REFSECT1"
2035 ><A
2036 NAME="AEN1280"
2037 ></A
2038 ><H2
2039 >Starting a Test and Collecting Results</H2
2040 ><P
2041 >A USB test script should prepare one or more transfers using
2042 appropriate functions such as <TT
2043 CLASS="FUNCTION"
2044 >usbtest::bulktest</TT
2045 >.
2046 Once all the individual tests have been prepared they can be started
2047 by a call to <TT
2048 CLASS="FUNCTION"
2049 >usbtest::start</TT
2050 >. This takes a single
2051 argument, a maximum duration measured in seconds. If all transfers
2052 have not been completed in the specified time then any remaining
2053 transfers will be aborted.</P
2054 ><P
2055 ><TT
2056 CLASS="FUNCTION"
2057 >usbtest::start</TT
2058 > will return <TT
2059 CLASS="LITERAL"
2060 >1</TT
2061 >
2062 if all the tests have succeeded, or <TT
2063 CLASS="LITERAL"
2064 >0</TT
2065 > if any of
2066 them have failed. More detailed reports will be stored in the
2067 Tcl variable <TT
2068 CLASS="VARNAME"
2069 >usbtests::results</TT
2070 >, which will be a
2071 list of string messages.</P
2072 ></DIV
2073 ><DIV
2074 CLASS="REFSECT1"
2075 ><A
2076 NAME="AEN1290"
2077 ></A
2078 ><H2
2079 >Existing Test Scripts</H2
2080 ><P
2081 >A number of test scripts are provided as standard. These are located
2082 in the <TT
2083 CLASS="FILENAME"
2084 >host</TT
2085 > subdirectory of the
2086 common USB slave package, and will be installed as part of the process
2087 of building the host-side software. When a script is specified on the
2088 command line <SPAN
2089 CLASS="APPLICATION"
2090 >usbhost</SPAN
2091 > will first search for
2092 it in the current directory, then in the install tree. Standard
2093 test scripts include the following:</P
2094 ><P
2095 ></P
2096 ><DIV
2097 CLASS="VARIABLELIST"
2098 ><DL
2099 ><DT
2100 ><TT
2101 CLASS="FILENAME"
2102 >list.tcl</TT
2103 ></DT
2104 ><DD
2105 ><P
2106 >      This script simply displays information about the capabilities
2107       of the target platform, as provided by the target-side USB
2108       device driver. It can help with tracking down problems, but its
2109       primary purpose is to let users check that everything is working
2110       correctly: if running <B
2111 CLASS="COMMAND"
2112 >usbhost list.tcl</B
2113 >
2114       outputs sensible information then the user knows that the
2115       target side is running correctly and that communication between
2116       host and target is possible.
2117     </P
2118 ></DD
2119 ><DT
2120 ><TT
2121 CLASS="FILENAME"
2122 >verbose.tcl</TT
2123 ></DT
2124 ><DD
2125 ><P
2126 >      The target-side code can provide information about what
2127       is happening while tests are prepared and run. This facility
2128       should not normally be used since the extra I/O involved will
2129       significantly affect the behaviour of the system, but in some
2130       circumstances it may prove useful. Since an eCos application
2131       cannot easily be given command-line arguments the target-side
2132       verbosity level cannot be controlled using
2133       <TT
2134 CLASS="PARAMETER"
2135 ><I
2136 >-V</I
2137 ></TT
2138 > or <TT
2139 CLASS="PARAMETER"
2140 ><I
2141 >--verbose</I
2142 ></TT
2143 >
2144       options. Instead it can be controlled from inside
2145       <SPAN
2146 CLASS="APPLICATION"
2147 >gdb</SPAN
2148 > by changing the integer
2149       variable <TT
2150 CLASS="VARNAME"
2151 >verbose</TT
2152 >. Alternatively it can
2153       be manipulated by running the test script
2154       <TT
2155 CLASS="FILENAME"
2156 >verbose.tcl</TT
2157 >. This script takes a single
2158       argument, the desired verbosity level, which should be a small
2159       integer. For example, to disable target-side run-time logging
2160       the command <B
2161 CLASS="COMMAND"
2162 >usbhost&nbsp;verbose&nbsp;0</B
2163 > can
2164       be used.
2165     </P
2166 ></DD
2167 ></DL
2168 ></DIV
2169 ></DIV
2170 ><DIV
2171 CLASS="REFSECT1"
2172 ><A
2173 NAME="AEN1313"
2174 ></A
2175 ><H2
2176 >Possible Problems</H2
2177 ><P
2178 >If all transfers succeed within the specified time then both host and
2179 target remain in synch and further tests can be run without problem.
2180 However, if at any time a failure occurs then things get more
2181 complicated. For example, if the current test involves a series of
2182 bulk OUT transfers and the target detects that for one of these
2183 transfers it received less data than was expected then the test has
2184 failed, and the target will stop accepting data on this endpoint.
2185 However the host-side software may not have detected anything wrong
2186 and is now blocked trying to send the next lot of data.</P
2187 ><P
2188 >The test code goes to considerable effort to recover from problems
2189 such as these. On the host-side separate threads are used for
2190 concurrent transfers, and on the target-side appropriate asynchronous
2191 I/O mechanisms are used. In addition there is a control thread on the
2192 host that checks the state of all the main host-side threads, and the
2193 state of the target using private control messages. If it discovers
2194 that one side has stopped sending or receiving data because of an
2195 error and the other side is blocked as a result, it will set certain
2196 flags and then cause one additional transfer to take place. That
2197 additional transfer will have the effect of unblocking the other side,
2198 which then discovers that an error has occurred by checking the
2199 appropriate flags. In this way both host and target should end up back
2200 in synch, and it is possible to move on to the next set of tests.</P
2201 ><P
2202 >However, the above assumes that the testing has not triggered any
2203 serious hardware conditions. If instead the target-side hardware has
2204 been left in some strange state so that, for example, it will no
2205 longer raise an interrupt for traffic on a particular endpoint then
2206 recovery is not currently possible, and the testing software will just
2207 hang.</P
2208 ><P
2209 >A possible future enhancement to the testing software would allow the
2210 host-side to raise a USB reset signal whenever a failure occurs, in
2211 the hope that this would clear any remaining problems within the
2212 target-side USB hardware.</P
2213 ></DIV
2214 ><DIV
2215 CLASS="NAVFOOTER"
2216 ><HR
2217 ALIGN="LEFT"
2218 WIDTH="100%"><TABLE
2219 WIDTH="100%"
2220 BORDER="0"
2221 CELLPADDING="0"
2222 CELLSPACING="0"
2223 ><TR
2224 ><TD
2225 WIDTH="33%"
2226 ALIGN="left"
2227 VALIGN="top"
2228 ><A
2229 HREF="usbs-writing.html"
2230 >Prev</A
2231 ></TD
2232 ><TD
2233 WIDTH="34%"
2234 ALIGN="center"
2235 VALIGN="top"
2236 ><A
2237 HREF="io-usb-slave.html"
2238 >Home</A
2239 ></TD
2240 ><TD
2241 WIDTH="33%"
2242 ALIGN="right"
2243 VALIGN="top"
2244 >&nbsp;</TD
2245 ></TR
2246 ><TR
2247 ><TD
2248 WIDTH="33%"
2249 ALIGN="left"
2250 VALIGN="top"
2251 >Writing a USB Device Driver</TD
2252 ><TD
2253 WIDTH="34%"
2254 ALIGN="center"
2255 VALIGN="top"
2256 >&nbsp;</TD
2257 ><TD
2258 WIDTH="33%"
2259 ALIGN="right"
2260 VALIGN="top"
2261 >&nbsp;</TD
2262 ></TR
2263 ></TABLE
2264 ></DIV
2265 ></BODY
2266 ></HTML
2267 >