OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [io/] [usb/] [slave/] [v2_0/] [doc/] [usbs-testing.html] - Blame information for rev 174

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 27 unneback 
<!-- 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 
>data</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 data=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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.