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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [usbs-testing.html] - Blame information for rev 613

Go to most recent revision | Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

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