Quality/TestSuite/USB Driver Test Specification

Latest revision as of 11:34, 25 March 2011

Introduction

blts-usb package (0.0.14) is test driver using USB host and peripheral devices.

USB peripheral test cases are made between host (e.g. PC) and peripheral gadget (e.g. N900). Both ends have their own drivers which communicate and transfer data between different endpoints.

Test Coverage

Each test case must be run independently and devices must be preset according to case requirements using provided setup test cases. In practice, this means for example data transfer requires preconnected host enabled USB cable and host mode supporting device is connected to system. Each test case prints out required user interaction to terminal.

• USB - Setup host driver
• USB - Setup peripheral driver
• USB - Read test
• USB - Write test

Software Coverage

Current coverage for USB tests:

• [USB-coverage.ods]

Hardware Coverage

Configurable USB endpoint transfer test cases.

Limitations

• Drivers must be initialized before running other test cases.
• All other gadget drivers MUST be unloaded before test execution in used DUT!
• All USB cables MUST be disconnected when executing initializations!

Future Improvements

• Automated test execution and peripheral DUT driver selection.
• Official unique USB driver ID.

Running the tests

Hardware setup and test execution order

Required hardware:

• Supported USB cable
• Device with USB host capability (e.g. PC)
• Device with USB peripheral capability (e.g. Nokia N810/N900)

How to setup test environment:

1. Make sure usb cable is disconnected between devices
2. Set up host side (e.g. PC) by running test 'USB - Setup host driver'
3. Set up gadget side (peripheral device) by running test 'USB - Setup peripheral driver'
4. Connect cable
5. Execute tests

NOTE: Before executing test cases it must be determined if used devices are capable of acting as peripheral or host. This depends on USB controller chips of devices and necessary information should be available from device vendors.

To run test cases, execute the command:

$ blts_usb_testrunner -C [config file] -e [test number]

The test environment must have following packages installed:

• libbltscommon1

Building packages

The build environment must have the following packages installed:

• libbltscommon-devel
• kernel-devel

The source package includes the pack.sh script, which is used for building RPM and Debian packages and source tar packages. To build an RPM package with the script, execute this command in the top level source directory of asset:

./pack.sh -r

To get help about the packaging script, execute

./pack.sh -h

The asset can also be built manually by executing:

./autogen.sh
./configure
make

Configuration package

The blts-usb package is dependent on blts-usb-tests-config configuration file package. The packaging script pack.sh creates RPM package blts-usb-tests-config-example_{version}.rpm and it must be installed first. The configuration files are copied in the test device during RPM installation.

The configuration file package can be installed in the device with a command:

rpm -ivh blts-usb-tests-config-example_{version}.rpm

This test asset uses two configuration files: One for generic test execution options and one for endpoint configuration. Endpoint configuration file is linked to base configuration files thus only base file path is given as parameter. Configuration files must be used, as they contain endpoint configuration for driver.

Currently following example base configuration file is included in the package:

• blts-usb-testrunner-default.cnf

The base files are linked to endpoint configuration files and following example is provided with test package:

• ep-configuration-default.cfg

NOTE: Supported endpoint configurations differ from device to device and they should be modified according to test execution requirements. These configuration files are provided as examples and should not be used as such during proper test execution.

For further instructions on creating and using configuration files, see Configuration file examples.

Test asset specific instructions

The test package can be installed in the device by executing the command:

rpm -ivh blts-usb-tests_{version}.rpm 

Common test execution guidelines

NOTE:

• Default config files are installed to /etc/blts
• Drivers must be initialized before running other test cases.
• All USB cables MUST be disconnected when executing initializations!

NOTE: All other gadget drivers MUST be unloaded before test execution in used DUT!

You can use command lsmod to determine which modules are loaded in memory:

$ lsmod

See if some gadget driver is found. For example g_file_storage is a mass storage module, but this depends on used HW and SW. The module can be unloaded with following command:

$ modprobe -r g_file_storage

Test case arguments

Arguments:

Running test cases

Test case execution notices:

* This test is run on host device.
# This test is run on peripheral device.

Test case descriptions and execution commands:

• USB - Setup host driver

* Setup host driver for test execution. Command line parameter:

* -h <name> : Use <name> as host driver (default: blts_usb_host)

* $ blts-usb-tests -en "USB - Setup host driver"

• USB - Setup peripheral driver

* Setup peripheral driver for test execution. Command line parameter:

* -p <name> : Use <name> as peripheral driver (default: blts_gadget)

* $ blts-usb-tests -en "USB - Setup peripheral driver"

• USB - Read test

* Read data from available endpoints. Command line parameter:

* -h <name> : Use <name> as host driver (default: blts_usb_host)

* $ blts-usb-tests -en "USB - Read test"

• USB - Write test

* Write data to available endpoints. Command line parameter:

* -h <name> : Use <name> as host driver (default: blts_usb_host)

* $ blts-usb-tests -en "USB - Write test"

Configuration file examples

The test asset allows you to change all endpoint parameters via configuration files. Since the USB (2.0) specification only states the valid range for different settings, it is possible to give any values as long as they fit inside these ranges. The test asset allows experimenting with different configurations and "triangulation" of what works and what does not. Naturally there are certain HW related restrictions such as total transfer capacity which obviously cannot be exceeded with endpoint configuration. Basic test asset configurations is done with base configuration files, such as provided blts-usb-testrunner-default.cnf:

# USB test case configuration for parameters

######################
# General parameters #
######################

[parameter]
	name host_driver
	const "blts_usb_host"
[end_parameter]

[parameter]
	name host_driver_path
	const "/usr/lib/tests/blts-usb-tests/"
[end_parameter]

[parameter]
	name peripheral_driver
	const "blts_gadget"
[end_parameter]

[parameter]
	name peripheral_driver_path
	const "/usr/lib/tests/blts-usb-tests/"
[end_parameter]

[parameter]
	name data_transfer_timeout
	const "10000"
[end_parameter]

[parameter]
	name usb_transfer_size
	const 4096
[end_parameter]

##########################
# Endpoint configuration #
##########################

[parameter]
	name ep_configuration_file
	const "/etc/blts/ep-configuration-default.cfg"
[end_parameter]

################
# Driver setup #
################

[test]
	name "USB - Setup host driver"
	params host_driver host_driver_path
[end_test]

[test]
	name "USB - Setup peripheral driver"
	params peripheral_driver peripheral_driver_path usb_transfer_size ep_configuration_file
[end_test]

#######################
# Data transfer cases #
#######################

[test]
	name "USB - Read test"
	params host_driver host_driver_path peripheral_driver peripheral_driver_path usb_transfer_size
[end_test]

[test]
	name "USB - Write test"
	params host_driver host_driver_path peripheral_driver peripheral_driver_path usb_transfer_size
[end_test]

To change the endpoint configuration, you will have to edit ep-configuration files. For example, provided ep-configuration-default.cfg looks like this by default:

# device_speed used_speed max_power
high any 50
# endpoint type direction max_packet_size interval
1 bulk in 512 9
2 bulk out 512 9

The lines starting with # are comments and document provided parameters. Device_speed is the highest speed used device is supposed to be able handle (any/low/full/high) and used_speed the operational speed during test execution. This can be used to force the device to use lower speed than normally would be used. To add new pair of bulk endpoints simply add following lines to the file:

3 bulk in 512 9
4 bulk out 512 9

Do note that you can put different endpoint types to the same configuration so there can be any combination of bulk, interrupt and isochronous endpoints as long as device supports this.

Module Design and Architecture

Both Debian and RPM package is provided. The package includes both host and peripheral drivers in addition to test runner. This package can be installed on all devices under testing, although functionality depends on used hardware.

Architecture diagram

References

Change History