Overo Setup and Testing

Belcarra supports a testing environment for testing Networking over USB protocols. This paper will explain the Overo USB Device side software components.

This document, the second of a series, is an overview of the USB Device testing using Belcarra’s Overo USB TestDrive Environment, a Linux test system (available here) based on the Gumstix Overo board. The Overo board is a low cost hardware development system using Texas Instruments’ OMAP 3530 System On Chip (SOC) and supports USB 2.0 for both host and client implementations.

Introduction

The TestDrive system can be used to test and evaluate various Networking over USB protocols and implementations:

• Gadget based network and filestorage function drivers
• Belcarra based network and mass storage function drivers
• Belcarra Windows USBLAN class driver

Preparing to Install

This requires an SD card with at least 4GB of space.  A page at gumstix.org shows how to create a basic 2-partition SD card.  For our demo kit, follow the same procedure, but create three partitions. See Preparing a Micro-SD Memory Card for use with Gumstix COM for further detail.

• Partition 1 FAT32 (per manufacturer’s page), but allow at least 250MB to allow for kernel backups
• Partition 2 ext3, about 2GB (use for the ROOTFS)
• Partition 3 FAT32, remainder of the disk, used for a mass storage volume.

Installation of the TestDrive Kit

The following is an example of how to install the kit.  We have made a few assumptions:

• The SD card as inserted in the Linux host machine maps to devices /dev/sde, /dev/sde1, /dev/sde2, and /dev/sde3. The key item is the letter shown in red. This letter may be different in your environment, depending on what other devices are installed, but the rest should be the same.
• The archive file you downloaded above is located in the current directory (otherwise step 6 below will require revision).
• There is no directory called “extract” in the current directory
• You have prepared the partitions as described above, and the card is inserted into a SD card reader on your Linux host machine
• You have permission, either as the root user, or via the sudo permission table to execute all the commands below.  In particular, the tar command in step 6 needs root permission.

1. On host machine create an empty directory (we’ll call it “extract” for now):

 mkdir extract

2. cd extract
3. mkdir p1 p2 p3
4. Unmount partitions from wherever they are mounted and mount them on p1, p2, and p3. Here’s a sample sequence to achieve this:

1. sudo umount /dev/sde[123] #You will see error messages if some or all of the partitions are not currently mounted
2. sudo mount /dev/sde1 p1
3. sudo mount /dev/sde2 p2
4. sudo mount /dev/sde3 p3

5. Write your local versions of MLO and u-boot to p1 (optional). They are available from here.  Note: MLO must be the first file copied onto extract/p1 due to a size restriction of the Overo’s boot loader.
6. Extract the contents of the archive, using a command similar to the following:

1. sudo tar xjf ../belcarra-gumstix-overo-kit-2011-03-17.tar.bz2

7. Populate the third partition as follows

1. cd p3;sudo unzip ../p3.zip

8. Wait for the SD card to finish writing (this may take a couple of minutes):

1. sudo sync

9. Unmount the volumes and clean up the directory

1. cd ..
2. sudo umount /dev/sde[123]
3. rm -f *.zip

The TestDrive Environment

After preparing the SD card, use it to boot the Overo.  There are three facilities of note:

• The Apache web server. The document root is /usr/share/apache2/httpdocs This directory is pre-populated with a number of useful test files
• The iperf network test-tool
• CrystalDiskMark (for mass storage testing)

Belcarra Windows USBLAN Evaluation Driver

Belcarra’s USBLAN Evaluation Driver is available via Windows Update. It is available for use when a device using either of the following Vendor / Product ID’s is plugged into Windows.

1. 15ec / d041 - enable the built-in DHCP service
2. 15ec / d042 - disable the built-in DHCP service

Please note that the evaluation driver will only work for thirty minutes at a time.

Setting up EEM or ECM on the Overo

Using Belcarra modules -- Demo versions

When the Overo boots, a number of shell functions are available to set up common test requirements. There are 2 “Demo” USB Vendor/Product ID pairs:

• 15ec/d041  Belcarra Demo #1.  
• 15ec/d042  Belcarra Demo #2

For each of these pairs, an evaluation version of Belcarra USBLAN is available from Windows Update for either the EEM or ECM network protocol.  For Demo #1, the built-in DHCP feature of DHCP is activated. For Demo #2, the built-in DHCP feature is not active. See here for more information on USBLAN features, including the built-in DHCP server.

• eem1 -Load Belcarra modules. Select configuration for Demo #1, EEM protocol. Enable USB.  
• eem2 -Load Belcarra modules. Select configuration for Demo #2, EEM protocol. Enable USB.
• ecm1 -Load Belcarra modules. Select configuration for Demo #1, ECM protocol. Enable USB
• ecm2 -Load Belcarra modules. Select configuration for Demo #2, ECM protocol. Enable USB
• ncm1 -Load Belcarra modules. Select configuration for Demo #1, NCM protocol. Enable USB
• ncm2 -Load Belcarra modules. Select configuration for Demo #2, NCM protocol. Enable USB

Note: the above modules first unload the  Gadget modules, if present (see below).  Also there is an optional argument, an IP address.

For instance

        ncm1 169.254.1.2

Means

• Unload the Gadget modules (if present)
• Load Belcarra modules
• Select configuration NCM #1 (VID/PID 15ec/d021)
• Start the USB subsystem
• After a short delay, set the network interface to have IP address 169.254.1.2

The IP address is optional.  In this case, the IP address may be set by the DHCP server (for Demo #1, not Demo #2 VIPD/PID).   Afterwards, if the IP address has not (yet) been set then there is a supplementary net command:

• netwait ipaddress wait for the network interface to be created (if necessary)  and then set the given IP address.

Using Belcarra modules -- general VID/PID

If you have your own version of Belcarra USBLAN with your own values of Vendor ID and Product ID, then you can set up EEM or ECM as follows. Here VID stands for your own vendor ID and PID for your own Product ID

• BTCDOWN -- this command only needed if you have previously loaded Belcarra modules using the command shown above
• BTC_EEM VID PID ipaddress  Set up the CDC-EEM protocol on the given Vendor and Product ID.  Then set the ip address using netwait (see above). The third argument is optional. If it is absent, the IP address is not set by this command (this is suitable for instance for DHCP).
• BTC_ECM VID PID ipaddress Same as BTC_EEM but for the CDC-ECM protocol

Note: after using either of these modules, you must run BTCDOWN before the other functions (eem1, eem2, ecm1, ecm2) will work.

Testing using the Gadget modules

The following commands first unload the Belcarra modules if necessary.

All the commands have an identical format

command [-q] vid pid [ip]

Here command is one of the following: std-ecm std-eem std-ncm for Gadget ECM, Gadget EEM or Gadget NCM respectively.

The optional -q means quick meaning to proceed without user confirmation. Otherwise, the command will first summarize the proposed action before proceeding. The user can press y to proceed or any other key to abort the operation

vid pid are specified as follows:

For Demo #1 15ec d041

For Demo #2 15ec d042

After licensing your own copy of USBLAN, you can substitute your own values. This is convenient for testing USBLAN before your own device is ready for final testing.

ip is an optional IP address. After loading the modules, the system first delays a short time and then sets this IP address. If this value is omitted or is set to the special value 0.0.0.0 then the command does not set the IP address, and instead relies on DHCP.

Examples

std-ecm -q 15ec d041 169.254.12  

Set up Gadget ECM using Demo #1 VID/PID values and set IP address 169.254.1.2. Do not ask for user confirmation

std-ncm 15ec d042

        Set up Gadget NCM, do not set the IP address, using Demo #2  VID/PID values. Ask for user confirmation before proceeding.

Which mode is current?

To discover which modules are in use issue this command:

lsmod

For Belcarra, the list will include network_if.

For Gadget the list will include g_ether or g_ncm (For Gadget the EEM protocol is supported as a part of the g_ether module, which imposes severe limitations on the Gadget implementation).

The gadget modules can be manually unloaded as follows:

rmmod g_ether musb_hdrc  (EEM or ECM)

rmmod g_ncm musb_hdrc (NCM only)

The Belcarra system is more complex and therefore BTCUNLOAD is provided to unload the Belcarra modules

Network testing

There are two major methods available for network benchmarking and stress testing

• Several large test files of progressively larger sizes are available in the Apache document root. These can be retrieved by a shell script on either end of the network link.
• For testing the speed of uploads, the wget program is available on the Overo. This can be used to retrieve files of any size from a host PC.  To avoid issues  with flash size and speed, the --output-document option of wget can be used to send the data to /dev/null.
• For loopback testing, the iperf utility is ideal

Mass Storage testing

Mass storage testing is done as follows

• If network testing is in progress, unload the network modules, as described above
• Run MSCMOUNT (no arguments required).  This function will unmount the third partition of your SD card locally, and offer it as a USB mass  storage volume
• Run MSCWAIT  (no arguments required)  This function will wait until the user has ejected the volume on the PC, and then re-mount the volume locally.
• When the volume is available to the PC the CrystalDiskMark tool is available within the volume. This can be use for either stress or speed testing.  Note: the CrystalDiskMark tool was designed for hard disks, not flash disks. The difference can be readily seen if a test is run on both a hard disk and a flash disk.  Only the “sequential” tests (first row of tests) produce comparable results. The other tests are severely affected by the high wait times for flash erases.

Additional  Documentation

• Belcarra USB TestDrive -  an overview of Belcarra’s Overo USB Test Environment, a Linux based test system based on the Gumstix Overo board.
• TestDrive Panda – Belcarra’s TestDrive environment for the TI PandaBoard

• Windows USB TestDrive Setup - an overview of setting up a Microsoft Windows system (7, Vista, XP)  to do testing of USB devices with tools such as Apache and Cygwin.
• Preparing a Micro-SD Memory Card for use with Gumstix COM how to partition, format, and copy files to a 4GB Micro-SD memory card for the Belcarra Overo TestDrive project

Related Sites

• Belcarra Technologies - design, implementation and support of high performance USB networking solutions
• Belcarra Composite Device Framework - USB client driver and management system
• Belcarra USBLAN - USB Class driver for Microsoft Windows