USB TestDrive Network Scripts

The TestDrive scripts described here can be used to load the appropriate modules for all of the various network protocols and variants supported by USBLAN. In the case of RNDIS, it is also possible to tell Windows to use the built-in VID/PID values (therefore not using USBLAN). This allows USBLAN/native RNDIS comparison.

The scripts described here are the foundation: they load network protocols. After this has been done, various network tests can be run. These are described elsewhere.

Supported Protocols

The supported protocols are:

• ECM
• EEM
• NCM
• ECM subset
• SAFE (another ECM subset)
• RNDIS

Stacks

All the protocols, can be loaded with the std (Gadget) implementation in the Linux kernel, or the btc (Belcarra) implementation. In particular Belcarra’s implementation of NCM and EEM is more advanced in important ways that are explained below.

Basic invocation modelThe scripts use a uniform invocation model as follows
stack-protocol [-q] VID PID [IP]

Here, stack is one of the following: std (for Gadget) or btc (for Belcarra)
The protocol is one of the following

• ecm
• eem
• ncm
• ecm.subset
• safe (BTC stack only)
• rndis (STD stack only)

Two arguments are surrounded by [ ] meaning that they are optional.

• -q means quick. If this option is given the action is taken without interactive confirmation. Otherwise, the user is presented with a summary of the proposed actions and asked for confirmation before the modules are loaded.
• VID is the USB Vendor ID. For Belcarra the value is 15ec. Note that this value must not be preceded by 0x
• PID is the USB Product ID. For the Demo edition of USBLAN, available from Windows Update, this is one of the following three values: D020, D021, D022. As with VID, these values are not preceded by 0x.
• IP is the designated IP address of the interface once it is created. If this argument is omitted or set to the special value 0.0.0.0 then no IP value is set by the script -- in this case the IP address may (see below) be set by USBLAN’s DHCP service

Belcarra EEM
The Belcarra implementation of EEM offers a number of enhancements compared to the Gadget implementation, as described in the following subsections

The device receive buffer

The EEM protocol allows for aggregation of frames in both directions, and also for larger USB transfers. However, the EEM standard does not specify a mechanism whereby a host driver (running under Windows) can discover the capabilities of a device.

RNDIS

The Testdrive environment includes the Gadget version

Special handling of RNDIS VID/PID

If the protocol is RNDIS and VID/PID are both omitted, then this means that the internal defaults of Gadget RNDIS are used, meaning that Windows will use the built-in RNDIS, not the USBLAN implementation.

Loading RNDIS support in Windows
When using the RNDIS support built into USBLAN, RNDIS becomes available whenever USBLAN has been installed for a given VID/PID combination, even if another protocol was used. For instance, consider the following sequence of events

• run std-rndis -q 15ec d021 
• Connect the USB cable
• Follow prompts in Windows to connect to Windows Update

After this, the following command activates ECM on the same NDIS interface in Windows:
std-ecm -q 15ec d021

To use the built-in (Microsoft) implementation of RNDIS, omit the VID and PID from the std-rndis command. Then after connecting the USB cable, you will be prompted to connect to Windows update (as before), but the Microsoft driver will be activated instead of USBLAN. This will create a new NDIS (network) interface. Therefore, you can always tell which version of RNDIS is active from the Control Panel in Windows.

Summary of scripts

• btc-ecm [-q] VID PID [IP]
• Unload all loaded network modules, then load Belcarra implementation of ECM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay.
• btc-ecm.subset [-q] VID PID [IP]
• Unload all loaded network modules, then load Belcarra implementation of an ECM subset with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay. This subset is useful on hardware which cannot implement the full ECM protocol.
• btc-safe [-q] VID PID [IP]
• Unload all loaded network modules, then load Belcarra implementation of the SAFE subset of ECM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay. SAFE is a slightly less restricted subset tan the preceding subset. Neither subset is needed on the Overo, but may be on other older hardware, and are provided here for demonstration purposes.
• btc-eem [-q] VID PID [IP]
• Unload all loaded network modules, then load Belcarra implementation of EEM with the specified parameters. If the optional IP address is non-zero, then set the given IP address after a short delay. The Belcarra implementation of EEM has significant improvements compared to that available in the Gadget implementation. Refer to Belcarra EEM section below for details.
• btc-ncm [-q] VID PID [IP]
• Unload all loaded network modules, then load Belcarra implementation of NCM with the specified parameters. If optional IP address is non-zero, then set the given IP address after a short delay.
• std-ecm [-q] VID PID [IP]
• Unload all loaded network modules, then load standard (Gadget) implementation of ECM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay.
• std-ecm.subset [-q] VID PID [IP]
• Unload all loaded network modules, then load standard (Gadget) implementation of a subset of ECM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay. The subset implemented here is identical that implemented by btc-ecm.subset.
• std-eem [-q] VID PID [IP]
• Unload all loaded network modules, then load standard (Gadget) implementation of EEM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay.
• std-ncm [-q] VID PID [IP]
• Unload all loaded network modules, then load standard (Gadget) implementation of NCM with the specified parameters.If IP address is non-zero, then set the given IP address after a short delay.
• std-rndis -q [IP]
• unload all network modules already loaded
• load the Gadget version of RNDIS, using the internal (default) vendor and product ID.  
• If a cable is now connected to a Windows 7 box, then the Microsoft implementation of RNDIS, using an Acer VID/PID combination will be loaded from Windows Update
• If the optional IP address is specified, its value is set as the IP address of usb0 after a short delay.
• std-rndis -q VID PID [IP]
• unload all network modules already loaded
• load the Gadget version of RNDIS, using the internal (default) vendor and product ID.  
• If a cable is now connected to a Windows 7 box, and the VID/PID match a USBLAN INF file (for example 15ec/d021 for the Demo version of USBLAN) then the Belcarra implementation of RNDIS, using the specified combination will be loaded, possibly from Windows Update.
• If the optional IP address is specified, its value is set as the IP address of usb0 after a short delay.