1 <!-- 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. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos USB Slave Support"
23 HREF="io-usb-slave.html"><LINK
25 TITLE="Writing a USB Device Driver"
26 HREF="usbs-writing.html"><LINK
28 TITLE="eCos Support for Developing USB-ethernet Peripherals"
29 HREF="io-usb-slave-eth.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="usbs-writing.html"
71 HREF="io-usb-slave-eth.html"
82 NAME="USBS-TESTING">Testing</H1
90 >Testing -- Testing of USB Device Drivers</DIV
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
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
124 > There is a single target-side program
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
134 > which will tell it what test or
139 mechanisms for running a wide range of tests.
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
155 >usbs_testing_endpoint</SPAN
161 > There is a single host-side program
165 >, which acts as a counterpart to
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
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
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
199 >usbtest::bulktest</TT
200 >, so the script can perform
201 the desired test or tests.
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
212 >, or alternatively writing a
213 single script that just invokes other scripts.
218 >The current implementation of <SPAN
222 depends heavily on functionality provided by the Linux kernel and in
223 particular the usbdevfs support. It uses
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
231 >/proc/bus/usb/xxx/yyy</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
247 >Building and Running the Target-side Code</H2
249 >The target-side component of the USB testing software consists of a
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
262 >CYGBLD_IO_USB_SLAVE_USBTEST</TT
263 > to add the program to
264 the list of tests for the current configuration.</P
270 require anything unusual, so it can be run in a normal
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
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
287 >"Red Hat eCos USB
289 >, so it will ignore the peripheral. When the
293 > program is run on the host it will
294 connect to the target-side software, and testing can now commence.</P
302 >Building and Running the Host-side Code</H2
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
317 >The host-side software should be built via the usual sequence of
318 "configure/make/make install". It can only be built on a
319 Linux host and the <B
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
336 >$ mkdir usbhost_build
338 $ <repo>packages/io/usb/slave/current/host/configure <A
341 SRC="../images/callouts/1.gif"
349 SRC="../images/callouts/2.gif"
357 SRC="../images/callouts/3.gif"
364 <output from make>
368 SRC="../images/callouts/4.gif"
375 <output from make install>
386 HREF="usbs-testing.html#PATH"
388 SRC="../images/callouts/1.gif"
395 >The location of the eCos component repository should be substituted
402 HREF="usbs-testing.html#VERSION"
404 SRC="../images/callouts/2.gif"
411 >If the package has been obtained via CVS or anonymous CVS then the
412 package version will be <TT
416 example. If instead the package has been obtained as part of a full
417 eCos release or as a separate <TT
421 appropriate package version should be used instead of
428 HREF="usbs-testing.html#ARGS"
430 SRC="../images/callouts/3.gif"
440 > script takes the usual arguments such
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
453 the existing Tcl installation in <TT
457 as provided by your Linux distribution. An alternative Tcl
458 installation can be specified using the parameter
464 >, or alternatively using some
468 >--with-tcl-include</I
480 >--with-tcl-version</I
485 HREF="usbs-testing.html#ROOT"
487 SRC="../images/callouts/4.gif"
494 >One of the host-side executables that gets built,
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
507 privileges, especially since the program contains a general-purpose
508 Tcl interpreter. Therefore when <SPAN
512 starts up and discovers that it does not have sufficient access to the
513 appropriate entries in <TT
517 it spawns an instance of <SPAN
521 the permissions on these entries. <SPAN
525 will only do this for a USB device <TT
527 >"Red Hat eCos USB
529 >, so installing this program suid root should not
530 introduce any security problems.</DD
537 > the following actions will take
548 > will be installed in <TT
556 the default location is changed at configure-time using a
562 > or similar option. It will be
563 installed as the executable
566 >usbhost_<version></SPAN
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
577 will be created, so users can just run <B
581 access the most recently-installed version.</P
588 > will be installed in
591 >/usr/local/libexec/ecos/io_usb_slave_<version></TT
593 This program should only be run by <SPAN
597 not invoked directly, so it is not placed in the <TT
601 directory. Again the presence of the package version in the directory
602 name allows multiple releases of the package to co-exist.</P
609 > will get installed in
610 the same directory as <SPAN
614 script is loaded automatically by the
622 >A number of additional Tcl scripts, for example
626 > will get installed alongside
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
636 > will search the install
637 directory for these test cases.</P
645 >Strictly speaking installing the <TT
649 other Tcl scripts below the <TT
653 directory deviates from standard practice: they are
654 architecture-independent data files so should be installed below
659 practice the files are sufficiently small that there is no point in
660 sharing them, and keeping them below <TT
664 simplifies the host-side software somewhat.</P
673 > should be run only when there is a
674 suitable target attached to the USB bus and running the
678 > program. It will search
681 >/proc/bus/usb/devices</TT
682 > for an entry corresponding
683 to this program, invoke <SPAN
687 necessary to change the access rights, and then interact with
695 > should be invoked as follows:</P
704 >$ usbhost [-v|--version] [-h|--help] [-V|--verbose] <test> [<test parameters>]</PRE
725 option will display version information for
729 > including the version of the USB
730 slave package that was used to build the executable.</P
745 will display usage information.</P
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
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
777 > to look for a script with that
781 > suffix if necessarary, and
782 run that script. <SPAN
786 current directory first, then in the install tree for standard test
787 scripts provided by the USB slave package.</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
796 >usbhost mytest 60</B
809 >Each test is defined by a Tcl script, running inside an interpreter
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
818 >bulk_in_endpoints</TT
820 endpoints on the target that can perform bulk IN operations, and a
824 > which contains information
825 such as the minimum and maximum packets sizes. There is a function
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
836 >To avoid namespace pollution all USB-related Tcl variables and
837 functions live in the <TT
841 Therefore accessing requires either explicitly including the
842 namespace any references, for example
845 >$usbtest::bulk_in_endpoints</TT
849 >namespace import</TT
852 >A very simple test script might look like this:</P
860 CLASS="PROGRAMLISTING"
861 >usbtest::bulktest 1 out 4000
862 usbtest::bulktest 2 in 4000
863 if { [usbtest::start 60] } {
864 puts "Test successful"
867 foreach result $usbtest::results {
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
882 > is invoked, and it is expected that the
883 test would complete within 60 seconds. If any failures occur then they
892 >Available Hardware</H2
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
908 > program running on the target
909 platform, it obtains this information and makes it available to test
910 scripts via Tcl variables:</P
919 >bulk_in_endpoints</TT
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
929 > Typical test scripts would
930 iterate over the list using something like:
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 {
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
987 > This field specifies a lower bound on the size of bulk transfers,
988 and will typically will have a value of 1.
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.
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.
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
1040 > field indicates the amount of
1041 padding that is required. The low-level code inside
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.
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
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
1075 >"/dev/usbs2w"</TT
1082 > Typical test scripts would access this data using something like:
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"
1099 puts " $usbtest::bulk_in($endpoint,max_in_padding) bytes of IN padding required"
1101 if { "" == $usbtest::bulk_in($endpoint,devtab) } {
1102 puts " no devtab entry provided"
1104 puts " corresponding devtab entry is $usbtest::bulk_in($endpoint,devtab)"
1115 >bulk_out_endpoint</TT
1119 > This is a simple list of the endpoints which can support bulk OUT
1120 transfers. It is analogous to
1123 >bulk_in_endpoints</TT
1134 > This array holds additional information about each bulk OUT
1135 endpoint. It can be accessed in the same way as
1139 >, except that there is no
1143 > field because that field only
1144 makes sense for IN transfers.
1154 > This array holds information about the control endpoint. It contains
1162 >. Note that there is no variable
1165 >control_endpoints</TT
1166 > because a USB target always
1167 supports a single control endpoint <TT
1174 > array does not use an endpoint number
1175 as the first index because that would be redundant.
1181 >isochronous_in_endpoints</TT
1185 >isochronous_in()</TT
1189 > These variables provide the same information as
1192 >bulk_in_endpoints</TT
1197 but for endpoints that support isochronous IN transfers.
1203 >isochronous_out_endpoints</TT
1207 >isochronous_out()</TT
1211 > These variables provide the same information as
1214 >bulk_out_endpoints</TT
1219 but for endpoints that support isochronous OUT transfers.
1225 >interrupt_in_endpoints</TT
1233 > These variables provide the same information as
1236 >bulk_in_endpoints</TT
1241 but for endpoints that support interrupt IN transfers.
1247 >interrupt_out_endpoints</TT
1251 >interrupt_out()</TT
1255 > These variables provide the same information as
1258 >bulk_out_endpoints</TT
1263 but for endpoints that support interrupt OUT transfers.
1275 >Testing Bulk Transfers</H2
1277 >The main function for initiating a bulk test is
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
1287 CLASS="VARIABLELIST"
1293 > This specifies the endpoint to use. It should correspond to
1294 one of the entries in
1297 >usbtest::bulk_in_endpoints</TT
1301 >usbtest::bulk_out_endpoints</TT
1310 > This should be either <TT
1320 >number of transfers</DT
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.
1338 >Additional arguments can be used to control the exact transfer. For
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,
1350 >, or as a subsequent
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
1365 >An obvious parameter to control is the actual data that gets sent.
1366 This can be controlled by the argument <TT
1372 which can take one of five values: <TT
1397 CLASS="VARIABLELIST"
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.
1419 > The entire buffer will be filled with a single byte, as per
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.
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
1451 >, the next byte will be
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
1463 For convenience these two constants are available as Tcl
1466 >usbtest::MULTIPLIER</TT
1470 >usbtest::INCREMENT</TT
1481 > This acts like <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.
1493 >The above requires three additional parameters
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
1532 the multiplier and increment for a sequence, and have default values
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
1549 CLASS="PROGRAMLISTING"
1550 >bulktest 2 IN 1000 data=wordseq data1=42 \
1551 data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT</PRE
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
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
1612 supplied, then the multiplier for subsequent transfers will be
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
1653 >On the target side USB transfers can happen using either low-level
1654 USB calls such as <TT
1656 >usbs_start_rx_buffer</TT
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
1665 >mechanism=devtab</I
1677 >The next set of arguments can be used to control the size of the
1678 transmitted buffer: <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
1726 > value, then dividing by the
1732 > value, and finally adding the
1738 > value. The defaults for these are
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
1775 > arguments can be used to impose
1776 lower and upper bounds on the transfer. By default the
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
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
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
1842 >The default values for <TT
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
1886 >rxsize1 1516</TT
1888 other parameters at their default values.</P
1890 >For target hardware which involves non-zero
1894 >, on the host side the padding will
1895 be added automatically to the receive size if necessary.</P
1903 >Transmit and Receive Delays</H3
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
1915 >The transmit delay is controlled by six parameters:
1949 >. The default values for these are
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
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
1980 >The receive delay is controlled by a similar set of six parameters:
2014 >. The default values for these are
2015 the same as for transmit delays.</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
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
2035 >Other Types of Transfer</H2
2037 >Support for testing other types of USB traffic such as isochronous
2038 transfers is not yet implemented.</P
2046 >Starting a Test and Collecting Results</H2
2048 >A USB test script should prepare one or more transfers using
2049 appropriate functions such as <TT
2051 >usbtest::bulktest</TT
2053 Once all the individual tests have been prepared they can be started
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
2069 if all the tests have succeeded, or <TT
2073 them have failed. More detailed reports will be stored in the
2076 >usbtests::results</TT
2078 list of string messages.</P
2086 >Existing Test Scripts</H2
2088 >A number of test scripts are provided as standard. These are located
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
2098 > will first search for
2099 it in the current directory, then in the install tree. Standard
2100 test scripts include the following:</P
2104 CLASS="VARIABLELIST"
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
2119 >usbhost list.tcl</B
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.
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
2151 options. Instead it can be controlled from inside
2155 > by changing the integer
2159 >. Alternatively it can
2160 be manipulated by running the test script
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
2169 >usbhost verbose 0</B
2183 >Possible Problems</H2
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
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
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
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
2226 SUMMARY="Footer navigation table"
2237 HREF="usbs-writing.html"
2246 HREF="ecos-ref.html"
2255 HREF="io-usb-slave-eth.html"
2265 >Writing a USB Device Driver</TD
2271 HREF="io-usb-slave.html"
2279 >eCos Support for Developing USB-ethernet Peripherals</TD
projects / karo-tx-redboot.git / blob