1 <!-- Copyright (C) 2002 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 substantively modified versions of this -->
7 <!-- document is prohibited without the explicit permission of the -->
8 <!-- copyright holder. -->
9 <!-- Distribution of the work or derivative of the work in any -->
10 <!-- standard (paper) book form is prohibited unless prior -->
11 <!-- permission is obtained from the copyright holder. -->
16 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
19 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
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"></HEAD
45 >eCos USB Slave Support</TH
53 HREF="usbs-writing.html"
83 >Testing -- Testing of USB Device Drivers</DIV
92 >The support for USB testing provided by the eCos USB common slave
93 package is somewhat different in nature from the kind of testing used
94 in many other packages. One obvious problem is that USB tests cannot
95 be run on just a bare target platform: instead the target platform
96 must be connected to a suitable USB host machine, and that host
97 machine must be running appropriate software for the test code to
98 interact with. This is very different from say a kernel test which
99 typically will have no external dependencies. Another important
100 difference between USB testing and say a C library
104 > test is sensitivity to timing and to
105 hardware boundary conditions: although a simple test case that just
106 performs a small number of USB transfers is better than no testing at
107 all, it should also be possible to run tests for hours or days on end,
108 under a variety of loads. In order to provide the required
109 functionality the basic architecture of the USB testing support is as
117 > There is a single target-side program
121 >. By default when this is run
122 on a target platform it will appear to do nothing. In fact it is
123 waiting to be contacted by another program
127 > which will tell it what test or
132 mechanisms for running a wide range of tests.
140 > is a generic program, but USB
141 testing depends to some extent on the functionality provided by the
142 hardware. For example there is no point in testing bulk transmits
143 to endpoint 12 if the target hardware does not support an endpoint
144 12. Therefore each USB device driver should supply information about
145 what the hardware is actually capable of, in the form of an array of
148 >usbs_testing_endpoint</SPAN
154 > There is a single host-side program
158 >, which acts as a counterpart to
166 > has no built-in knowledge of
167 the test or tests that are supposed to run, it only provides
168 mechanisms for running a wide range of tests. On start-up
172 > will search the USB bus for
173 hardware running the target-side program, specifically a USB device
174 that identifies itself as the product <TT
186 > contains a Tcl interpreter, and
187 will execute any Tcl scripts specified on the command line
188 together with appropriate arguments. The Tcl interpreter has been
189 extended with various commands such as
192 >usbtest::bulktest</TT
193 >, so the script can perform
194 the desired test or tests.
199 > Adding a new test simply involves writing a short Tcl script that
200 invokes the appropriate USB-specific commands. Running multiple
201 tests involves passing appropriate arguments to
205 >, or alternatively writing a
206 single script that just invokes other scripts.
211 >The current implementation of <SPAN
215 depends heavily on functionality provided by the Linux kernel and in
216 particular the usbdevfs support. It uses
219 >/proc/bus/usb/devices</TT
220 > to find out what devices
221 are attached to the bus, and will then access the device by opening
224 >/proc/bus/usb/xxx/yyy</TT
229 > operations. This allows USB testing to take
230 place without having to write a new host-side device driver, but
231 getting the code working on host machines not running Linux would
232 obviously be problematical.</P
240 >Building and Running the Target-side Code</H2
242 >The target-side component of the USB testing software consists of a
247 support for a range of different tests, under the control of host-side
248 software. This program is not built by default alongside other eCos
249 test cases since it will only operate in certain environments,
250 specifically when the target board's connector is plugged into a Linux
251 host, and when the appropriate host-side software has been installed
252 on that host. Instead the user must enable a configuration option
255 >CYGBLD_IO_USB_SLAVE_USBTEST</TT
256 > to add the program to
257 the list of tests for the current configuration.</P
263 require anything unusual, so it can be run in a normal
267 > session just like any eCos application.
268 After initialization the program will wait for activity from the host.
269 Depending on the hardware, the Linux host will detect that a new USB
270 peripheral is present on the bus either when the
274 > initialization is complete or
275 when the cable between target and host is connected. The host will
276 perform the normal USB enumeration sequence and discover that the
277 peripheral does not match any known vendor or product id and that
278 there is no device driver for <TT
280 >"Red Hat eCos USB
282 >, so it will ignore the peripheral. When the
286 > program is run on the host it will
287 connect to the target-side software, and testing can now commence.</P
295 >Building and Running the Host-side Code</H2
303 >In theory the host-side software should be built when the package is
304 installed in the component repository, and removed when a package
305 is uninstalled. The current eCos administration tool does not provide
306 this functionality.</P
310 >The host-side software should be built via the usual sequence of
311 "configure/make/make install". It can only be built on a
312 Linux host and the <B
316 explicit test for this. Because the eCos component repository should
317 generally be treated as a read-only resource the configure script will
318 also prevent you from trying to build inside the source tree. Instead
319 a separate build tree is required. Hence a typical sequence for
320 building the host-side software would be as follows:</P
329 >$ mkdir usbhost_build
331 $ <repo>packages/io/usb/slave/current/host/configure <A
334 SRC="../images/callouts/1.gif"
342 SRC="../images/callouts/2.gif"
350 SRC="../images/callouts/3.gif"
357 <output from make>
361 SRC="../images/callouts/4.gif"
368 <output from make install>
379 HREF="usbs-testing.html#PATH"
381 SRC="../images/callouts/1.gif"
388 >The location of the eCos component repository should be substituted
395 HREF="usbs-testing.html#VERSION"
397 SRC="../images/callouts/2.gif"
404 >If the package has been obtained via CVS or anonymous CVS then the
405 package version will be <TT
409 example. If instead the package has been obtained as part of a full
410 eCos release or as a separate <TT
414 appropriate package version should be used instead of
421 HREF="usbs-testing.html#ARGS"
423 SRC="../images/callouts/3.gif"
433 > script takes the usual arguments such
439 > to specify where the executables
440 and support files should be installed. The only other parameter that
441 some users may wish to specify is the location of a suitable Tcl
442 installation. By default <SPAN
446 the existing Tcl installation in <TT
450 as provided by your Linux distribution. An alternative Tcl
451 installation can be specified using the parameter
457 >, or alternatively using some
461 >--with-tcl-include</I
473 >--with-tcl-version</I
478 HREF="usbs-testing.html#ROOT"
480 SRC="../images/callouts/4.gif"
487 >One of the host-side executables that gets built,
491 >, needs to be installed with suid
492 root privileges. Although the Linux kernel makes it possible for
493 applications to perform low-level USB operations such as transmitting
494 bulk packets, by default access to this functionality is restricted to
495 programs with superuser privileges. It is undesirable to run a complex
496 program such as <SPAN
500 privileges, especially since the program contains a general-purpose
501 Tcl interpreter. Therefore when <SPAN
505 starts up and discovers that it does not have sufficient access to the
506 appropriate entries in <TT
510 it spawns an instance of <SPAN
514 the permissions on these entries. <SPAN
518 will only do this for a USB device <TT
520 >"Red Hat eCos USB
522 >, so installing this program suid root should not
523 introduce any security problems.</DD
530 > the following actions will take
541 > will be installed in <TT
549 the default location is changed at configure-time using a
555 > or similar option. It will be
556 installed as the executable
559 >usbhost_<version></SPAN
563 >usbhost_current</SPAN
564 >, thus allowing several
565 releases of the USB slave package to co-exist. For convenience a
566 symbolic link from <TT
570 will be created, so users can just run <B
574 access the most recently-installed version.</P
581 > will be installed in
584 >/usr/local/libexec/ecos/io_usb_slave_<version></TT
586 This program should only be run by <SPAN
590 not invoked directly, so it is not placed in the <TT
594 directory. Again the presence of the package version in the directory
595 name allows multiple releases of the package to co-exist.</P
602 > will get installed in
603 the same directory as <SPAN
607 script is loaded automatically by the
615 >A number of additional Tcl scripts, for example
619 > will get installed alongside
623 >. These correspond to various test
624 cases provided as standard. If a given test case is specified on the
625 command line and cannot be found relative to the current directory
629 > will search the install
630 directory for these test cases.</P
638 >Strictly speaking installing the <TT
642 other Tcl scripts below the <TT
646 directory deviates from standard practice: they are
647 architecture-independent data files so should be installed below
652 practice the files are sufficiently small that there is no point in
653 sharing them, and keeping them below <TT
657 simplifies the host-side software somewhat.</P
666 > should be run only when there is a
667 suitable target attached to the USB bus and running the
671 > program. It will search
674 >/proc/bus/usb/devices</TT
675 > for an entry corresponding
676 to this program, invoke <SPAN
680 necessary to change the access rights, and then interact with
688 > should be invoked as follows:</P
697 >$ usbhost [-v|--version] [-h|--help] [-V|--verbose] <test> [<test parameters>]</PRE
718 option will display version information for
722 > including the version of the USB
723 slave package that was used to build the executable.</P
738 will display usage information.</P
753 option can be used to obtain more information at run-time, for example
754 some output for every USB transfer. This option can be repeated
755 multiple times to increase the amount of output.</P
759 >The first argument that does not begin with a hyphen specifies a test
760 that should be run, in the form of a Tcl script. For example an
770 > to look for a script with that
774 > suffix if necessarary, and
775 run that script. <SPAN
779 current directory first, then in the install tree for standard test
780 scripts provided by the USB slave package.</P
784 >Some test scripts may want their own parameters, for example a
785 duration in seconds. These can be passed on the command line after
786 the name of the test, for example
789 >usbhost mytest 60</B
802 >Each test is defined by a Tcl script, running inside an interpreter
806 >. In addition to the
807 normal Tcl functionality this interpreter provides a number of
808 variables and functions related to USB testing. For example there is a
811 >bulk_in_endpoints</TT
813 endpoints on the target that can perform bulk IN operations, and a
817 > which contains information
818 such as the minimum and maximum packets sizes. There is a function
822 > which can be used to perform bulk tests
823 on a particular endpoint. A simple test script aimed at specific
824 hardware could ignore the information variables since it would know
825 exactly what USB hardware is available on the target, whereas a
826 general-purpose script would use the information to adapt to the
827 hardware capabilities.</P
829 >To avoid namespace pollution all USB-related Tcl variables and
830 functions live in the <TT
834 Therefore accessing requires either explicitly including the
835 namespace any references, for example
838 >$usbtest::bulk_in_endpoints</TT
842 >namespace import</TT
845 >A very simple test script might look like this:</P
853 CLASS="PROGRAMLISTING"
854 >usbtest::bulktest 1 out 4000
855 usbtest::bulktest 2 in 4000
856 if { [usbtest::start 60] } {
857 puts "Test successful"
860 foreach result $usbtest::results {
868 >This would perform a test run involving 4000 bulk transfers from the
869 host to the target's endpoint 1, and concurrently 4000 bulk transfers
870 from endpoint 2. Default settings for packet sizes, contents, and
871 delays would be used. The actual test would not start running until
875 > is invoked, and it is expected that the
876 test would complete within 60 seconds. If any failures occur then they
885 >Available Hardware</H2
887 >Each target-side USB device driver provides information about the
888 actual capabilities of the hardware, for example which endpoints are
889 available. Strictly speaking it provides information about what is
890 actually supported by the device driver, which may be a subset of what
891 the hardware is capable of. For example, the hardware may support
892 isochronous transfers on a particular endpoint but if there is no
893 software support for this in the driver then this endpoint will not be
901 > program running on the target
902 platform, it obtains this information and makes it available to test
903 scripts via Tcl variables:</P
912 >bulk_in_endpoints</TT
916 > This is a simple list of the endpoints which can support bulk IN
917 transfers. For example if the target-side hardware supports
918 these transfers on endpoints 3 and 5 then the value would be
922 > Typical test scripts would
923 iterate over the list using something like:
932 CLASS="PROGRAMLISTING"
933 > if { 0 != [llength $usbtest::bulk_in_endpoints] } {
934 puts"Bulk IN endpoints: $usbtest::bulk_in_endpoints"
935 foreach endpoint $usbtest:bulk_in_endpoints {
951 > This array holds additional information about each bulk IN endpoint.
952 The array is indexed by two fields, the endpoint number and one of
980 > This field specifies a lower bound on the size of bulk transfers,
981 and will typically will have a value of 1.
990 > The typical minimum transfer size of a single byte is not strictly
991 speaking correct, since under some circumstances it can make sense
992 to have a transfer size of zero bytes. However current target-side
993 device drivers interpret a request to transfer zero bytes as a way
994 for higher-level code to determine whether or not an endpoint is
995 stalled, so it is not actually possible to perform zero-byte
996 transfers. This issue will be addressed at some future point.
1008 > This field specifies an upper bound on the size of bulk transfers.
1009 Some target-side drivers may be limited to transfers of say
1010 0x0FFFF bytes because of hardware limitations. In practice the
1011 transfer size is likely to be limited primarily to limit memory
1012 consumption of the test code on the target hardware, and to ensure
1013 that tests complete reasonably quickly. At the time of writing
1014 transfers are limited to 4K.
1024 > On some hardware it may be necessary for the target-side device
1025 driver to send more data than is actually intended. For example
1026 the SA11x0 USB hardware cannot perform bulk transfers that are
1027 an exact multiple of 64 bytes, instead it must pad such
1028 transfers with an extra byte and the host must be ready to
1029 accept and discard this byte. The
1033 > field indicates the amount of
1034 padding that is required. The low-level code inside
1038 > will use this field
1039 automatically, and there is no need for test scripts to adjust
1040 packet sizes for padding. The field is provided for
1041 informational purposes only.
1051 > This is a string indicating whether or not the
1052 target-side USB device driver supports access to this endpoint
1053 via entries in the device table, in other words through
1054 conventional calls like <TT
1061 >. Some device drivers may only
1062 support low-level USB access because typically that is what gets
1063 used by USB class-specific packages such as USB-ethernet.
1064 An empty string indicates that no devtab entry is available,
1065 otherwise it will be something like
1068 >"/dev/usbs2w"</TT
1075 > Typical test scripts would access this data using something like:
1084 CLASS="PROGRAMLISTING"
1085 > foreach endpoint $usbtest:bulk_in_endpoints {
1086 puts "Endpoint $endpoint: "
1087 puts " minimum transfer size $usbtest::bulk_in($endpoint,min_size)"
1088 puts " maximum transfer size $usbtest::bulk_in($endpoint,max_size)"
1089 if { 0 == $usbtest::bulk_in($endpoint,max_in_padding) } {
1090 puts " no IN padding required"
1092 puts " $usbtest::bulk_in($endpoint,max_in_padding) bytes of IN padding required"
1094 if { "" == $usbtest::bulk_in($endpoint,devtab) } {
1095 puts " no devtab entry provided"
1097 puts " corresponding devtab entry is $usbtest::bulk_in($endpoint,devtab)"
1108 >bulk_out_endpoint</TT
1112 > This is a simple list of the endpoints which can support bulk OUT
1113 transfers. It is analogous to
1116 >bulk_in_endpoints</TT
1127 > This array holds additional information about each bulk OUT
1128 endpoint. It can be accessed in the same way as
1132 >, except that there is no
1136 > field because that field only
1137 makes sense for IN transfers.
1147 > This array holds information about the control endpoint. It contains
1155 >. Note that there is no variable
1158 >control_endpoints</TT
1159 > because a USB target always
1160 supports a single control endpoint <TT
1167 > array does not use an endpoint number
1168 as the first index because that would be redundant.
1174 >isochronous_in_endpoints</TT
1178 >isochronous_in()</TT
1182 > These variables provide the same information as
1185 >bulk_in_endpoints</TT
1190 but for endpoints that support isochronous IN transfers.
1196 >isochronous_out_endpoints</TT
1200 >isochronous_out()</TT
1204 > These variables provide the same information as
1207 >bulk_out_endpoints</TT
1212 but for endpoints that support isochronous OUT transfers.
1218 >interrupt_in_endpoints</TT
1226 > These variables provide the same information as
1229 >bulk_in_endpoints</TT
1234 but for endpoints that support interrupt IN transfers.
1240 >interrupt_out_endpoints</TT
1244 >interrupt_out()</TT
1248 > These variables provide the same information as
1251 >bulk_out_endpoints</TT
1256 but for endpoints that support interrupt OUT transfers.
1268 >Testing Bulk Transfers</H2
1270 >The main function for initiating a bulk test is
1273 >usbtest::bulktest</TT
1274 >. This takes three compulsory
1275 arguments, and can be given a number of additional arguments to
1276 control the exact behaviour. The compulsory arguments are:</P
1280 CLASS="VARIABLELIST"
1286 > This specifies the endpoint to use. It should correspond to
1287 one of the entries in
1290 >usbtest::bulk_in_endpoints</TT
1294 >usbtest::bulk_out_endpoints</TT
1303 > This should be either <TT
1313 >number of transfers</DT
1316 > This specifies the number of transfers that should take place. The
1317 testing software does not currently support the concept of performing
1318 transfers for a given period of time because synchronising this on
1319 both the host and a wide range of targets is difficult. However it
1320 is relatively easy to work out the approximate time a number of bulk
1321 transfers should take place, based on a typical bandwidth of
1322 1MB/second and assuming say a 1ms overhead per transfer.
1323 Alternatively a test script could perform a small initial run to
1324 determine what performance can actually be expected from a given
1325 target, and then use this information to run a much longer test.
1331 >Additional arguments can be used to control the exact transfer. For
1337 > argument can be used to
1338 slowly increase the delay between transfers. All such arguments involve
1339 a value which can be passed either as part of the argument itself,
1343 >, or as a subsequent
1347 >. The possible arguments fall
1348 into a number of categories: data, I/O mechanism, transmit size,
1349 receive size, transmit delay, and receive delay.</P
1358 >An obvious parameter to control is the actual data that gets sent.
1359 This can be controlled by the argument <TT
1365 which can take one of five values: <TT
1390 CLASS="VARIABLELIST"
1399 > The transmit code will not attempt to fill the buffer in any way,
1400 and the receive code will not check it. The actual data that gets
1401 transferred will be whatever happened to be in the buffer before
1402 the transfer started.
1412 > The entire buffer will be filled with a single byte, as per
1426 > The buffer will be treated as an array of 32-bit integers, and will
1427 be filled with the same integer repeated the appropriate number of
1428 times. If the buffer size is not a multiple of four bytes then
1429 the last few bytes will be set to 0.
1439 > The buffer will be filled with a sequence of bytes, generated by
1440 a linear congruential generator. If the first byte in the buffer is
1441 filled with the value <TT
1444 >, the next byte will be
1448 >. For example a sequence of slowly
1449 incrementing bytes can be achieved by setting both the multiplier
1450 and the increment to 1. Alternatively a pseudo-random number
1451 sequence can be achieved using values 1103515245 and 12345, as
1452 per the standard C library <TT
1456 For convenience these two constants are available as Tcl
1459 >usbtest::MULTIPLIER</TT
1463 >usbtest::INCREMENT</TT
1474 > This acts like <TT
1477 >, except that the buffer is
1478 treated as an array of 32-bit integers rather than as an array of
1479 bytes. If the buffer is not a multiple of four bytes then the last
1480 few bytes will be filled with zeroes.
1486 >The above requires three additional parameters
1509 the value to be used for byte or word fills, or the first number when
1510 calculating a sequence. The default value is <TT
1525 the multiplier and increment for a sequence, and have default values
1533 example, to perform a bulk transfer of a pseudo-random sequence of
1534 integers starting with 42 the following code could be used:</P
1542 CLASS="PROGRAMLISTING"
1543 >bulktest 2 IN 1000 format=wordseq data1=42 \
1544 data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT</PRE
1549 >The above parameters define what data gets transferred for the first
1550 transfer, but a test can involve multiple transfers. The data format
1551 will be the same for all transfers, but it is possible to adjust the
1552 current value, the multiplier, and the increment between each
1553 transfer. This is achieved with parameters <TT
1586 >, with default values of 1 for each
1587 multiplier and 0 for each increment. For example, if the multiplier
1588 for the first transfer is set to <TT
1605 supplied, then the multiplier for subsequent transfers will be
1624 >Currently it is not possible for a test script to send specific data,
1625 for example a specific sequence of bytes captured by a protocol analyser
1626 that caused a problem. If the transfer was from host to target then
1627 the target would have to know the exact sequence of bytes to expect,
1628 which means transferring data over the USB bus when that data is known
1629 to have caused problems in the past. Similarly for target to host
1630 transfers the target would have to know what bytes to send. A possible
1631 future extension of the USB testing support would allow for bounce
1632 operations, where a given message is first sent to the target and then
1633 sent back to the host, with only the host checking that the data was
1634 returned correctly.</P
1646 >On the target side USB transfers can happen using either low-level
1647 USB calls such as <TT
1649 >usbs_start_rx_buffer</TT
1651 higher-level calls which go through the device table. By default the
1652 target-side code will use the low-level calls. If it is desired to
1653 test the higher-level calls instead, for example because those are
1654 what the application uses, then that can be achieved with an
1658 >mechanism=devtab</I
1670 >The next set of arguments can be used to control the size of the
1671 transmitted buffer: <TT
1711 > determines the size of the first
1712 transfer, and has a default value of 32 bytes. The size of the next
1713 transfer is calculated by first multiplying by the
1719 > value, then dividing by the
1725 > value, and finally adding the
1731 > value. The defaults for these are
1742 respectively, which means that the transfer size will remain
1743 unchanged. If for example the transfer size should increase by
1744 approximately 50 per cent each time then suitable values might be
1768 > arguments can be used to impose
1769 lower and upper bounds on the transfer. By default the
1777 appropriate for the endpoint will be used. If at any time the
1778 current size falls outside the bounds then it will be normalized.</P
1788 >The receive size, in other words the number of bytes that either host
1789 or target will expect to receive as opposed to the number of bytes
1790 that actually get sent, can be adjusted using a similar set of
1825 >. The current receive size will be
1826 adjusted between transfers just like the transmit size. However when
1827 communicating over USB it is not a good idea to attempt to receive
1828 less data than will actually be sent: typically neither the hardware
1829 nor the software will be able to do anything useful with the excess,
1830 so there will be problems. Therefore if at any time the calculated
1831 receive size is less than the transmit size, the actual receive will
1832 be for the exact number of bytes that will get transmitted. However
1833 this will not affect the calculations for the next receive size.</P
1835 >The default values for <TT
1871 respectively. This means that the calculated receive size will always
1872 be less than the transmit size, so the receive operation will be for
1873 the exact number of bytes transmitted. For some USB protocols this
1874 would not accurately reflect the traffic that will happen. For example
1875 with USB-ethernet transfer sizes will vary between 16 and 1516 bytes,
1876 so the receiver will always expect up to 1516 bytes. This can be
1879 >rxsize1 1516</TT
1881 other parameters at their default values.</P
1883 >For target hardware which involves non-zero
1887 >, on the host side the padding will
1888 be added automatically to the receive size if necessary.</P
1896 >Transmit and Receive Delays</H3
1898 >Typically during the testing there will be some minor delays between
1899 transfers on both host and target. Some of these delays will be caused
1900 by timeslicing, for example another process running on the host, or a
1901 concurrent test thread running inside the target. Other delays will be
1902 caused by the USB bus itself, for example activity from another device
1903 on the bus. However it is desirable that test cases be allowed to
1904 inject additional and somewhat more controlled delays into the system,
1905 for example to make sure that the target behaves correctly even if the
1906 target is not yet ready to receive data from the host.</P
1908 >The transmit delay is controlled by six parameters:
1942 >. The default values for these are
1963 > respectively, so that by default
1964 transmits will happen as quickly as possible. Delays are measured in
1965 nanoseconds, so a value of <TT
1969 to a delay of 0.001 seconds or one millisecond. By default delays have
1970 an upper bound of one second. Between transfers the transmit delay is
1971 updated in much the same was as the transfer sizes.</P
1973 >The receive delay is controlled by a similar set of six parameters:
2007 >. The default values for these are
2008 the same as for transmit delays.</P
2010 >The transmit delay is used on the side which sends data over the USB
2011 bus, so for a bulk IN transfer it is the target that sends data and
2012 hence sleeps for the specified transmit delay, while the host receives
2013 data sleeps for the receive delay. For an OUT transfer the positions
2016 >It should be noted that although the delays are measured in
2017 nanoseconds, the actual delays will be much less precise and are
2018 likely to be of the order of milliseconds. The exact details will
2019 depend on the kernel clock speed.</P
2028 >Other Types of Transfer</H2
2030 >Support for testing other types of USB traffic such as isochronous
2031 transfers is not yet implemented.</P
2039 >Starting a Test and Collecting Results</H2
2041 >A USB test script should prepare one or more transfers using
2042 appropriate functions such as <TT
2044 >usbtest::bulktest</TT
2046 Once all the individual tests have been prepared they can be started
2050 >. This takes a single
2051 argument, a maximum duration measured in seconds. If all transfers
2052 have not been completed in the specified time then any remaining
2053 transfers will be aborted.</P
2062 if all the tests have succeeded, or <TT
2066 them have failed. More detailed reports will be stored in the
2069 >usbtests::results</TT
2071 list of string messages.</P
2079 >Existing Test Scripts</H2
2081 >A number of test scripts are provided as standard. These are located
2085 > subdirectory of the
2086 common USB slave package, and will be installed as part of the process
2087 of building the host-side software. When a script is specified on the
2091 > will first search for
2092 it in the current directory, then in the install tree. Standard
2093 test scripts include the following:</P
2097 CLASS="VARIABLELIST"
2106 > This script simply displays information about the capabilities
2107 of the target platform, as provided by the target-side USB
2108 device driver. It can help with tracking down problems, but its
2109 primary purpose is to let users check that everything is working
2110 correctly: if running <B
2112 >usbhost list.tcl</B
2114 outputs sensible information then the user knows that the
2115 target side is running correctly and that communication between
2116 host and target is possible.
2126 > The target-side code can provide information about what
2127 is happening while tests are prepared and run. This facility
2128 should not normally be used since the extra I/O involved will
2129 significantly affect the behaviour of the system, but in some
2130 circumstances it may prove useful. Since an eCos application
2131 cannot easily be given command-line arguments the target-side
2132 verbosity level cannot be controlled using
2144 options. Instead it can be controlled from inside
2148 > by changing the integer
2152 >. Alternatively it can
2153 be manipulated by running the test script
2157 >. This script takes a single
2158 argument, the desired verbosity level, which should be a small
2159 integer. For example, to disable target-side run-time logging
2162 >usbhost verbose 0</B
2176 >Possible Problems</H2
2178 >If all transfers succeed within the specified time then both host and
2179 target remain in synch and further tests can be run without problem.
2180 However, if at any time a failure occurs then things get more
2181 complicated. For example, if the current test involves a series of
2182 bulk OUT transfers and the target detects that for one of these
2183 transfers it received less data than was expected then the test has
2184 failed, and the target will stop accepting data on this endpoint.
2185 However the host-side software may not have detected anything wrong
2186 and is now blocked trying to send the next lot of data.</P
2188 >The test code goes to considerable effort to recover from problems
2189 such as these. On the host-side separate threads are used for
2190 concurrent transfers, and on the target-side appropriate asynchronous
2191 I/O mechanisms are used. In addition there is a control thread on the
2192 host that checks the state of all the main host-side threads, and the
2193 state of the target using private control messages. If it discovers
2194 that one side has stopped sending or receiving data because of an
2195 error and the other side is blocked as a result, it will set certain
2196 flags and then cause one additional transfer to take place. That
2197 additional transfer will have the effect of unblocking the other side,
2198 which then discovers that an error has occurred by checking the
2199 appropriate flags. In this way both host and target should end up back
2200 in synch, and it is possible to move on to the next set of tests.</P
2202 >However, the above assumes that the testing has not triggered any
2203 serious hardware conditions. If instead the target-side hardware has
2204 been left in some strange state so that, for example, it will no
2205 longer raise an interrupt for traffic on a particular endpoint then
2206 recovery is not currently possible, and the testing software will just
2209 >A possible future enhancement to the testing software would allow the
2210 host-side to raise a USB reset signal whenever a failure occurs, in
2211 the hope that this would clear any remaining problems within the
2212 target-side USB hardware.</P
2229 HREF="usbs-writing.html"
2237 HREF="io-usb-slave.html"
2251 >Writing a USB Device Driver</TD
projects / karo-tx-redboot.git / blob