usbs-testing.html

ecos源代码包

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_&lt;version&gt;</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] &lt;test&gt; [&lt;test parameters&gt;]</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&nbsp;mytest&nbsp;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"
>&quot;3 5&quot;</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 {
          &#8230;
      }
  }
  </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"
>&quot;/dev/usbs2w&quot;</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.