Symbian platform provides test code that you can run to validate a USB client port. This topic describes the USB client test code.
For testing the port, you will need:
A Symbian platform text shell ROM image for the device that also contains the USB drivers (the LDD and the PDD), and the unit test applications T_USB and T_USBAPI. On a slow CPU you may need to use release (UREL) versions of the driver binaries to avoid exceeding the time-out limits of the USB protocol.
A PC running either MS Windows [98SE|ME|2000|XP] to run the Symbian host-side test program USBRFLCT, or MS Windows 2000 to run, in addition, the USB Command Verifier (USBCV) R1.2.1 compliance test program. On MS Windows XP you will also be able to run the USBCV R1.3 compliance test program.
A USB driver disk (or some other location accessible to the PC) containing the .inf file that matches the device to be tested, and the driver binary file that will be installed for the device. Note that for USBRFLCT, both items are included in the binary program distribution.
In addition, a USB analyser, like the ones made by LeCroy formerly CATC, is invaluable for this kind of work. Without this equipment it may be impossible to be sure that the port has been fully successful.
These are the recommended steps for testing the port:
Run T_USBAPI on the unconnected USB device and get it to pass.
Use a USB cable to connect the device under test to a PC and start T_USB on the device (use T_USB menu options '0','1','1' and '1'). See if the device successfully delivers all the information (descriptors) that the host asks for. If so, a dialogue box pops up on the PC, saying “New hardware found” and offering certain options. Point the OS to the location of the .inf files and the driver files (the USB driver disk) and have it pick and install the correct driver. Afterwards you should see the new USB device in the Windows Device Manager under the category Symbian platform controlled USB devices as USBRFLCT - Device. If things don’t work as expected at this early stage, the USB analyser will prove invaluable.
Try and run USBRFLCT and T_USB together. First start T_USB on the device, choose the four numbered program options (but this time the first menu option must not be '0'), and then start USBRFLCT on the PC. The program pair should run indefinitely, in any mode. If the program halts after a while then this almost certainly indicates either a hardware problem associated with the USB device controller or an incorrect handling of the controller in the PSL. If the halt occurs after a long time, then this could point to a resource problem, such as a memory leak. This test will verify that at least one bulk IN endpoint and one bulk OUT endpoint are working correctly, and that data can be transferred over the USB link.
Run the USB Implementers Forum's USBCV compliance test suite and go through the “Chapter 9 Tests”. You will first need to start T_USB on the device end, as USBCV needs a successfully enumerated device as a target (choose '0' as the first T_USB option). These tests should all pass. It is important to run USBCV to verify that endpoint-0 is behaving correctly, and that the device is compliant with the USB Specification 2.0.
The host (PC) side test program: USBRFLCT uses the services of a USB client driver, USBIO.SYS. This driver is loaded by the OS as part of the enumeration once the USB device on test is connected to the PC.
The generic USB device driver USBIO is a product developed and marketed by the German company Thesycon [USBIO Software Development Kit for Windows; see http://www.thesycon.de/usbio/eng/usbio.htm].
The driver provides Win32 applications with direct access to USB devices which are otherwise only accessible from kernel-mode. It can be used with any kind of USB device, enabling application developers to control devices without having to develop a kernel-mode WDM driver. Symbian owns a licence to the driver and its development package, and is entitled to ship renamed copies of the driver binary to licensees and partners as part of its own development kits, usually adopting the name of the application that uses it.
This is a device-side only, stand-alone test program. It is used to verify the proper working of some basic USB API functionality. For T_USBAPI to run, the device doesn’t need to be USB-connected to a PC although if it is then some additional tests are performed. Tests run by T_USBAPI include:
loading the USB LDD and opening a channel
searching for suitable endpoints and setting up an interface
searching for suitable endpoints and creating an 'alternate setting' for that interface (if supported).
querying and allocating endpoint resources (DMA and double buffering)
powering up the UDC and connecting it to the bus.
manipulating (modifying) USB descriptors (Device, Device_Qualifier, Configuration, Other_Speed_Configuration, Interface, Endpoint, String)
testing the USB OTG API extensions
requesting and releasing Device Control
some static state notification tests (alternate device status, endpoint status).
setting and clearing endpoint Halt condition (where supported in unconfigured state)
closing the channel and freeing the LDD
Most of these tests verify the functioning of the platform-independent code (i.e. platform-independent layer + LDD). However, some of this code relies on platform-specific layer functionality, such as the stall state and the maximum packet size of endpoints. Therefore, a working, or a partially working platform-specific layer is required for T_USBAPI to pass.
When called normally, T_USBAPI runs once and then exits. It can also run endlessly in a loop, provided it is not failing, by adding the parameter soak to the command line. Once the program is running in endless mode, it can be stopped at any time by pressing the Esc key, in which case the program finishes the current set of tests and then exits. This loop mode can be useful for the detection of memory leaks in the USB stack, although the main functionality exercised lies in the platform-independent layer and the LDD, not in the platform-specific layer.
T_USBAPI is a standalone program which can be safely run on a UDEB image. Choose to display error messages and warnings specific to the USB components using the appropriate kernel debug flags (KPANIC, KUSBPSL and KUSB). The following example shows the E32 shell commands to set KPANIC, KUSBPSL and KUSB in that order:
C:\>trace 80000000
C:\>trace 3 1
"trace 3 1" means "set (bit 1|bit 0) at index 1" (KUSBPSL=33, KUSB=32)
These are the host and device side parts, respectively, of a reflector-like USB test program. They are normally used together, but T_USB can also be used to create a simple USB device to allow USBCV to execute.
To ensure proper internetworking, USBRFLCT and T_USB exchange their version numbers after startup, and either program will quit if the other does not provide a suitable minimum version number.
This is the host-side part of a reflector-like USB test program. This is normally used together with T_USB, the device-side part.
The directory ...\e32test\win32\usbrflct\ contains its source code.
The directory ...\e32test\win32\usbrflct_distribution\ contains a binary distribution of the program, including the USBRFLCT.SYS driver and a USBRFLCT.INF file for the installation of the driver.
The syntax for invoking this is:
usbrflct [options]
where options can be one of the following:
/[r|t] |
receive|transmit only; default is to loop with statistics printed every 1024th iteration |
/l |
loop mode with statistics printed for every iteration |
/v |
verbose driver & program output |
/[h|?] |
displays this help text |
Three modes of operation are available:
Loop mode.
Data chunks are read from the USB device and then immediately written back to it. Successive data chunks are read, each being one byte larger than the one before, starting with size 0 until a specified maximum size has been reached. This maximum size value is specified on the device using T_USB. After the maximum size has been reached, the size of the data chunk is reset back to its starting value.
A preamble packet is sent by the device before each data chunk, containing the size of the chunk that is to follow. This kind of protocol is necessary, because the host side driver has to specify the exact number of bytes that it needs to read from the device.
Every 1024th loop, the program displays statistics about the test run. For example, the total number of bytes transferred, and the current average data throughput in bytes/sec.
Receive-only mode.
In this mode, a single preamble packet containing the size of the data chunks that are to follow is sent from the device. The host-side program subsequently, and continuously, reads data chunks of that size from the device. This mode can be used to determine the raw transfer performance of the USB connection in the device upstream direction.
Transmit-only mode.
In this mode, no preamble packet is sent. Instead, maximum (constant) sized data chunks are sent. This mode can be used to determine the raw transfer performance of the USB connection in the device downstream direction.
Verbose mode.
In this mode, the driver and program output are both displayed. Use this to track down problems that occur when trying to get USBRFLCT and T_USB to work together. This may help in the following circumstances:
The error messages are particularly helpful, a list of error codes together with explanations for the USBRFLCT.SYS driver can be found in the USBIO Reference Manual. These codes are also available on Thesycon's website at http://www.thesycon.de/usbio/usbioman.pdf. Do not use this mode during loop or throughput testing to avoid program slowdown which could affect these tests.
This is the device-side part of a reflector-like USB test program. This is normally used together with USBRFLCT, the host-side part.
The source for this program can be found in:
After starting the program, you are prompted to choose a maximum size for a single transfer.
Note: The maximum transfer size is not the same as the maximum packet size.
The prompt appears as follows:
++++Choose max transfer size++++
'0' - Set up USB device for USBCV
'1' - 32 bytes
'2' - 1024 bytes
'3' - 64 kbytes
'4' - 1 Mbyte
Once you have chosen the maximum transfer size you are prompted to choose a bandwidth priority for the interface that will be created and used for the tests. All options except '0' are used when T_USB is run together with USBRFLCT. The program carries out dynamic version number checking of the two programs to ensure compatibility . Option '0' sets up a static USB device that can be used to perform other tests, including compliance testing with USBCV. This option also circumvents dynamic version checking. Most of the other menu options have no meaning in this mode.
Choose a bandwidth priority from the following menu for the interface specifically created for the tests. All tests will be carried out over this interface.
++++ Choose Bandwidth Priority ++++
'1' - Economical buffering - default
'2' - More memory than default buffering - Plus1
'3' - More memory than Plus1 buffering - Plus2
'4' - Maximum memory for buffering
Choose endpoint options from the following two configuration menus:
++++ Choose Endpoint I/O Transfer Mode ++++
'1' - Interrupt Mode
'2' - DMA Mode (recommended)
++++ Choose Endpoint FIFO Mode ++++
'1' - Normal Buffering Mode
'2' - Double Buffering Mode (recommended)
A message prompts the user to start the host side test program USBRFLCT.
Once host enumeration and USBRFLCT configuration completes, the program's main menu is displayed as follows:
++++ Select Program Option ++++
'L'oop test
Loop test with data 'C'ompare
'R'eceive-only test (we receive, host transmits)
'T'ransmit-only test
Receive and 'P'ut (write) to File
Transmit and 'G'et (read) from File
Signal Remote - 'W'akeup to the host
'S'top current transfer
Re'E'numerate device
'Q'uit
Choose one of the six main test modes. The selected mode should correspond with the mode in which the host-side program is running. For example, device-side Receive matches host-side Transmit.
The Loop test with Compare is just like the normal Loop, except that the received data is compared with the data that was previously sent, allowing any transmission errors to be detected. The purpose of the non-comparing mode is performance (throughput) assessment of the USB link, in this mode the slow down of the application introduced by the byte-by-byte checking of the compare operation is not desirable. Note: The non-comparing mode does do some checking, specifically it compares the received transfer number (4 bytes at the start of each buffer) against the expected value.
The standard 'Receive-only' test mode R immediately discards the data received, similarly the standard 'Transmit-only' mode T creates random data on the fly to send to the device. These tests are useful for checking the maximum throughput of the link, however they do not reflect normal usage. In a real world scenario, transmitted data would be read from a file and received data would be written to a file.
There are two further tests which include file I/O. These are:
In both cases you must first enter a source or destination from the list of available drives.
S stops an ongoing transfer at any time
W issues a Remote Wake-up signal to the host; this is needed, for example, when running USBCV.
E re-enumerates the USB device by first disconnecting it from, and then reconnecting it to the bus.
ESC or Q quits the program after tearing down the device configuration and freeing all used resources.
Thesycon provide this Win32 GUI application. Like USBRFLCT it works on top of the USBRFLCT.SYS driver (otherwise known as USBIOAPP.EXE). The source code for this program is part of the USBIO development kit. You can find the compiled executable USBIOAPP.EXE in the same directory as USBRFLCT and the host side drivers: ...\e32test\win32\usbflct_distribution\.
Use USBIOAPP to exercise and test the low-level functionality of an attached USB device. In this case, the Symbian platform device running the USB device stack which includes the port of the platform-specific layer.
The following steps describe an example test:
Connect the Symbian platform USB device to a PC on which the USBRFLCT driver has been installed.
Start T_USB on the device to create a USB device (use option '0' for the transfer size).
Launch USBIOAPP on the PC.
Press the Scan for USBIO devices button. The device should be detected by USBIOAPP.
Test and exercise the USB device using the different options provided by the USBIOAPP program.
Further details can be found in the USBIO manual, which contains a chapter on the USBIOAPP. See http://www.thesycon.de/usbio/usbioman.pdf
This test program is written and maintained by the USB Implementers Forum, Inc, (also referred to as the “USB Forum” or “USB IF”). It can be used to check compatibility of the USB device with the USB specification (currently version 2.0). It contains a collection of different test suites, but the only tests that are of interest regarding the platform-specific layer port are the “Chapter 9 Tests”. Even though most of the "Chapter 9" request processing is done by the platform-independent layer, the tests can help to uncover potential problems with endpoint-0 controlling platform-specific layer code. The tests will also show whether or not the platform-specific layer and the platform-independent layer work together without problems.
This program runs on Windows 2000 and Windows XP (English Version) only. At the time of writing, the version of the package is R1.2.1, and can be obtained from http://www.usb.org/developers/tools/USBCV121.msi.
This is not a dedicated test program, but it can be used to check that the USB driver stack is operating correctly. Since it is not a test program USBMSAPP is not normally included in ROMs with any of the ...\e32tests\f32tests\alltests rom.bat options. The source can be found ...\e32ustils\usbmsapp\. If you want to include it, use the command line macro below.
Note: Add this macro to \e32\rombuild:
rom --variant=h4hrp --inst=armv5 --build=urel --type=alltests --symbol --define=ROMOPT_USBMSAPP --name=H4HRPARMV5.IMG
Start the program from the command prompt with a drive letter as a parameter:
C:\> usbmsapp d:
This mounts the specified drive with the Mass Storage file system ('MSFS'). Check that you can see it as a Read/Write disk drive on the USB host computer. The drive name on the host computer will be the first free drive letter available.
Note: You can only mount drives marked as 'removable' as USB Mass Storage devices. The C: drive cannot be marked as 'removable'. Internal drives made available for USB Mass Storage must be marked as 'removable' for reasons of platform security.