Validation

Requirements

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 computer running +either MS Windows 98 or above 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.

Test +steps

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 +USBIO driver

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.

T_USBAPI

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)

USBRFLCT +and T_USB

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.

Since this program suite is subject to continual development + and improvement, in order for them to work properly together, +both parts must always come from the same Symbian platform +delivery.

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.

USBRFLCT

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

+ + +

loop mode with statistics printed for every iteration

+ + +

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 first time +you test a port of the platform specific layer
- after installation +changes on the PC
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.

T_USB

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:

...\e32test\device\t_usb.h
...\e32test\device\t_usb.cpp
...\e32test\device\t_usbco2.cpp

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:

'Receive' mode P, where data received from the link is written to a +newly created file.

'Transmit' mode G, where data is read from a newly created file and sent +across the link.

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.

USBIOAPP

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

USB +Command Verifier (USBCV)

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.

USBMSAPP +(USB Mass Storage Application)

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.