Linux and 3Com EtherLink Vortex/Boomerang Cyclone Ethercards

This page contains Linux device drivers and information on the 3Com "Vortex", "Boomerang", "Cyclone", "Hurricane", and "Tornado" series ethercards. The master copy resides on the CESDIS WWW server.

3Com Vendor-supported driver

A second driver implementation is now available for certain 3Com PCI boards.

In September 1999 3Com released a driver for the 3c905B and 3c905C series. This driver was written in-house, and is available under the GPL from. http://support.3com.com/infodeli/tools/nic/linux.htm

Note that the 3Com driver, named 3c90x.c, supports only recent production boards. The driver described on this page, named 3c59x.c, supports all generations of PCI boards. (See complete list below.)

Supported boards

PCI boards

The supported models are the PCI EtherLink III 3c590 "Vortex" series, (3c590 and 3c595), the PCI EtherLink XL "Boomerang" series (3c900 and 3c905), the 3c905B "Cyclone" series, and the 3c905C "Tornado" series.

EISA boards

Also supported are 3c592 and 3c597 EISA boards.

CardBus cards

The "3c59x.c" driver source supports the 3Com CardBus Ethernet adapters. The driver must be compiled with the -DCARDBUS flag, and the resulting driver binary differs from the PCI version. The suggested compile command is at the bottom of the file, and the directions are included with the PCMCIA package.

ISA EtherLink cards

The ISA 3c515 "Corkscrew" has a separate driver that is similar, but a different register layout makes it impractical to fold into the unified Vortex-series driver.

Why do we use names like "Vortex"?

These are the 3Com internal names for the implementations. The names make it clear which product we are talking about, and the product numbers are often mistyped -- even I've made the mistake of refering to the 3c509 when I meant 3c905. (3Com only purchased rights to the numbers '3' '5' and '9', Intel owns '4', '8', '6', and '2'. '0' and '1' are still in the public domain ;-)

See also the

  • Vortex driver development page.
  • Linux-vortex mailing list archive on Tux.
  • Tux linux-vortex-bug mailing list archive.
  • Back-up Mailing List archive (external link, Greg J. Siekas).
  • Back-up Vortex-bugs Mailing List archive (external link, Greg J. Siekas).
  • 3Com logo3Com web site

    Usage instructions

    When loaded as a module the following variables may be set:
    name type description
    debug int The debug message level, 0 (no messages) to 6 (wordy).
    options int[] The media type override and card operation settings (See list below.)
    full_duplex int[] Force full duplex.
    max_interrupt_work int Maximum number of events to handle at each interrupt, default 20.
    rx_copybreak int See driver source for tuning details.

    An example of loading the vortex module is

    	insmod 3c59x.o debug=1 options=0,,4  full_duplex=0,0,1
    
    This sets the debug message level to minimal messages, sets the first card to the 10baseT transceiver, the second to the EEPROM-set transceiver, and the third card, a 3c595, to operate in full-duplex mode using its 100baseTx transceiver. (Note: card ordering is set by the PCI BIOS.) Possible media type settings
    index media
    0 Auto-select (default to the 10baseT link)
    1 AUI
    2 undefined (special case: 10baseT from the LILO prompt)
    3 10base2 (BNC)
    4 100baseTx Symbol mode, valid for 3c595 only.
    5 100baseFx Symbol mode, valid for 3c595 only.
    6 MII (the correct transceiver type on the 3c905A)
    8 3c905B internal transceiver (the correct transceiver type on the Cyclone)
    9 External MII, for the 3c905B Cyclone
    0x200 Add to above values to force full-duplex.

    Note that the preferred method of using full duplex is to allow autonegotiation to take place. If you must force full duplex when commmunicating with older equipment use the full_duplex module parameter in preference to the options flag.

    Driver Source Code

    The driver source code is available from ftp://cesdis.gsfc.nasa.gov/pub/linux/drivers/3c59x.c.
    The latest Development/Test version may be available as ftp://cesdis.gsfc.nasa.gov/pub/linux/drivers/test/3c59x.c.

    Pre-compiled Driver Modules

    I do not provide pre-compile driver modules, since each distribution would require its own binary for warning-free module insertion.

    Updating Driver Source Code, and Pre-Patched Kernels

    The great folks at VA Research are providing pre-patched kernel source trees for various kernel versions from ftp.varesearch.com.

    If you have a 2.0 series kernel, it's easy to do the update yourself. Just replace your old linux/drivers/net/3c59x.c file with the updated driver source.

    Building and Using the Driver as a Module

    See Using Linux Network Drivers as Modules

    Support

    Mailing lists

    Support for the Vortex and Boomerang drivers is now being handled through the mailing list linux-vortex-bug@beowulf.gsfc.nasa.gov. This mailing list is appropriate for most topics including bug reports, performance reports, and suggestion for driver improvement. To subscribe, send a message with the contents "subscribe" e.g.:

    echo subscribe | /bin/mail linux-vortex-bug-request@beowulf.gsfc.nasa.gov

    New driver announcements are made (and occasional discussions held) on the mailing list linux-vortex@beowulf.gsfc.nasa.gov.

    Typical Problems

    "modversions.h not found" reported when compiling the driver.

    Delete '-DMODVERSIONS' from the command used to compile the driver module.

    Transmit error status

    When a transmit error occurs the driver produces a status message such as

    "eth0: Transmit error, Tx status register 82. The two values typically seen are
    0x82
    Out of window collision. This typically occurs when some other Ethernet host is incorrectly set to full duplex on a half duplex network.
    0x88
    16 collisions. This typically occurs when the network is exceptionally busy or when another host doesn't correctly back off after a collision. If this error is mixed with 0x82 errors it is the result of a host incorrectly set to full duplex (see above).
    Both of these errors are the result of network errors that should be corrected. They do not represent driver malfunction.

    The bits in the status word are:
    value description
    0x02 Out-of-window collision.
    0x04 Status stack overflow (normally impossible).
    0x08 16 collisions.
    0x10 Tx underrun (not enough PCI bus bandwidth).
    0x20 Tx jabber.
    0x40 Tx interrupt requested.
    0x80 Status is valid (this should always be set).

    What if the card is detected with a ff:ff:ff:ff:ff:ff station address?

    Read the Help File on this topic.

    Quick-fixups (but read the above section when you get a chance):

    100mbps link reported as 10mpbs with 'ifconfig'.

    The 'ifconfig' program is reporting the Link Encapsulation Type, not the link speed. In some cases detecting the link speed takes considerable time, so the drivers don't implement this. Complete link information can read from the card using the vortex-diag program.

    I know the 'ifconfig' report is misleading -- I've answered this hundreds of inquires about it. The wording has been changed in new 'ifconfig' versions to report only "Ethernet".

    Special Micron instructions

    Some motherboards have a broken PCI BIOS implementation that doesn't actually map the card to the reported I/O address. This problem affects most OSes as well as the 3Com setup program for MS-DOS. The work-around is to disable "Plug-and-Play" in the BIOS setup.

    Some Micron motherboards use a fixed PCI slot to IRQ mapping. If you encounter an IRQ conflict, evidenced by an EAGAIN error when opening the interface, physically move the card to a different PCI slot. Typically the "shared" PCI/EISA position has a non-shared IRQ.

    Special Dell instructions

    A "SIOSIFFLAGS: Try again when starting an ethernet device means that there is an interrupt conflict. Dell machines tend to assign multiple PCI devices to the same IRQ line. Generally this works under Linux -- most PCI drivers are willing to share IRQ lines (with the inevitable increase in CPU overhead). But some drivers, specifically several SCSI drivers use the so-called "fast" interrupt structure that is incompatible with most other drivers. See IRQ conflict page for more information.

    Special Compaq instructions

    Early Compaq PCI machines used an unusual PCI BIOS implementation that is mapped to high memory. Most Linux kernel versions are unable to work with it. A work-around is to boot first into MS-DOS and run a Compaq-supplied program to remap the PCI BIOS tables. A better fix is to get a BIOS update from Compaq. The 3c59x driver implements a special work-around by setting ioaddr and irq values, but this feature is depricated and will be removed in future versions.

    Possible problems and solutions

    The machine immediately hangs when the interface is activated

    Put the card on its own IRQ line to isolate the problem. Specifically, avoid having the card share an IRQ with a video card while running X Windows, and avoid SCSI adapters when possible.

    Compile Errors

    If you get an "linux/version.h no such file or directory" you either have not installed the kernel source code, or you haven't run

    	cd /usr/src/linux; make include/linux/version.h
    yet. Some distributions allow you to install just the essential header files of the kernel source code, including a pre-built "version.h", so this isn't always necessary.

    Ancient Driver Update Log

    v0.40 of 4/18/97
    Split the Vortex-mode and Boomerang-mode transmit routines.
    The driver now falls back to the Vortex mode when the Boomerang mode Tx or Rx fails.
    v0.41 of 6/16/97
    Increased RX_RING_SIZE from 16 to 32.
    Made rx_copybreak a module-settable variable.
    Added 2.1.* support with test_and_set_bit().
    Read the ethernet address from the Vendor rather than OEM EEPROM location.
    Added Rx-pacing bug fix by doing whole-Rx-frame threshold.
    Set full-duplex bit from passed-in option.
    Work with oversized (more than 1500 byte) MTU.
    Added switch to non-bus-master receive when we encounter an error.
    Split Boomerang and Vortex transmit functions.
    Correct compile-command for 3c59x.c name.
    v0.42 of 7/15/97 Added transmit-timeout code from Michael Sievers (sieversm@mail.desy.de).
    v0.43 of 9/2/97
    Added MII-read code to detect the full-duplex status of the link.
    v0.44 of 9/9/97
    Many changes:
    MII ioctl() code so that a non-device-specific user-level program may query and configure the transceiver.
    MII_sync() included, for MDIO preamble suppression (which is now done without assuming a 83840A transceiver).
    More variables settable when loaded as a module. See the top of the driver file for details.
    Different (perhap better?) 16-collision recovery code.
    v0.45 of 9/11/97
    Turn on TxComplete interrupt to enable the v0.44 16-collision recovery.
    v0.46 of 9/19/97
    Fixed inb() statement in TxComplete interrupt, and flushed TxStatus FIFO on TxComplete error.

    Related resources

    This driver was written to support the Beowulf cluster project at CESDIS. For Beowulf-specific information, read the Beowulf project description.

    Old Announcements

    Installation instructions for 1.2.13

    Alternate patch files

    Alternate patch files will be made available for other popular kernel versions. Send me email if you have a request.

    Acknowledgments

    Thanks to Terry Murphy, Terry_Murphy@3mail.3Com.COM, and Cameron Spitzer, cls@truffula.sj.ca.us, of 3Com for providing the 3c590 and 3c595 ethercards and the databook.

    CESDIS is located at the NASA Goddard Space Flight Center in Greenbelt MD.


    Top
    Author: Donald Becker, becker@cesdis.gsfc.nasa.gov.