+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Testing</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="eCos USB Slave Support"
-HREF="io-usb-slave.html"><LINK
-REL="PREVIOUS"
-TITLE="Writing a USB Device Driver"
-HREF="usbs-writing.html"><LINK
-REL="NEXT"
-TITLE="eCos Support for Developing USB-ethernet Peripherals"
-HREF="io-usb-slave-eth.html"></HEAD
-><BODY
-CLASS="REFENTRY"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="usbs-writing.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="io-usb-slave-eth.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><H1
-><A
-NAME="USBS-TESTING">Testing</H1
-><DIV
-CLASS="REFNAMEDIV"
-><A
-NAME="AEN16868"
-></A
-><H2
->Name</H2
->Testing -- Testing of USB Device Drivers</DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN16871"
-></A
-><H2
->Introduction</H2
-><P
->The support for USB testing provided by the eCos USB common slave
-package is somewhat different in nature from the kind of testing used
-in many other packages. One obvious problem is that USB tests cannot
-be run on just a bare target platform: instead the target platform
-must be connected to a suitable USB host machine, and that host
-machine must be running appropriate software for the test code to
-interact with. This is very different from say a kernel test which
-typically will have no external dependencies. Another important
-difference between USB testing and say a C library
-<TT
-CLASS="FUNCTION"
->strcmp</TT
-> test is sensitivity to timing and to
-hardware boundary conditions: although a simple test case that just
-performs a small number of USB transfers is better than no testing at
-all, it should also be possible to run tests for hours or days on end,
-under a variety of loads. In order to provide the required
-functionality the basic architecture of the USB testing support is as
-follows: </P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
-> There is a single target-side program
- <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
->. By default when this is run
- on a target platform it will appear to do nothing. In fact it is
- waiting to be contacted by another program
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> which will tell it what test or
- tests to run. <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> provides
- mechanisms for running a wide range of tests.
- </P
-></LI
-><LI
-><P
-> <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> is a generic program, but USB
- testing depends to some extent on the functionality provided by the
- hardware. For example there is no point in testing bulk transmits
- to endpoint 12 if the target hardware does not support an endpoint
- 12. Therefore each USB device driver should supply information about
- what the hardware is actually capable of, in the form of an array of
- <SPAN
-CLASS="STRUCTNAME"
->usbs_testing_endpoint</SPAN
-> data structures.
- </P
-></LI
-><LI
-><P
-> There is a single host-side program
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->, which acts as a counterpart to
- <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
->. Again
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> has no built-in knowledge of
- the test or tests that are supposed to run, it only provides
- mechanisms for running a wide range of tests. On start-up
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will search the USB bus for
- hardware running the target-side program, specifically a USB device
- that identifies itself as the product <TT
-CLASS="LITERAL"
->"Red Hat eCos
- USB test"</TT
->.
- </P
-></LI
-><LI
-><P
-> <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> contains a Tcl interpreter, and
- will execute any Tcl scripts specified on the command line
- together with appropriate arguments. The Tcl interpreter has been
- extended with various commands such as
- <TT
-CLASS="LITERAL"
->usbtest::bulktest</TT
->, so the script can perform
- the desired test or tests.
- </P
-></LI
-><LI
-><P
-> Adding a new test simply involves writing a short Tcl script that
- invokes the appropriate USB-specific commands. Running multiple
- tests involves passing appropriate arguments to
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->, or alternatively writing a
- single script that just invokes other scripts.
- </P
-></LI
-></OL
-><P
->The current implementation of <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->
-depends heavily on functionality provided by the Linux kernel and in
-particular the usbdevfs support. It uses
-<TT
-CLASS="FILENAME"
->/proc/bus/usb/devices</TT
-> to find out what devices
-are attached to the bus, and will then access the device by opening
-<TT
-CLASS="FILENAME"
->/proc/bus/usb/xxx/yyy</TT
-> and performing
-<TT
-CLASS="FUNCTION"
->ioctl</TT
-> operations. This allows USB testing to take
-place without having to write a new host-side device driver, but
-getting the code working on host machines not running Linux would
-obviously be problematical.</P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN16904"
-></A
-><H2
->Building and Running the Target-side Code</H2
-><P
->The target-side component of the USB testing software consists of a
-single program <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> which contains
-support for a range of different tests, under the control of host-side
-software. This program is not built by default alongside other eCos
-test cases since it will only operate in certain environments,
-specifically when the target board's connector is plugged into a Linux
-host, and when the appropriate host-side software has been installed
-on that host. Instead the user must enable a configuration option
-<TT
-CLASS="LITERAL"
->CYGBLD_IO_USB_SLAVE_USBTEST</TT
-> to add the program to
-the list of tests for the current configuration.</P
-><P
->Starting the <SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> program does not
-require anything unusual, so it can be run in a normal
-<SPAN
-CLASS="APPLICATION"
->gdb</SPAN
-> session just like any eCos application.
-After initialization the program will wait for activity from the host.
-Depending on the hardware, the Linux host will detect that a new USB
-peripheral is present on the bus either when the
-<SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> initialization is complete or
-when the cable between target and host is connected. The host will
-perform the normal USB enumeration sequence and discover that the
-peripheral does not match any known vendor or product id and that
-there is no device driver for <TT
-CLASS="LITERAL"
->"Red Hat eCos USB
-test"</TT
->, so it will ignore the peripheral. When the
-<SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> program is run on the host it will
-connect to the target-side software, and testing can now commence.</P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN16915"
-></A
-><H2
->Building and Running the Host-side Code</H2
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->In theory the host-side software should be built when the package is
-installed in the component repository, and removed when a package
-is uninstalled. The current eCos administration tool does not provide
-this functionality.</P
-></BLOCKQUOTE
-></DIV
-><P
->The host-side software should be built via the usual sequence of
-"configure/make/make install". It can only be built on a
-Linux host and the <B
-CLASS="COMMAND"
->configure</B
-> script contains an
-explicit test for this. Because the eCos component repository should
-generally be treated as a read-only resource the configure script will
-also prevent you from trying to build inside the source tree. Instead
-a separate build tree is required. Hence a typical sequence for
-building the host-side software would be as follows:</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->$ mkdir usbhost_build
-$ cd usbhost_build
-$ <repo>packages/io/usb/slave/current/host/configure <A
-NAME="PATH"
-><IMG
-SRC="../images/callouts/1.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(1)"></A
-> <A
-NAME="VERSION"
-><IMG
-SRC="../images/callouts/2.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(2)"></A
-> <args> <A
-NAME="ARGS"
-><IMG
-SRC="../images/callouts/3.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(3)"></A
->
-$ make
-<output from make>
-$ su <A
-NAME="ROOT"
-><IMG
-SRC="../images/callouts/4.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(4)"></A
->
-$ make install
-<output from make install>
-$</PRE
-></TD
-></TR
-></TABLE
-><DIV
-CLASS="CALLOUTLIST"
-><DL
-COMPACT="COMPACT"
-><DT
-><A
-HREF="usbs-testing.html#PATH"
-><IMG
-SRC="../images/callouts/1.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(1)"></A
-></DT
-><DD
->The location of the eCos component repository should be substituted
-for <TT
-CLASS="LITERAL"
-><repo></TT
->.</DD
-><DT
-><A
-HREF="usbs-testing.html#VERSION"
-><IMG
-SRC="../images/callouts/2.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(2)"></A
-></DT
-><DD
->If the package has been obtained via CVS or anonymous CVS then the
-package version will be <TT
-CLASS="FILENAME"
->current</TT
->, as per the
-example. If instead the package has been obtained as part of a full
-eCos release or as a separate <TT
-CLASS="FILENAME"
->.epk</TT
-> file then the
-appropriate package version should be used instead of
-<TT
-CLASS="FILENAME"
->current</TT
->.</DD
-><DT
-><A
-HREF="usbs-testing.html#ARGS"
-><IMG
-SRC="../images/callouts/3.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(3)"></A
-></DT
-><DD
->The <B
-CLASS="COMMAND"
->configure</B
-> script takes the usual arguments such
-as <TT
-CLASS="PARAMETER"
-><I
->--prefix=</I
-></TT
-> to specify where the executables
-and support files should be installed. The only other parameter that
-some users may wish to specify is the location of a suitable Tcl
-installation. By default <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will use
-the existing Tcl installation in <TT
-CLASS="FILENAME"
->/usr</TT
->,
-as provided by your Linux distribution. An alternative Tcl
-installation can be specified using the parameter
-<TT
-CLASS="PARAMETER"
-><I
->--with-tcl=</I
-></TT
->, or alternatively using some
-combination of <TT
-CLASS="PARAMETER"
-><I
->--with-tcl-include</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->--with-tcl-lib</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->--with-tcl-version</I
-></TT
->. </DD
-><DT
-><A
-HREF="usbs-testing.html#ROOT"
-><IMG
-SRC="../images/callouts/4.gif"
-HSPACE="0"
-VSPACE="0"
-BORDER="0"
-ALT="(4)"></A
-></DT
-><DD
->One of the host-side executables that gets built,
-<SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
->, needs to be installed with suid
-root privileges. Although the Linux kernel makes it possible for
-applications to perform low-level USB operations such as transmitting
-bulk packets, by default access to this functionality is restricted to
-programs with superuser privileges. It is undesirable to run a complex
-program such as <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> with such
-privileges, especially since the program contains a general-purpose
-Tcl interpreter. Therefore when <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->
-starts up and discovers that it does not have sufficient access to the
-appropriate entries in <TT
-CLASS="FILENAME"
->/proc/bus/usb</TT
->,
-it spawns an instance of <SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
-> to modify
-the permissions on these entries. <SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
->
-will only do this for a USB device <TT
-CLASS="LITERAL"
->"Red Hat eCos USB
-test"</TT
->, so installing this program suid root should not
-introduce any security problems.</DD
-></DL
-></DIV
-><P
->During <B
-CLASS="COMMAND"
->make install</B
-> the following actions will take
-place: </P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
-><SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will be installed in <TT
-CLASS="FILENAME"
->/usr/local/bin</TT
->,
-or some other <TT
-CLASS="FILENAME"
->bin</TT
-> directory if
-the default location is changed at configure-time using a
-<TT
-CLASS="PARAMETER"
-><I
->--prefix=</I
-></TT
-> or similar option. It will be
-installed as the executable
-<SPAN
-CLASS="APPLICATION"
->usbhost_<version></SPAN
->, for example
-<SPAN
-CLASS="APPLICATION"
->usbhost_current</SPAN
->, thus allowing several
-releases of the USB slave package to co-exist. For convenience a
-symbolic link from <TT
-CLASS="FILENAME"
->usbhost</TT
-> to this executable
-will be created, so users can just run <B
-CLASS="COMMAND"
->usbhost</B
-> to
-access the most recently-installed version.</P
-></LI
-><LI
-><P
-><SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
-> will be installed in
-<TT
-CLASS="FILENAME"
->/usr/local/libexec/ecos/io_usb_slave_<version></TT
->.
-This program should only be run by <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->,
-not invoked directly, so it is not placed in the <TT
-CLASS="FILENAME"
->bin</TT
->
-directory. Again the presence of the package version in the directory
-name allows multiple releases of the package to co-exist.</P
-></LI
-><LI
-><P
->A Tcl script <TT
-CLASS="FILENAME"
->usbhost.tcl</TT
-> will get installed in
-the same directory as <SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
->. This Tcl
-script is loaded automatically by the
-<SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> executable. </P
-></LI
-><LI
-><P
->A number of additional Tcl scripts, for example
-<TT
-CLASS="FILENAME"
->list.tcl</TT
-> will get installed alongside
-<TT
-CLASS="FILENAME"
->usbhost.tcl</TT
->. These correspond to various test
-cases provided as standard. If a given test case is specified on the
-command line and cannot be found relative to the current directory
-then <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will search the install
-directory for these test cases.</P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->Strictly speaking installing the <TT
-CLASS="FILENAME"
->usbhost.tcl</TT
-> and
-other Tcl scripts below the <TT
-CLASS="FILENAME"
->libexec</TT
->
-directory deviates from standard practice: they are
-architecture-independent data files so should be installed below
-the <TT
-CLASS="FILENAME"
->share</TT
-> subdirectory. In
-practice the files are sufficiently small that there is no point in
-sharing them, and keeping them below <TT
-CLASS="FILENAME"
->libexec</TT
->
-simplifies the host-side software somewhat.</P
-></BLOCKQUOTE
-></DIV
-></LI
-></OL
-><P
->The <B
-CLASS="COMMAND"
->usbhost</B
-> should be run only when there is a
-suitable target attached to the USB bus and running the
-<SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> program. It will search
-<TT
-CLASS="FILENAME"
->/proc/bus/usb/devices</TT
-> for an entry corresponding
-to this program, invoke <SPAN
-CLASS="APPLICATION"
->usbchmod</SPAN
-> if
-necessary to change the access rights, and then interact with
-<SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> over the USB bus.
-<B
-CLASS="COMMAND"
->usbhost</B
-> should be invoked as follows:</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->$ usbhost [-v|--version] [-h|--help] [-V|--verbose] <test> [<test parameters>]</PRE
-></TD
-></TR
-></TABLE
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->The <TT
-CLASS="PARAMETER"
-><I
->-v</I
-></TT
-> or <TT
-CLASS="PARAMETER"
-><I
->--version</I
-></TT
->
-option will display version information for
-<SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> including the version of the USB
-slave package that was used to build the executable.</P
-></LI
-><LI
-><P
->The <TT
-CLASS="PARAMETER"
-><I
->-h</I
-></TT
-> or <TT
-CLASS="PARAMETER"
-><I
->--help</I
-></TT
-> option
-will display usage information.</P
-></LI
-><LI
-><P
->The <TT
-CLASS="PARAMETER"
-><I
->-V</I
-></TT
-> or <TT
-CLASS="PARAMETER"
-><I
->--verbose</I
-></TT
->
-option can be used to obtain more information at run-time, for example
-some output for every USB transfer. This option can be repeated
-multiple times to increase the amount of output.</P
-></LI
-><LI
-><P
->The first argument that does not begin with a hyphen specifies a test
-that should be run, in the form of a Tcl script. For example an
-argument of <TT
-CLASS="PARAMETER"
-><I
->list.tcl</I
-></TT
-> will cause
-<SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> to look for a script with that
-name, adding a <TT
-CLASS="FILENAME"
->.tcl</TT
-> suffix if necessarary, and
-run that script. <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will look in the
-current directory first, then in the install tree for standard test
-scripts provided by the USB slave package.</P
-></LI
-><LI
-><P
->Some test scripts may want their own parameters, for example a
-duration in seconds. These can be passed on the command line after
-the name of the test, for example
-<B
-CLASS="COMMAND"
->usbhost mytest 60</B
->. </P
-></LI
-></OL
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17020"
-></A
-><H2
->Writing a Test</H2
-><P
->Each test is defined by a Tcl script, running inside an interpreter
-provided by <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
->. In addition to the
-normal Tcl functionality this interpreter provides a number of
-variables and functions related to USB testing. For example there is a
-variable <TT
-CLASS="VARNAME"
->bulk_in_endpoints</TT
-> that lists all the
-endpoints on the target that can perform bulk IN operations, and a
-related array <TT
-CLASS="VARNAME"
->bulk_in</TT
-> which contains information
-such as the minimum and maximum packets sizes. There is a function
-<TT
-CLASS="FUNCTION"
->bulktest</TT
-> which can be used to perform bulk tests
-on a particular endpoint. A simple test script aimed at specific
-hardware could ignore the information variables since it would know
-exactly what USB hardware is available on the target, whereas a
-general-purpose script would use the information to adapt to the
-hardware capabilities.</P
-><P
->To avoid namespace pollution all USB-related Tcl variables and
-functions live in the <TT
-CLASS="VARNAME"
->usbtest::</TT
-> namespace.
-Therefore accessing requires either explicitly including the
-namespace any references, for example
-<TT
-CLASS="LITERAL"
->$usbtest::bulk_in_endpoints</TT
->, or by using Tcl's
-<TT
-CLASS="FUNCTION"
->namespace import</TT
-> facility.</P
-><P
->A very simple test script might look like this:</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->usbtest::bulktest 1 out 4000
-usbtest::bulktest 2 in 4000
-if { [usbtest::start 60] } {
- puts "Test successful"
-} else
- puts "Test failed"
- foreach result $usbtest::results {
- puts $result
- }
-}</PRE
-></TD
-></TR
-></TABLE
-><P
->This would perform a test run involving 4000 bulk transfers from the
-host to the target's endpoint 1, and concurrently 4000 bulk transfers
-from endpoint 2. Default settings for packet sizes, contents, and
-delays would be used. The actual test would not start running until
-<TT
-CLASS="FILENAME"
->usbtest</TT
-> is invoked, and it is expected that the
-test would complete within 60 seconds. If any failures occur then they
-are reported.</P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17035"
-></A
-><H2
->Available Hardware</H2
-><P
->Each target-side USB device driver provides information about the
-actual capabilities of the hardware, for example which endpoints are
-available. Strictly speaking it provides information about what is
-actually supported by the device driver, which may be a subset of what
-the hardware is capable of. For example, the hardware may support
-isochronous transfers on a particular endpoint but if there is no
-software support for this in the driver then this endpoint will not be
-listed. When <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> first contacts the
-<SPAN
-CLASS="APPLICATION"
->usbtarget</SPAN
-> program running on the target
-platform, it obtains this information and makes it available to test
-scripts via Tcl variables:</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="VARNAME"
->bulk_in_endpoints</TT
-></DT
-><DD
-><P
-> This is a simple list of the endpoints which can support bulk IN
- transfers. For example if the target-side hardware supports
- these transfers on endpoints 3 and 5 then the value would be
- <TT
-CLASS="LITERAL"
->"3 5"</TT
-> Typical test scripts would
- iterate over the list using something like:
- </P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> if { 0 != [llength $usbtest::bulk_in_endpoints] } {
- puts"Bulk IN endpoints: $usbtest::bulk_in_endpoints"
- foreach endpoint $usbtest:bulk_in_endpoints {
- …
- }
- }
- </PRE
-></TD
-></TR
-></TABLE
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->bulk_in()</TT
-></DT
-><DD
-><P
-> This array holds additional information about each bulk IN endpoint.
- The array is indexed by two fields, the endpoint number and one of
- <TT
-CLASS="LITERAL"
->min_size</TT
->, <TT
-CLASS="LITERAL"
->max_size</TT
->,
- <TT
-CLASS="LITERAL"
->max_in_padding</TT
-> and <TT
-CLASS="LITERAL"
->devtab</TT
->:
- </P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="LITERAL"
->min_size</TT
-></DT
-><DD
-><P
-> This field specifies a lower bound on the size of bulk transfers,
- and will typically will have a value of 1.
- </P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
-> The typical minimum transfer size of a single byte is not strictly
- speaking correct, since under some circumstances it can make sense
- to have a transfer size of zero bytes. However current target-side
- device drivers interpret a request to transfer zero bytes as a way
- for higher-level code to determine whether or not an endpoint is
- stalled, so it is not actually possible to perform zero-byte
- transfers. This issue will be addressed at some future point.
- </P
-></BLOCKQUOTE
-></DIV
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->max_size</TT
-></DT
-><DD
-><P
-> This field specifies an upper bound on the size of bulk transfers.
- Some target-side drivers may be limited to transfers of say
- 0x0FFFF bytes because of hardware limitations. In practice the
- transfer size is likely to be limited primarily to limit memory
- consumption of the test code on the target hardware, and to ensure
- that tests complete reasonably quickly. At the time of writing
- transfers are limited to 4K.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->max_in_padding</TT
-></DT
-><DD
-><P
-> On some hardware it may be necessary for the target-side device
- driver to send more data than is actually intended. For example
- the SA11x0 USB hardware cannot perform bulk transfers that are
- an exact multiple of 64 bytes, instead it must pad such
- transfers with an extra byte and the host must be ready to
- accept and discard this byte. The
- <TT
-CLASS="LITERAL"
->max_in_padding</TT
-> field indicates the amount of
- padding that is required. The low-level code inside
- <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will use this field
- automatically, and there is no need for test scripts to adjust
- packet sizes for padding. The field is provided for
- informational purposes only.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->devtab</TT
-></DT
-><DD
-><P
-> This is a string indicating whether or not the
- target-side USB device driver supports access to this endpoint
- via entries in the device table, in other words through
- conventional calls like <TT
-CLASS="FUNCTION"
->open</TT
-> and
- <TT
-CLASS="FUNCTION"
->write</TT
->. Some device drivers may only
- support low-level USB access because typically that is what gets
- used by USB class-specific packages such as USB-ethernet.
- An empty string indicates that no devtab entry is available,
- otherwise it will be something like
- <TT
-CLASS="LITERAL"
->"/dev/usbs2w"</TT
->.
- </P
-></DD
-></DL
-></DIV
-><P
-> Typical test scripts would access this data using something like:
- </P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> foreach endpoint $usbtest:bulk_in_endpoints {
- puts "Endpoint $endpoint: "
- puts " minimum transfer size $usbtest::bulk_in($endpoint,min_size)"
- puts " maximum transfer size $usbtest::bulk_in($endpoint,max_size)"
- if { 0 == $usbtest::bulk_in($endpoint,max_in_padding) } {
- puts " no IN padding required"
- } else {
- puts " $usbtest::bulk_in($endpoint,max_in_padding) bytes of IN padding required"
- }
- if { "" == $usbtest::bulk_in($endpoint,devtab) } {
- puts " no devtab entry provided"
- } else {
- puts " corresponding devtab entry is $usbtest::bulk_in($endpoint,devtab)"
- }
- }
- </PRE
-></TD
-></TR
-></TABLE
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->bulk_out_endpoint</TT
-></DT
-><DD
-><P
-> This is a simple list of the endpoints which can support bulk OUT
- transfers. It is analogous to
- <TT
-CLASS="VARNAME"
->bulk_in_endpoints</TT
->.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->bulk_out()</TT
-></DT
-><DD
-><P
-> This array holds additional information about each bulk OUT
- endpoint. It can be accessed in the same way as
- <TT
-CLASS="VARNAME"
->bulk_in()</TT
->, except that there is no
- <TT
-CLASS="LITERAL"
->max_in_padding</TT
-> field because that field only
- makes sense for IN transfers.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->control()</TT
-></DT
-><DD
-><P
-> This array holds information about the control endpoint. It contains
- two fields, <TT
-CLASS="LITERAL"
->min_size</TT
-> and
- <TT
-CLASS="LITERAL"
->max_size</TT
->. Note that there is no variable
- <TT
-CLASS="VARNAME"
->control_endpoints</TT
-> because a USB target always
- supports a single control endpoint <TT
-CLASS="LITERAL"
->0</TT
->. Similarly
- the <TT
-CLASS="VARNAME"
->control</TT
-> array does not use an endpoint number
- as the first index because that would be redundant.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->isochronous_in_endpoints</TT
-> and
- <TT
-CLASS="VARNAME"
->isochronous_in()</TT
-></DT
-><DD
-><P
-> These variables provide the same information as
- <TT
-CLASS="VARNAME"
->bulk_in_endpoints</TT
-> and <TT
-CLASS="VARNAME"
->bulk_in</TT
->,
- but for endpoints that support isochronous IN transfers.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->isochronous_out_endpoints</TT
-> and
- <TT
-CLASS="VARNAME"
->isochronous_out()</TT
-></DT
-><DD
-><P
-> These variables provide the same information as
- <TT
-CLASS="VARNAME"
->bulk_out_endpoints</TT
-> and <TT
-CLASS="VARNAME"
->bulk_out</TT
->,
- but for endpoints that support isochronous OUT transfers.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->interrupt_in_endpoints</TT
-> and
- <TT
-CLASS="VARNAME"
->interrupt_in()</TT
-></DT
-><DD
-><P
-> These variables provide the same information as
- <TT
-CLASS="VARNAME"
->bulk_in_endpoints</TT
-> and <TT
-CLASS="VARNAME"
->bulk_in</TT
->,
- but for endpoints that support interrupt IN transfers.
- </P
-></DD
-><DT
-><TT
-CLASS="VARNAME"
->interrupt_out_endpoints</TT
-> and
- <TT
-CLASS="VARNAME"
->interrupt_out()</TT
-></DT
-><DD
-><P
-> These variables provide the same information as
- <TT
-CLASS="VARNAME"
->bulk_out_endpoints</TT
-> and <TT
-CLASS="VARNAME"
->bulk_out</TT
->,
- but for endpoints that support interrupt OUT transfers.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17142"
-></A
-><H2
->Testing Bulk Transfers</H2
-><P
->The main function for initiating a bulk test is
-<TT
-CLASS="FUNCTION"
->usbtest::bulktest</TT
->. This takes three compulsory
-arguments, and can be given a number of additional arguments to
-control the exact behaviour. The compulsory arguments are:</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
->endpoint</DT
-><DD
-><P
-> This specifies the endpoint to use. It should correspond to
- one of the entries in
- <TT
-CLASS="VARNAME"
->usbtest::bulk_in_endpoints</TT
-> or
- <TT
-CLASS="VARNAME"
->usbtest::bulk_out_endpoints</TT
->, depending on the
- transfer direction.
- </P
-></DD
-><DT
->direction</DT
-><DD
-><P
-> This should be either <TT
-CLASS="LITERAL"
->in</TT
-> or <TT
-CLASS="LITERAL"
->out</TT
->.
- </P
-></DD
-><DT
->number of transfers</DT
-><DD
-><P
-> This specifies the number of transfers that should take place. The
- testing software does not currently support the concept of performing
- transfers for a given period of time because synchronising this on
- both the host and a wide range of targets is difficult. However it
- is relatively easy to work out the approximate time a number of bulk
- transfers should take place, based on a typical bandwidth of
- 1MB/second and assuming say a 1ms overhead per transfer.
- Alternatively a test script could perform a small initial run to
- determine what performance can actually be expected from a given
- target, and then use this information to run a much longer test.
- </P
-></DD
-></DL
-></DIV
-><P
->Additional arguments can be used to control the exact transfer. For
-example a <TT
-CLASS="PARAMETER"
-><I
->txdelay+</I
-></TT
-> argument can be used to
-slowly increase the delay between transfers. All such arguments involve
-a value which can be passed either as part of the argument itself,
-for example <TT
-CLASS="LITERAL"
->txdelay+=5</TT
->, or as a subsequent
-argument, <TT
-CLASS="LITERAL"
->txdelay+ 5</TT
->. The possible arguments fall
-into a number of categories: data, I/O mechanism, transmit size,
-receive size, transmit delay, and receive delay.</P
-><DIV
-CLASS="REFSECT2"
-><A
-NAME="AEN17167"
-></A
-><H3
->Data</H3
-><P
->An obvious parameter to control is the actual data that gets sent.
-This can be controlled by the argument <TT
-CLASS="PARAMETER"
-><I
->data</I
-></TT
->
-which can take one of five values: <TT
-CLASS="LITERAL"
->none</TT
->,
-<TT
-CLASS="LITERAL"
->bytefill</TT
->, <TT
-CLASS="LITERAL"
->intfill</TT
->,
-<TT
-CLASS="LITERAL"
->byteseq</TT
-> and <TT
-CLASS="LITERAL"
->wordseq</TT
->. The default
-value is <TT
-CLASS="LITERAL"
->none</TT
->.</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="LITERAL"
->none</TT
-></DT
-><DD
-><P
-> The transmit code will not attempt to fill the buffer in any way,
- and the receive code will not check it. The actual data that gets
- transferred will be whatever happened to be in the buffer before
- the transfer started.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->bytefill</TT
-></DT
-><DD
-><P
-> The entire buffer will be filled with a single byte, as per
- <TT
-CLASS="FUNCTION"
->memset</TT
->.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->intfill</TT
-></DT
-><DD
-><P
-> The buffer will be treated as an array of 32-bit integers, and will
- be filled with the same integer repeated the appropriate number of
- times. If the buffer size is not a multiple of four bytes then
- the last few bytes will be set to 0.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->byteseq</TT
-></DT
-><DD
-><P
-> The buffer will be filled with a sequence of bytes, generated by
- a linear congruential generator. If the first byte in the buffer is
- filled with the value <TT
-CLASS="LITERAL"
->x</TT
->, the next byte will be
- <TT
-CLASS="LITERAL"
->(m*x)+i</TT
->. For example a sequence of slowly
- incrementing bytes can be achieved by setting both the multiplier
- and the increment to 1. Alternatively a pseudo-random number
- sequence can be achieved using values 1103515245 and 12345, as
- per the standard C library <TT
-CLASS="FUNCTION"
->rand</TT
-> function.
- For convenience these two constants are available as Tcl
- variables <TT
-CLASS="VARNAME"
->usbtest::MULTIPLIER</TT
-> and
- <TT
-CLASS="VARNAME"
->usbtest::INCREMENT</TT
->.
- </P
-></DD
-><DT
-><TT
-CLASS="LITERAL"
->wordseq</TT
-></DT
-><DD
-><P
-> This acts like <TT
-CLASS="LITERAL"
->byteseq</TT
->, except that the buffer is
- treated as an array of 32-bit integers rather than as an array of
- bytes. If the buffer is not a multiple of four bytes then the last
- few bytes will be filled with zeroes.
- </P
-></DD
-></DL
-></DIV
-><P
->The above requires three additional parameters
-<TT
-CLASS="PARAMETER"
-><I
->data1</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->data*</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->data+</I
-></TT
->. <TT
-CLASS="PARAMETER"
-><I
->data1</I
-></TT
-> specifies
-the value to be used for byte or word fills, or the first number when
-calculating a sequence. The default value is <TT
-CLASS="LITERAL"
->0</TT
->.
-<TT
-CLASS="PARAMETER"
-><I
->data*</I
-></TT
-> and <TT
-CLASS="PARAMETER"
-><I
->data+</I
-></TT
-> specify
-the multiplier and increment for a sequence, and have default values
-of <TT
-CLASS="LITERAL"
->1</TT
-> and <TT
-CLASS="LITERAL"
->0</TT
-> respectively. For
-example, to perform a bulk transfer of a pseudo-random sequence of
-integers starting with 42 the following code could be used:</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->bulktest 2 IN 1000 data=wordseq data1=42 \
- data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT</PRE
-></TD
-></TR
-></TABLE
-><P
->The above parameters define what data gets transferred for the first
-transfer, but a test can involve multiple transfers. The data format
-will be the same for all transfers, but it is possible to adjust the
-current value, the multiplier, and the increment between each
-transfer. This is achieved with parameters <TT
-CLASS="PARAMETER"
-><I
->data1*</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->data1+</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->data**</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->data*+</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->data+*</I
-></TT
->, and
-<TT
-CLASS="PARAMETER"
-><I
->data++</I
-></TT
->, with default values of 1 for each
-multiplier and 0 for each increment. For example, if the multiplier
-for the first transfer is set to <TT
-CLASS="LITERAL"
->2</TT
-> using
-<TT
-CLASS="PARAMETER"
-><I
->data*</I
-></TT
->, and arguments
-<TT
-CLASS="LITERAL"
->data** 2</TT
-> and <TT
-CLASS="LITERAL"
->data*+ -1</TT
-> are also
-supplied, then the multiplier for subsequent transfers will be
-<TT
-CLASS="LITERAL"
->3</TT
->, <TT
-CLASS="LITERAL"
->5</TT
->, <TT
-CLASS="LITERAL"
->9</TT
->,
-….</P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->Currently it is not possible for a test script to send specific data,
-for example a specific sequence of bytes captured by a protocol analyser
-that caused a problem. If the transfer was from host to target then
-the target would have to know the exact sequence of bytes to expect,
-which means transferring data over the USB bus when that data is known
-to have caused problems in the past. Similarly for target to host
-transfers the target would have to know what bytes to send. A possible
-future extension of the USB testing support would allow for bounce
-operations, where a given message is first sent to the target and then
-sent back to the host, with only the host checking that the data was
-returned correctly.</P
-></BLOCKQUOTE
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT2"
-><A
-NAME="AEN17237"
-></A
-><H3
->I/O Mechanism</H3
-><P
->On the target side USB transfers can happen using either low-level
-USB calls such as <TT
-CLASS="FUNCTION"
->usbs_start_rx_buffer</TT
->, or by
-higher-level calls which go through the device table. By default the
-target-side code will use the low-level calls. If it is desired to
-test the higher-level calls instead, for example because those are
-what the application uses, then that can be achieved with an
-argument <TT
-CLASS="PARAMETER"
-><I
->mechanism=devtab</I
-></TT
->.</P
-></DIV
-><DIV
-CLASS="REFSECT2"
-><A
-NAME="AEN17242"
-></A
-><H3
->Transmit Size</H3
-><P
->The next set of arguments can be used to control the size of the
-transmitted buffer: <TT
-CLASS="PARAMETER"
-><I
->txsize1</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->txsize>=</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->txsize<=</I
-></TT
->
-<TT
-CLASS="PARAMETER"
-><I
->txsize*</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->txsize/</I
-></TT
->,
-and <TT
-CLASS="PARAMETER"
-><I
->txsize+</I
-></TT
->.</P
-><P
-><TT
-CLASS="PARAMETER"
-><I
->txsize1</I
-></TT
-> determines the size of the first
-transfer, and has a default value of 32 bytes. The size of the next
-transfer is calculated by first multiplying by the
-<TT
-CLASS="PARAMETER"
-><I
->txsize*</I
-></TT
-> value, then dividing by the
-<TT
-CLASS="PARAMETER"
-><I
->txsize/</I
-></TT
-> value, and finally adding the
-<TT
-CLASS="PARAMETER"
-><I
->txsize+</I
-></TT
-> value. The defaults for these are
-<TT
-CLASS="LITERAL"
->1</TT
->, <TT
-CLASS="LITERAL"
->1</TT
->, and <TT
-CLASS="LITERAL"
->0</TT
->
-respectively, which means that the transfer size will remain
-unchanged. If for example the transfer size should increase by
-approximately 50 per cent each time then suitable values might be
-<TT
-CLASS="LITERAL"
->txsize* 3</TT
->, <TT
-CLASS="LITERAL"
->txsize/ 2</TT
->,
-and <TT
-CLASS="LITERAL"
->txsize+ 1</TT
->. </P
-><P
->The <TT
-CLASS="PARAMETER"
-><I
->txsize>=</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->txsize<=</I
-></TT
-> arguments can be used to impose
-lower and upper bounds on the transfer. By default the
-<TT
-CLASS="LITERAL"
->min_size</TT
-> and <TT
-CLASS="LITERAL"
->max_size</TT
-> values
-appropriate for the endpoint will be used. If at any time the
-current size falls outside the bounds then it will be normalized.</P
-></DIV
-><DIV
-CLASS="REFSECT2"
-><A
-NAME="AEN17267"
-></A
-><H3
->Receive Size</H3
-><P
->The receive size, in other words the number of bytes that either host
-or target will expect to receive as opposed to the number of bytes
-that actually get sent, can be adjusted using a similar set of
-arguments: <TT
-CLASS="PARAMETER"
-><I
->rxsize1</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxsize>=</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxsize<=</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxsize*</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->rxsize/</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->rxsize+</I
-></TT
->. The current receive size will be
-adjusted between transfers just like the transmit size. However when
-communicating over USB it is not a good idea to attempt to receive
-less data than will actually be sent: typically neither the hardware
-nor the software will be able to do anything useful with the excess,
-so there will be problems. Therefore if at any time the calculated
-receive size is less than the transmit size, the actual receive will
-be for the exact number of bytes that will get transmitted. However
-this will not affect the calculations for the next receive size.</P
-><P
->The default values for <TT
-CLASS="PARAMETER"
-><I
->rxsize1</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxsize*</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->rxsize/</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->rxsize+</I
-></TT
-> are <TT
-CLASS="LITERAL"
->0</TT
->,
-<TT
-CLASS="LITERAL"
->1</TT
->, <TT
-CLASS="LITERAL"
->1</TT
-> and <TT
-CLASS="LITERAL"
->0</TT
->
-respectively. This means that the calculated receive size will always
-be less than the transmit size, so the receive operation will be for
-the exact number of bytes transmitted. For some USB protocols this
-would not accurately reflect the traffic that will happen. For example
-with USB-ethernet transfer sizes will vary between 16 and 1516 bytes,
-so the receiver will always expect up to 1516 bytes. This can be
-achieved using <TT
-CLASS="LITERAL"
->rxsize1 1516</TT
->, leaving the
-other parameters at their default values.</P
-><P
->For target hardware which involves non-zero
-<TT
-CLASS="LITERAL"
->max_in_padding</TT
->, on the host side the padding will
-be added automatically to the receive size if necessary.</P
-></DIV
-><DIV
-CLASS="REFSECT2"
-><A
-NAME="AEN17288"
-></A
-><H3
->Transmit and Receive Delays</H3
-><P
->Typically during the testing there will be some minor delays between
-transfers on both host and target. Some of these delays will be caused
-by timeslicing, for example another process running on the host, or a
-concurrent test thread running inside the target. Other delays will be
-caused by the USB bus itself, for example activity from another device
-on the bus. However it is desirable that test cases be allowed to
-inject additional and somewhat more controlled delays into the system,
-for example to make sure that the target behaves correctly even if the
-target is not yet ready to receive data from the host.</P
-><P
->The transmit delay is controlled by six parameters:
-<TT
-CLASS="PARAMETER"
-><I
->txdelay1</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->txdelay*</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->txdelay/</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->txdelay+</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->txdelay>=</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->txdelay<=</I
-></TT
->. The default values for these are
-<TT
-CLASS="LITERAL"
->0</TT
->, <TT
-CLASS="LITERAL"
->1</TT
->, <TT
-CLASS="LITERAL"
->1</TT
->,
-<TT
-CLASS="LITERAL"
->0</TT
->, <TT
-CLASS="LITERAL"
->0</TT
-> and
-<TT
-CLASS="LITERAL"
->1000000000</TT
-> respectively, so that by default
-transmits will happen as quickly as possible. Delays are measured in
-nanoseconds, so a value of <TT
-CLASS="LITERAL"
->1000000</TT
-> would correspond
-to a delay of 0.001 seconds or one millisecond. By default delays have
-an upper bound of one second. Between transfers the transmit delay is
-updated in much the same was as the transfer sizes.</P
-><P
->The receive delay is controlled by a similar set of six parameters:
-<TT
-CLASS="PARAMETER"
-><I
->rxdelay1</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->rxdelay*</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxdelay/</I
-></TT
->, <TT
-CLASS="PARAMETER"
-><I
->rxdelay+</I
-></TT
->,
-<TT
-CLASS="PARAMETER"
-><I
->rxdelay>=</I
-></TT
-> and
-<TT
-CLASS="PARAMETER"
-><I
->rxdelay<=</I
-></TT
->. The default values for these are
-the same as for transmit delays.</P
-><P
->The transmit delay is used on the side which sends data over the USB
-bus, so for a bulk IN transfer it is the target that sends data and
-hence sleeps for the specified transmit delay, while the host receives
-data sleeps for the receive delay. For an OUT transfer the positions
-are reversed.</P
-><P
->It should be noted that although the delays are measured in
-nanoseconds, the actual delays will be much less precise and are
-likely to be of the order of milliseconds. The exact details will
-depend on the kernel clock speed.</P
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17314"
-></A
-><H2
->Other Types of Transfer</H2
-><P
->Support for testing other types of USB traffic such as isochronous
-transfers is not yet implemented.</P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17317"
-></A
-><H2
->Starting a Test and Collecting Results</H2
-><P
->A USB test script should prepare one or more transfers using
-appropriate functions such as <TT
-CLASS="FUNCTION"
->usbtest::bulktest</TT
->.
-Once all the individual tests have been prepared they can be started
-by a call to <TT
-CLASS="FUNCTION"
->usbtest::start</TT
->. This takes a single
-argument, a maximum duration measured in seconds. If all transfers
-have not been completed in the specified time then any remaining
-transfers will be aborted.</P
-><P
-><TT
-CLASS="FUNCTION"
->usbtest::start</TT
-> will return <TT
-CLASS="LITERAL"
->1</TT
->
-if all the tests have succeeded, or <TT
-CLASS="LITERAL"
->0</TT
-> if any of
-them have failed. More detailed reports will be stored in the
-Tcl variable <TT
-CLASS="VARNAME"
->usbtests::results</TT
->, which will be a
-list of string messages.</P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17327"
-></A
-><H2
->Existing Test Scripts</H2
-><P
->A number of test scripts are provided as standard. These are located
-in the <TT
-CLASS="FILENAME"
->host</TT
-> subdirectory of the
-common USB slave package, and will be installed as part of the process
-of building the host-side software. When a script is specified on the
-command line <SPAN
-CLASS="APPLICATION"
->usbhost</SPAN
-> will first search for
-it in the current directory, then in the install tree. Standard
-test scripts include the following:</P
-><P
-></P
-><DIV
-CLASS="VARIABLELIST"
-><DL
-><DT
-><TT
-CLASS="FILENAME"
->list.tcl</TT
-></DT
-><DD
-><P
-> This script simply displays information about the capabilities
- of the target platform, as provided by the target-side USB
- device driver. It can help with tracking down problems, but its
- primary purpose is to let users check that everything is working
- correctly: if running <B
-CLASS="COMMAND"
->usbhost list.tcl</B
->
- outputs sensible information then the user knows that the
- target side is running correctly and that communication between
- host and target is possible.
- </P
-></DD
-><DT
-><TT
-CLASS="FILENAME"
->verbose.tcl</TT
-></DT
-><DD
-><P
-> The target-side code can provide information about what
- is happening while tests are prepared and run. This facility
- should not normally be used since the extra I/O involved will
- significantly affect the behaviour of the system, but in some
- circumstances it may prove useful. Since an eCos application
- cannot easily be given command-line arguments the target-side
- verbosity level cannot be controlled using
- <TT
-CLASS="PARAMETER"
-><I
->-V</I
-></TT
-> or <TT
-CLASS="PARAMETER"
-><I
->--verbose</I
-></TT
->
- options. Instead it can be controlled from inside
- <SPAN
-CLASS="APPLICATION"
->gdb</SPAN
-> by changing the integer
- variable <TT
-CLASS="VARNAME"
->verbose</TT
->. Alternatively it can
- be manipulated by running the test script
- <TT
-CLASS="FILENAME"
->verbose.tcl</TT
->. This script takes a single
- argument, the desired verbosity level, which should be a small
- integer. For example, to disable target-side run-time logging
- the command <B
-CLASS="COMMAND"
->usbhost verbose 0</B
-> can
- be used.
- </P
-></DD
-></DL
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN17350"
-></A
-><H2
->Possible Problems</H2
-><P
->If all transfers succeed within the specified time then both host and
-target remain in synch and further tests can be run without problem.
-However, if at any time a failure occurs then things get more
-complicated. For example, if the current test involves a series of
-bulk OUT transfers and the target detects that for one of these
-transfers it received less data than was expected then the test has
-failed, and the target will stop accepting data on this endpoint.
-However the host-side software may not have detected anything wrong
-and is now blocked trying to send the next lot of data.</P
-><P
->The test code goes to considerable effort to recover from problems
-such as these. On the host-side separate threads are used for
-concurrent transfers, and on the target-side appropriate asynchronous
-I/O mechanisms are used. In addition there is a control thread on the
-host that checks the state of all the main host-side threads, and the
-state of the target using private control messages. If it discovers
-that one side has stopped sending or receiving data because of an
-error and the other side is blocked as a result, it will set certain
-flags and then cause one additional transfer to take place. That
-additional transfer will have the effect of unblocking the other side,
-which then discovers that an error has occurred by checking the
-appropriate flags. In this way both host and target should end up back
-in synch, and it is possible to move on to the next set of tests.</P
-><P
->However, the above assumes that the testing has not triggered any
-serious hardware conditions. If instead the target-side hardware has
-been left in some strange state so that, for example, it will no
-longer raise an interrupt for traffic on a particular endpoint then
-recovery is not currently possible, and the testing software will just
-hang.</P
-><P
->A possible future enhancement to the testing software would allow the
-host-side to raise a USB reset signal whenever a failure occurs, in
-the hope that this would clear any remaining problems within the
-target-side USB hardware.</P
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="usbs-writing.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="io-usb-slave-eth.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Writing a USB Device Driver</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="io-usb-slave.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->eCos Support for Developing USB-ethernet Peripherals</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff