usbs-testing.html

encos_rtos一款精致小巧的实时嵌入式操作系统 ＋CODEWORR 教程

></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*&nbsp;3</TT
>, <TT
CLASS="LITERAL"
>txsize/&nbsp;2</TT
>,
and <TT
CLASS="LITERAL"
>txsize+&nbsp;1</TT
>. </P
><P
>The <TT
CLASS="PARAMETER"
><I
>txsize&gt;=</I
></TT
> and
<TT
CLASS="PARAMETER"
><I
>txsize&lt;=</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&gt;=</I
></TT
>,
<TT
CLASS="PARAMETER"
><I
>rxsize&lt;=</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&nbsp;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&gt;=</I
></TT
> and
<TT
CLASS="PARAMETER"
><I
>txdelay&lt;=</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&gt;=</I
></TT
> and
<TT
CLASS="PARAMETER"
><I
>rxdelay&lt;=</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&nbsp;verbose&nbsp;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
>