Last Modified: 27 September 2005
In Linux kernel 2.6, 'usbnet' can support this standard USB-IF class specification, replacing the older 'CDCEther' or 'cdc-ether' driver. Devices that embed Linux will often support this, using the Linux-USB Gadget driver stack and the 'gether' driver, on hardware such as the NetChip 2280 (USB 2.0 high speed). Epson based devices: cdcsubset. The package provides the installation files for ACER USB Ethernet/RNDIS Driver version 1.1129.0.0. If the driver is already installed on your system, updating (overwrite-installing) may fix various issues, add new functions, or just upgrade to the available version.
USB is a general purpose host-to-device (master-to-slave)I/O bus protocol.It can easily carry network traffic,multiplexing it along with all the other bus traffic.This can be done directly, or with one of the many widely availableUSB-to-network adapter productsfor networks like Ethernet, ATM, DSL, POTS, ISDN, and cable TV.There are several USB class standards for such adapters,and many proprietary approaches too.
This web page describes how to use the Linux usbnet driver,CONFIG_USB_USBNET in most Linux 2.4 (or later) kernels.This driver originally (2.4.early) focussed only onsupporting less conventional types of USB networking devices.In current Linux it's now a generalized core, supporting severalkinds of network devices running under Linux with 'minidrivers',which are separate modulesthat can be as small as a pair of static data tables.
It makes sense to have a common driver core becauseonly a handful of control and setup operations really needproduct- or class-specific code.Most of the driver handles i/o queues and USB faults,which can easily be product-neutral.And for some reason, vendors seem to dislike using standardframing in their Windows drivers, so many minidrivers needto wrap a technically-unnecessary layer of headers aroundEthernet packets for better interoperability.
Another approach to using IP over USB is to make thedevice look like a serial line or telecommunications modem,and then run PPP over those protocols.This document doesn't address those approaches, used sometimeswith USB drivers such as cdc_acm, usb-serial,and with adapters to IRDA or BlueTooth stacks.
Here's an incomplete list of devices that the usbnetdriver works with.It's incomplete because Linux doesn't need to know anythingspecific about products (correctly) implementingthe CDC Ethernet class specification.It's also incomplete because products that usespecialized chips (or which reuse otherproduct designs) may be repackaged without changing how theywork. Two devices with different brand labeling (on thebox and device) may look identical at the USB level.That often removes the need for driver updates, even forlower end devices that don't support thestandard USB-IF CDC Ethernet class.
|Advance USBNET||cdc_subset||(eTEK design)|
|ALi M5632 (chip)||cdc_subset||USB 2.0 high speed; used in various products. The current Linux driver does NOT interoperate with the Win32 'USB Virtual Network Adapter' driver from ALi (now Uli). (That ALI code seems to need a seven byte header that nobody's taught Linux to use.)|
|AnchorChips 2720 (chip)||cdc_subset||used in various products|
|BAFO DirectLinq||plusb||(uses PL-2301)|
|Belkin USB DirectConnect||cdc_subset||(eTEK design)|
|eTEK (design)||cdc_subset||used in various products|
|GeneSys GL620USB-A||gl620a||used in various products, including some motherboards and at least one BAFO product. the half-duplex GL620USB is NOT supported! products using it include the Inland Pro USB Quick Link|
|Jaton USB ConNET||plusb||(uses PL-2302)|
|LapLink Gold||net1080||(uses NetChip 1080)|
|NetChip 1080 (chip)||net1080||used in various products|
|Prolific PL-2301/2302 (chips)||plusb||used in various products; these two chips seem to be all but identical|
|Xircom PGUNET||cdc_subset||(uses AnchorChips 2720)|
Of those, support for the Prolific based devices is the least robust.(Likely better status handshaking would help a lot.)Seek out other options if you can.I've had the best luck with the designs used by Belkin and NetChip.
There are other USB 2.0 high speed (480 Mbit/sec)host-to-host link products available too, with data transfer speedsthat comfortably break 100BaseT speed limits.A single USB 2.0 link should handle even full duplex 100BaseT switches(100 MBit/sec in each direction) with capacity to spare, and morecapable EHCI controllers should handle several such links.
|CDC Ethernet devices (including some cable modems)||cdc_ether||In Linux kernel 2.6, 'usbnet' can support this standard USB-IF class specification, replacing the older 'CDCEther' or 'cdc-ether' driver. |
Devices that embed Linux will often support this, using the Linux-USB Gadget driver stack and the 'g_ether' driver, on hardware such as the NetChip 2280 (USB 2.0 high speed).
|Epson based devices||cdc_subset||Epson provides example firmware.|
|PXA-2xx based PDAs||cdc_subset or rndis||The PXA-250 and PXA-255 are used in successors to SA-1100 based products; there are other similar PXA-based products. 'usbnet' talks to PDAs running standard ARM-Linux kernels with the 'usb-eth' or 'g_ether' drivers.|
|SA-1100 based PDAs||cdc_subset||found in iPAQ, YOPY, and other PDAs using standard ARM Linux kernels; also see the resources at handhelds.org|
|BLOB boot loader||cdc_subset||Some of the boot loaders used with embedded systems allow the OS to be downloaded over USB using TFTP. This is a big help when developing systems which don't have many I/O ports. One such boot loader is BLOB.|
|Sharp Zaurus SL-5000D, SL-5500, SL-5600, SL-6000, A-300, B-500, C-700, C-750, C-760, C-860...||cdc_subset or rndis||These SA-1100 (or PXA-25x) based products don't use standard ARM Linux kernels, but usbnet talks to the gadget-side stack they use. Do NOT add the 'usbdnet' driver, just get the latest 'usbnet' patch if you have one of the newest Zaurus models.|
|RNDIS based devices||rndis||Recent Linux kernels (2.6.14 and later) include experimental support for the RNDIS protocol. Since that's the only USB networking protocol built into MS-Windows, it's interesting even though it's a proprietary protocol with only incomplete public documentation. The driver is young, but it seems to work with at least some Nokia cell phones.|
The cable devices perform a master-to-slave conversion anda slave-to-master conversion ... but these kinds of gadgets don't need the slave-to-master conversion, they're natural slaves!The PDA side initialization is a bit different,but the host side initialization (and most of the other informationprovided here) stays the same.And of course, the USB-enabled gadget could be running some otherOS, maybe an RTOS; it doesn't need to run Linux.It only needs to wrap network packets in one of a few ways,without many demands for control handshaking.
ST Lab USB Ethernet,
|asix||All these are based on the same core hardware. This originally used separate driver, but then it merged with 'usbnet'. Later kernels split out this minidriver into its own module.|
There are also Linux-USB device drivers for ethernet adaptersthat don't use this framework.
|Sometimes they're sold as special 'adapter cables' like this one (which happens to use a Prolific PL-2301 chip). Notice that this has two 'A' connectors built in, as well as the special device (inside the molded plastic; use your X-Ray goggles).|
|Another way to package these devices takes a bit more money to provide two 'B' connectors. They're hooked up using standard 'A-to-B' cables, usually provided with the device, so these again connect to each host using an 'A' connector.|
What do these devices look like inside?You can often open them up to look.The Belkin device shown above has an AVR microcontroller and twogeneral purpose USB interface chips, but most other suchdevices take a lower cost approach using specialized chips.Here's what one looks like. Like the Belkin device above,this one includes LEDs to show data traffic and errors;you'll have to imagine them flashing:
Yes, you may occasionally see 'A-to-A' cablesfor sale; don't waste your money buying them.Those cables are forbidden in USB, since the electrical connectionsdon't make any sense at all. (If you try to use one, you might evenshort out your USB electronics and so need to buy a new system.)Basically, they're missing the extra electronics shown above,which is necessary to let a USB 'master' (host) talk to anotherone, by making both talk through a USB 'slave' (device).(There is one time you may need such cables: when you're working with ahardware development system where the single USB port can be configured&emdash; for development only! &emdash; in either master or slave roles.)
One consequence of supporting multiple devices is thatthe 'usbnet' driver supports several different link levelframing solutions for IEEE 802 packets over USB.(Another is that most bugfixes automatically benefit eventhe devices they weren't seen with.)
Starting with Linux kernel 2.6.14, the framing is handled entirelyby the minidriver (usually a module); the core usbnet frameworkdoesn't know about framing rules any more.Standard Linux kernels supported them in roughly this order:
As yet, there is no Linux support for the new CDC 'Ethernet Emulation Model';other than supporting that link management protocol, there's no end-uservalue in defining yet another framing scheme.Use the 'Simple' framing for new devices; the only good reason to useanything else is to work around hardware problems, when forany reason that hardware can't be changed.
When you connect a usbnet device to a Linux host, it normally issues aUSB hotplug event,which will ensure that the usbnet driver is active.In most GNU/Linux distributions you shouldn't even notice whetherthe driver needed loading. It should just initialize, so thatyou can immediately use the device as a network interface.If it doesn't, then you probably didn't configure this driver(or its modular form) into your kernel build.To fix that, rebuild and reinstall as appropriate;at this time you might also want to upgrade to a recent kernel.
Once that driver starts using that USB device,you'll notice a message like this in your syslog files,announcing the presence of a newusb0 (or usb1, usb2, etc) network interfacethat you can use with ifconfig and similar network tools.
Of course, that might also say 'SA-1100 Linux Device' or 'Zaurus'if you are using such a PDA, or identify some other hardware.Ethernet adapters, or devices that run like them (many cable modems),would normally use names like 'eth0'.
Instead of usb-00:02.0-1.3 (which will likely be differenton your machine) older kernels may show a usbfs name like '005/003'.The 'usbfs' style device naming has problems since it's not 'stable':it can easily change over time.The newer style, output of the usb_make_path() functionin the kernel, is stable; it won't change until you re-cable your tree of USBdevices (or perhaps move your USB adapter card).Stable names let you build systems with logic like'since this link goes to the test network,we will firewall it carefully when we bring it up'.
After a the driver binds to the device, the new interface causes anetwork hotplug eventreporting that a new network interface has been registered.At this time,the interface might look like this through 'ifconfig' or 'ip':
That is, this appears like a normal Ethernet link,not like a point-to-point link.(The older plusb driver, found in 2.2 Linux, wasset up as a point to point link.)That's done for several reasons, most of which boil down tomaking it easier to bridge these links together.Linux has a fully featured IEEE 802.1 bridging module (CONFIG_BRIDGE)with full spanning tree support as supported by normalEthernet bridges.So it's easy toconfigure bridging; a laptop mightconnect to a desktop with a USB networking cable, and then tothe local LAN through a bridge.With that working, DHCP or ZCIP are easy to use from the laptop.(The link level address will usually not be one from amanufacturer's ID prom, except on higher end devices.Instead, it will have been 'locally assigned'during initialization of the 'usbnet' driver.)
When you get these network hotplug events, you basically wantto configure it.As a standard network link,you could just configure it for use with IPv4.Or, you can configure it to work with IPv6 .To bring the interface up by hand, you might type:
In general, you'd rather automate such things. At thiswriting, that's not easily done except for specific GNU/Linuxdistributions (or families of them).The standard hotplug distribution works for everything thatsupports the
ifup command, but that commandunfortunately requires some pre-configuration.
You should usually set the netmask to 255.255.255.0,for a 'class C' (or /24) subnet. Get the right network settingsfrom your local network admin.
With ethtool version 1.5 or later, and recent enough version of theusbnet driver, you can get additional information from the driver.Different devices may have different information available; for example,link availability is not always known.Linux defines some standard interpretations for the 'message level' bits,which are not widely used ... but this framework uses them for all itsdevices, letting you mask which messages will be seen.(Many messages won't be available unless debugging is enabled.)
You might want to use stable bus-info values to figure outwhat network address to assign to a given link, if your routingconfiguration needs that.You can use ip link set usbN name newnameor similar tools.(NOTE: the nameif tool is unfortunately not goingto help here, since it assumes that that Ethernet addressessolve this problem.For dynamically assigned Ethernet addresses, that can'twork; using 'bus-info' is the appropriate solution.)
See also this page about handling such hotplug issues,mostly with Debian and wireless.)
These distributions have an
ifup command that requireseach device to be pre-configured, with a unique config file.If your device is very 'ethernet-like' (named ethN) thenyour sysadmin tools will probably recognize them and helpyou set up the interface; else you'll edit system config files.The rest of these configuration instructions are oriented towardsdevices that are not very 'ethernet-like'.
You can preconfigure those tools, modify the system setup toautomate more of the setup, or more typically do both.The preconfiguration uses files like
/etc/sysconfig/network-scripts/ifup-eth0:you shouldn't have much trouble makingmodified versions for usb0and other USB links you may use.
The network model used in these explanations is the coreof many such models that you will likely need to handle.Two systems are being directly connected.One is a 'leaf' system withno other network connectivity (perhaps a laptop, PDA, or printer).The other is a 'host' that sits on some LAN, and probablyhas Internet access.Those two systems connect through USB network links,and the configuration problem is making sure thereis complete IP connectivity.You'll have to arrange naming and routing yourself,and this section shows how to set up using static IP addressing.
Here's how I set up one laptop, which expects to connect toany of several desktop machines, with a 10.0.1/24 'USB subnet'.Similar setups can use DHCP.
That uses a USB host-to-host cable.USB 'gadgets' that embed Linux can work much the same,but they seldom run RedHat's Linux distribution.See the sections on PDAs and other USB gadgetsor, for dynamic configuration, zeroconf.
Each desktop machine that leaf connects tois set up up like this (different IP and routing oneach interface).
That desktop machine is also set up to do IP level routing,since it's on a LAN that has Internet access.You probably don't want to administer routing machinery exceptwhen you're deploying some kind of firewall.Be very careful about routing, particularly if youuse multiple such links on a given desktop/host.A bridged configuration will be less error prone.
If a host bridges every USB link it sees onto the main LAN, thenonly the link to the main LAN needs to be pre-configured.Less configuration means fewer important things can go wrong.It also eliminates the need to route a two-node subnet for each newUSB network device, making network administrators happier withyour choice of peripheral hardware.
You may be familiar with how bridging works with MicrosoftWindows XP, when you connect your second network link.Only the tools and commands are very different on Linux hosts;most distributions for Linux don't yet provide a way to automaticallyset up your bridge that's as easy.
Linux kernels include a standard IEEE 802 (Ethernet) Bridging module,using the Spanning Tree Protocol (STP) to interoperate withcommercial Ethernet bridge and switch products.Use the Linux kernel 'bridge' module along with the 'bridge-utils'package, which includes the important brctl command.The latest code is available at http://bridge.sourceforge.net.Most current Linux distributions include that package,though usually it's not in the standard software profile.(You might have noticed that the MS-Windows driver provided with mostUSB host-to-host cables implements a limited form of bridging.A key limitation is usually 'no loops': they don't support STP.)
The first part of bridge setup makes a logical LAN during network startup.You'll need to do that by hand, since most sysadmin tools don'tunderstand bridge configuration.(If you're using Ubuntu or Debian, you're lucky to have somedecent examples of how to set up bridges as part of your 'ifupdown'documentation. They're not GUI tools, but they're a better startthan what's sketched here.)I modified the network startup code to bring up eth0 asthe core of bridge, instead of calling 'ifup'.So now it (re)boots into the right configuration, but this setup won't play nicely with RedHat's tools.If your LAN uses DHCP or ZCIP for dynamic address assignment,change the last step appropriately.
The second part of bridge setup makes hotplugging add all USBinterfaces to that bridge.As shown here, nothing happens if there's no 'lan' bridge;so this change could go into config files on any system thatmight ever use a bridge called 'lan' in this particular way.On such systems, you can connect any number of these devicesand they'd be automatically bridged as soon as they connect.
The bridge may cause a short delay (one document saidthirty seconds) before you can access the new devices,and should quickly start forwarding packets.
Be careful using Bridged configurations with PDAs.They may not have unique Ethernet addresses.Among other things, that means that if there's more thanone such PDA in use at your site, everyone who may be bridgingone of them should override that non-unique address.On a Zaurus &emdash; unless you're using Linux 2.6 based OpenZaurusROMs, which don't have this issue &emdash; that'd mean modifying/etc/hotplug/net.agent to make it callifconfig usbd0 hw ether xx:xx:xx:xx:xx:xxbefore it brings the interface up.(Set the local assignment bit, 0x02 in the first octet, toensure it still uses a name like 'usb0' not 'eth0'.)Host-to-host cables automatically use pairs of unique 'locally assigned'IEEE 802 addresses, and do not cause such problems.
The current zcipsoftware works with recent versions of usbnet.(There's also a version of this in current versions of Busybox.)It partially supports the goal ofa fully hands-off user install experience,so that USB peripherals don't requireany sysadmin attention at all during setup,even on networks without DHCP service.(Read more about the IETF Zero Configuration Networking working group.)
A 'leaf' type system might use ZCIP something like this:
Since that setup doesn't use 'ifup' to bring interfaces up,you don't need to manually set up each potential usb link.
Any embedded Linux system coulduse this same IP-over-USB approach if it acts as a USB 'Device',not a USB 'Host'.Many people will be familiar with PDAs running Linux,discussed later in this section,but the embedded system doesn't need to be a PDA.It could be a home gateway, or any other kind of deviceor gadgetwhere embedding Linux can give your product an edge.
In fact, that embedded system doesn't even have to run Linux,even when the processor it uses could support it (32bits, maybe an MMU,and so on).Some of those systems will run a real time OS, and microcontrollersoften use very specialized operating environments.The latest version of the usbnet driver include support forsome firmware that Epson provided to help system-on-chip applications(using Epson SOCs) interoperate better with Linux.
However, if that system does run Linux you can use the newUSB Gadget framework to develop drivers there. That frameworkcomes with a CDC Ethernet driver, which is used in conjunctionwith a driver for the specific hardware involved.The 'Ethernet Gadget' code can achieve dozens of megabytes oftransfer speed in both directions, if the rest of the systemsupports such rates.
Most versions of that gadget stack also support Win32 interoperationusing RNDIS; see linux/Documentation/usb/linux.inf and use thedrivers bundled into XP by Microsoft.You should be able to use 'usbnet' to talk to these gadgetsfrom Linux hosts, and itsdevice side acts much like the iPaq scenario described here.(Except that the interface name is likely usb0instead of usbf or usbd0.)
NOTE for RNDIS users:MS-Windows has problems with its USB and RNDIS stacks,which can not be worked around by Linux peripherals.Symptoms include at one extreme a blue screen (panic),to stopping communication after a while,to (the mildest failure) just a temporary lockup that goesaway after a while.Among other things, it seems that MS-Windows does so much work when hooking up a new device that it's easy for one thing togo wrong, which can sometimes completely lock up the USBport to which you connect the device.You know these are bugs in MS-Windows because those thingsaren't allowed to happen no matter what the externalUSB device does.Unfortunately we can't expect such bugs to get fixedby Microsoft.(Another example of a clear bug in the MSFT code: when hookingthe host link up to the built-in bridging on XP, it disables alluse of multicast and broadcast packets, which are fundamentalto operation of bridges.)
StrongARM SA-1100 based PDAs running GNU/Linux (like the Yopy,or many iPaqs once you replace that other OS with Linux)will network through the usbnet host side driver.They get this by using amainstream ARM kernel suchas 2.6.18, or perhaps thehandhelds.org kernel distribution.(And maybe changing vendor and product IDs.)The CONFIG_SA1100_USB_NETLINK option enables the usb-ethdriver inside that PDA, which talks to usbnet on the host.
Similar support can be provided for essentially any other 'device side'Linux, including XScale PXA-25x based PDAs or other embeddedsystems.In particular, quite a lot of ARM chips have direct support inLinux 2.6 kernels.
The host side initialization in those cases is exactlyas shown earlier, since the host uses the 'usbnet' driver.The kernel in the PDA (or whatever embedded Linux device you'reworking with) uses a slightly different driver.For the www.handhelds.org kernels you'll use theinterface name usbf (for USB Function?).See this wiki page for more information on how to set up youriPAQ (Yopy works the same) to talk to a USB Host running Linux(like current desktop or laptop machines).
At the same time the Linux community was doing the work abovein public, Zaurus SL-5000D development was being done behindclosed doors. The result was a second driverfor everything mentioned above ... and some confusion.There's an incompatible derivative of'usbnet', called usbdnet (just an added 'd'), which expectsto talk to an eth-fd driver (instead of 'usb-eth')inside your Zaurus.
Those two Zaurus-specific driversuse nonstandard framing for Ethernet over USB, although the'eth-fd' driver enumerates as if it were conformant with the CDC Ethernet specification.(Newer versions break conformance in different ways,and claim to conform to the CDC MDLM specification.)That means standard CDC Ethernet drivers need tohave a way to blacklist Zaurus products, since they areincompatible with the protocol standard they advertise.Zaurus framing adds an Ethernet CRC to the normal packet framing(explicitly disallowed by the CDC specification)as a partial work around for some DMA problems.The ARM Linux 'usb-eth' driver and SA-1100 USB stackhaven't needed such nonstandard changes.Another issue is that the two Ethernet addresses advertisedby 'eth-fd' don't seem to be unique, so that using themfor all of the PDAs in a workgroup can be problematic.
In late October 2002 a patch was submitted to teach 'usbnet'how to use the current Zaurus-specific protocol.The 'usbnet' driver now works with all current Zaurus models,including the SL-5000D, SL-5500, SL-5600, C-700, and C-750/C-760.Current 2.6 kernels have it (2.5.45 on), as do 2.4.21and later kernels.That's the preferred solution for Zaurus interoperability.
If you use a standard ARM Linux 2.6 kernel, running g_ether(or an old 2.4 kernel using usb-eth),the question shouldn't come upsince 'usbnet' has interoperated with 'usb-eth' since aboutthe Linux 2.4.10 release.The problem only comes up with code derived from that Zaurus work.
Note that until a patch to the CDCEther driver(on Linux 2.4 only)is available,preventing it from talking to these Zaurus products, you mightneed to add that driver to /etc/hotplug/blacklistto prevent confusion like having your Zaurus appear as eth0and then not work right (because of the CRC).Some users have also found they need to shrink the mtu on the Zaurus,with ifconfig usb0 mtu 1000.
Until that updated 'usbnet' starts to be more widely available,you'll want to read something like this SL-5000HOWTO talking about how to do this with the original Zaurussoftware, and where to get the kernel patches you'll need if youwant to recreate your own kernel.(Or, use the www.handhelds.org kernel tree, Opie,or openzaurus.org.)