USB High Speed EHCI (2.0) Interface Regular Packet Size Test (Compact 7)
3/12/2014
The USB Host-Controller Driver Test verifies the functionality of USB host-controller drivers. It can also be used to determine whether a given USB host-controller, either stand-alone or on-board logic, works correctly with Windows Embedded Compact.
The USB Host Test works by acting as a client driver above the USB bus driver, usbd.dll, on the host device. It is loaded when a function loopback device is connected to the host through a USB cable. Once connected, the USB test suite (the test client driver on the host side) can then stream data or issue device requests to and from this data loopback device, exercising the USB host-controller and its corresponding drivers.
Test Prerequisites
Your device must meet the following requirements before you run this test.
The hardware required for the USB Host-Controller Driver test, in addition to the test platform, includes:
The USB Host Controller Driver Test requires two platform devices. One device acts as the USB host under test, while the second acts as a USB function device. The USB function device that has been tested is a CEPC with a NetChip NET2280 USB function PCI card, but can be any platform supporting USB function that has the appropriate drivers supplied.
The following table shows the hardware required for the test.
| Requirement | Description |
|---|---|
USB Host Device Under Test |
Host platform under test containing either a host controller card or an on-board host controller. |
USB Function Device |
This test has been verified using a CEPC with a NetChip NET2280 USB function card. However, you can use another platform (or another instance of the same platform) as the USB function device, if the required USB function drivers are available. |
USB cable |
Required for setting up the test. |
The following table shows the software that is required on the HOST device for the USB Host-Controller Driver test.
| Requirements | Description |
|---|---|
Tux.exe |
Tux test harness, required for test execution. |
Kato.dll |
Kato logging engine, required for logging the test data. |
ktux.dll |
Kernel mode test harness module. |
Usbtest.dll |
Test module containing tests. |
Usbd.dll |
USB component; must be included in the runtime image. |
EHCI/OHCI/UHCI host-controller driver(s) |
USB component; must be included in the runtime image. |
The following table shows the software that is required on the FUNCTION device for the USB Host-Controller Driver test. A CEPC with NetChip NET2280 card is assumed.
| Requirements | Description |
|---|---|
Lufldrv.exe |
Loads the required loopback configuration driver. Must be included in the runtime image, or be available in a release directory to be automatically downloaded to the device. |
LpBkCfg1.dll |
Configures a USB function controller with six endpoints in addition to endpoint zero. |
LpBkCfg2.dll |
Configures a USB function controller with four endpoints in addition to endpoint zero. |
Net2280.dll |
Netchip NET2280 USB 2.0 function bus driver. |
The lufldrv.exe executable as well as the loopback configuration files can be found at the following default installation path: C:\Program Files\Windows Embedded Compact Test Kit\tests\target\<CPU>\.
Subtests
The table below lists the subtests included in this test.
| SubTest ID | Description |
|---|---|
1001-1314 1501-1504 1601-1612 |
Data loopback tests. There are a total of 42 tests of this kind. Test case IDs are of the form 1DST, where D refers to the method of data transfer, S refers to whether the transfer method is synchronous or asynchronous, and T refers to the type of transfer. There are six categories of tests for how the data is being transferred, denoted by the first two digits of the test ID, as follows: * Normal loopback tests (test ID starts with 10) * Loopback tests that use physical memory (test ID starts with 11) * Loopback tests that use a part of allocated physical memory (test ID starts with 12) * Normal short packet transfer loopback tests (test ID starts with 13) * Stress short packet transfer loopback tests (test ID starts with 15) * Zero-length transfer loopback tests (test ID starts with 16) Both synchronous and asynchronous transfer methods are used. Tests that use a synchronous transfer method have a 0 for the third digit (xx0x), while tests that use an asynchronous transfer method have a 1 for the third digit (xx1x). There are five categories of transfer-type tests, denoted by the final digit of the test ID, as follows: * Bulk pipe loopback tests (test ID ends with 1) * Interrupt pipe loopback tests (test ID ends with 2) * Isochronous pipe loopback tests (test ID ends with 3) * All pipes transfer concurrently (test ID ends with 4) * All three types of transfer occur concurrently (test ID ends with 5). Note: This final category is designed for testing some other USB function devices with more endpoints than the host-controller driver can handle. Testers that use Netchip NET2280 on the USB function device can ignore this category. |
1401-1442 |
Additional data loopback tests. These tests mainly focus on certain API functions like GetTransferStatus, AbortTransfer, and CloseTransfer. |
2001-2013 |
Chapter 9 tests |
3001-3012 |
Dynamic Packet Size Changing By default, the data loopback device configures the endpoints with some often used, DWORD-aligned packet sizes. Having all the previously listed tests passes under this configuration is sufficient for build verification. Testers can also change the packet sizes for each endpoint, if they want; the values are hard-coded in the source code for lpbkcfg1.dll, lpbkcfg2.dll, etc. Packet size is configurable by the jobs in the 3000 test case series. These jobs are not tests in themselves, but are executed to configure the device for a particular packet size before the related test is run. If you run one of the test cases in the 3000 series, the packet size set by the job in the given test case remains in effect until another test in the series is run, or the device is restarted. Note: Some jobs are only valid for a device configured for full-speed mode, while other test cases apply only to a device configured for high-speed. * 3001: Uses very small packet sizes in full-speed configuration. * 3002: Uses very small packet sizes in high-speed configuration. * 3003: Uses irregular packet sizes (for example, a non-DWORD-aligned size) in full-speed configuration. * 3004: Uses irregular packet sizes (for example, a non-DWORD-aligned size) in high-speed configuration. * 3005: High-speed only; uses very large packet sizes (for example, 2*1024 for isochronous endpoints) in full-speed configuration. (Note: In real-world applications, NET2280 function card cannot handle such large packet sizes because its on-board FIFO buffer is too small.) |
4001-4014 |
Additional USB API tests |
9001 9003-9004 9991 |
USB Driver device reset/suspend/resume test These test certain API functions like SuspendDevice, ResumeDevice, and DisableDevice. For test case 9991, the last test case in the suite, a physical detach is required before continuing any testing. Note: Connection between host and function might be lost after suspend/reset tests. In this case, reload the loopback driver on the client side. |
9005-9007 |
Stress test for testing EP0 transfer. |
Setting Up the Test
See "Running the Test" for setup instructions.
Running the Test
Setting up the USB Host-Controller Driver Test requires downloading images to both the function and host devices, executing command lines on each, and when prompted, connecting the host to the function with a USB cable. Do not connect the USB cable until prompted by the test.
1. Download run-time images to both host and function devices. Two instances of Platform Builder will be required to do this, however both instances of Platform Builder can be hosted on the same PC. Do not connect the devices to each other with a USB cable at this time.
2. Using the "gi mod" command, verify that the desired host controller driver(s) (ex. ehci.dll/ohci2.dll/uhci.dll) is loaded on the host device and that "net2280.dll" is loaded on the function device (again, assuming a CEPC with a NET2280 card is used as the function loopback).
3. On the loopback device, start the loopback driver (ex. s lufldrv.exe) with options to suit your testing purposes. See table below for common test scenarios.
4. On the loopback device, use "gi mod" to verify that "LpBkCfg1.dll" (or the desired loopback configuration module) is loaded.
5. On the host device, if desired, run the appropriate 3000-series job to set the packet size to be used for the test (ex. s tux -o -n -d usbtest -x3001). See the table below for common test scenarios.
6. On the host device, execute the test using the following command: s tux -o -n -d usbtest -x1-2999,4000-9999.
7. When prompted by the host device, connect the host and function devices with a USB cable.
The same basic procedure is used for a variety of different configurations (high-speed/full-speed/composite, etc). The following table shows which commands to execute for the most common test scenarios.
| FUNCTION-SIDE COMMANDS | HOST-SIDE COMMANDS | |||
|---|---|---|---|---|
|
Regular Packet Size |
Small Packet Size |
Non-Regular Packet Size |
|
High Speed [EHCI(2.0)] |
s lufldrv.exe |
s tux -o -n -d usbtest -x1-2999,4000-9999 |
s tux -o -n -d usbtest -x3002,1-2999,4000-9999 |
s tux -o -n -d usbtest -x3004,1-2999,4000-9999 |
High Speed [EHCI(2.0)], composite config |
s lufldrv.exe -c |
s tux -o -n -d usbtest -x1-2999,4000-9999 |
s tux -o -n -d usbtest -x3002,1-2999,4000-9999 |
s tux -o -n -d usbtest -x3004,1-2999,4000-9999 |
Full Speed [OHCI(1.1)/UHCI(1.0)] |
s lufldrv.exe -f |
s tux -o -n -d usbtest -x1-2999,4000-9999 |
s tux -o -n -d usbtest -x3001,1-2999,4000-9999 |
s tux -o -n -d usbtest -x3003,1-2999,4000-9999 |
Full Speed [OHCI(1.1)/UHCI(1.0)], composite config |
s lufldrv.exe -f -c |
s tux -o -n -d usbtest -x1-2999,4000-9999 |
s tux -o -n -d usbtest -x3001,1-2999,4000-9999 |
s tux -o -n -d usbtest -x3003,1-2999,4000-9999 |
Note: To enable testing against a composite function, ensure that the USB function device image is built with the following SYSGEN set: SYSGEN_USBFN_COMPOSITE=1.
On the FUNCTION device, the command line parameters to lufldrv.exe allow you to configure the loopback driver. Sample usage: "s lufldrv.exe -2 -f "
| Command-line parameter | Description |
|---|---|
-1 |
Specifies that lufldrv.exe loads the Loop-back Configuration #1 driver, LpBkCfg1.dll. This configuration specifies a USB function controller with six endpoints in addition to endpoint zero. A pair each of bulk (IN/OUT), interrupt (IN/OUT) and isochronous (IN/OUT) endpoints. When no configuration number is specified, this is loaded by default. |
-2 |
Specifies that lufldrv.exe loads the Loop-back Configuration #2 driver, LpBkCfg2.dll. This configuration specifies a USB function controller with four endpoints in addition to endpoint zero. A pair each of bulk (IN/OUT) and interrupt (IN/OUT) endpoints. |
-3 |
Specifies that lufldrv.exe loads the custom loop-back driver you created: LpBkCfgNew.dll. See below about creating a custom loop-back configuration driver. |
-f |
Causes the device to operate at full-speed instead of the default high-speed. |
-c |
Composite device functionality. |
To create a custom loopback driver configuration, modify the existing test code for the USB function client-data loop-back driver that you load on the function side. To modify the test source code:
1. Open the setconfig.cpp file in the …\USBFN\Drivers\LpBkNewCfg folder.
2. Search for all lines of code marked with the //<--USER INPUT comment, and change the configuration, interface, and endpoint settings, or endpoint settings to meet the compatibility requirements for the USB function controller that you are using. Example:
------------------------8<-----------------------------
// --- set endpoints for highspeed config 0, interface 0 ---
//---endpoint 1---
PUSB_ENDPOINT_DESCRIPTOR pCurEP = &pCurIf->pEPs[0].usbEP;
pCurEP->bEndpointAddress = 0x81; //<--USER INPUT
pCurEP->bmAttributes = USB_ENDPOINT_TYPE_BULK;//<--USER INPUT
pCurEP->wMaxPacketSize = 0x200;//<--USER INPUT
pCurEP->bInterval = 0x0;//<--USER INPUT
//will it work with another endpoint to be a loopback pair?
pCurIf->pEPs[0].iPairAddr = 1; //<-- USER INPUT
------------------------>8-----------------------------
3. After you make the necessary modifications, build the source code in this directory. A USB function client-data loopback driver is created by using the name LpBkNewCfg.dll.
4. To load the newly configured client-data loopback driver, at the Windows Embedded Compact Command Prompt within Platform Builder, type "s lufldrv -3".
Note:
* Even if your host controller supports only USB 1.1, you still must set up configuration, interface, and endpoint data for a high-speed device. In this case, you can use the same configuration settings that you specify for a full-speed device.
* Pair the endpoints so that each pair contains an endpoint of the same type.
* Neither multiple configurations, nor multiple interfaces are supported on the function side. However, the data structure does support these two features.
For further USB Host test coverage, consider adding the following scenarios to your testing matrix:
* Execute the host tests through a USB hub.
* Execute the host tests using a full-speed reflector (s lufldrv -f) against a high-speed host. If full-speed and high-speed host controller drivers reside on the same device, executing the test against a full-speed reflector will cause a handoff from the high-speed to full-speed host controller driver. If no full-speed driver is available, the test will need to take place through a hub. This latter scenario is the so-called "golden bridge" test, and is the only scenario in which a USB 2.0 host-controller performs split transfers.
* Attach several USB devices to the system. Then suspend and resume the system. The expected result is that the USB devices remain connected, are recognized by the system, and are functional.
* Attach a USB device, suspend the system, replace the USB device with another in the same port, and then resume. Check that the system correctly enumerates the new device.
* Suspend the (host-side) system during the transfer stage of a data transfer test, and then resume. Check that the system does not crash (though the transfer test will fail).
* Disconnect the USB connection during the transfer stage of a data transfer test. Check that the system does not crash (though the transfer test will fail).
Verifying the Test
When the test completes running, verify that "PASSED" appears in the test log for all subtests.
Troubleshooting the Test
* On the USB function device, using the debug output, ensure the loopback driver was properly loaded on the loopback function device.
* On the USB host device, observe the debug output for failures. If source code is available, attempt to pinpoint the source of the error.
For additional platform specific issues, consult the CTK articles on the TechNet wiki.