Documentation/networking/vortex.txt Andrew Morton 30 April 2000 This document describes the usage and errata of the 3Com "Vortex" device driver for Linux, 3c59x.c. The driver was written by Donald Becker Don is no longer the prime maintener of this version of the driver. Please report problems to one or more of: Andrew Morton Netdev mailing list Linux kernel mailing list Please note the 'Reporting and Diagnosing Problems' section at the end of this file. Since kernel 2.3.99-pre6, this driver incorporates the support for the 3c575-series Cardbus cards which used to be handled by 3c575_cb.c. This driver supports the following hardware: 3c590 Vortex 10Mbps 3c592 EISA 10mbps Demon/Vortex 3c597 EISA Fast Demon/Vortex 3c595 Vortex 100baseTx 3c595 Vortex 100baseT4 3c595 Vortex 100base-MII 3Com Vortex 3c900 Boomerang 10baseT 3c900 Boomerang 10Mbps Combo 3c900 Cyclone 10Mbps TPO 3c900 Cyclone 10Mbps Combo 3c900 Cyclone 10Mbps TPC 3c900B-FL Cyclone 10base-FL 3c905 Boomerang 100baseTx 3c905 Boomerang 100baseT4 3c905B Cyclone 100baseTx 3c905B Cyclone 10/100/BNC 3c905B-FX Cyclone 100baseFx 3c905C Tornado 3c980 Cyclone 3cSOHO100-TX Hurricane 3c555 Laptop Hurricane 3c575 Boomerang CardBus 3CCFE575 Cyclone CardBus 3CCFE575CT Cyclone CardBus 3CCFE656 Cyclone CardBus 3CCFEM656 Cyclone CardBus 3c450 Cyclone/unknown 3Com Boomerang (unknown version) Module parameters ================= There are several parameters which may be provided to the driver when its module is loaded. These are usually placed in /etc/modules.conf (used to be conf.modules). Example: options 3c59x debug=3 rx_copybreak=300 If you are using the PCMCIA tools (cardmgr) then theoptions may be placed in /etc/pcmcia/config.opts: module "3c59x" opts "debug=3 extra_reset=1" The supported parameters are: debug=N Where N is a number from 0 to 7. Anything above 3 produces a lot of output in your system logs. debug=1 is default. options=N1,N2,N3,... Each number in the list provides an option to the corresponding network card. So if you have two 3c905's and you wish to provide them with option 0x204 you would use: options=0x204,0x204 The individual options are composed of a number of bitfields which have the following meanings: ssible media type settings 0 10baseT 1 10Mbs AUI 2 undefined 3 10base2 (BNC) 4 100base-TX 5 100base-FX 6 MII (Media Independent Interface) 7 Use default setting from EEPROM 8 Autonegotiate 9 External MII 10 Use default setting from EEPROM When generating a value for the 'options' setting, the above media selection values may be OR'ed (or added to) the following: 512 (0x200) Force full-duplex 16 (0x10) Bus-master enable bit (Old Vortex cards only) For example: insmod 3c59x options=0x204 will force full-duplex 100base-TX, rather than allowing the usual autonegotiation. full_duplex=N1,N2,N3... Similar to bit 9 of 'options'. Forces the corresponding card into full-duplex mode. rx_copybreak=M The driver preallocates 32 full-sized (1536 byte) network buffers for receiving. When a packet arrives, the driver has to decide whether to leave the packet in its full-sized buffer, or to allocate a smaller buffer and copy the packet across into it. This is a speed/space tradeoff. The value of rx_copybreak is used to decide when to make the copy. If the packet size is less than rx_copybreak, the packet is copied. The default value for rx_copybreak is 200 bytes. max_interrupt_work=N The driver's interrupt service routine can handle many receive and transmit packets in a single invokation. It does this in a loop. The value of max_interrupt_work governs how mnay times the interrupt service routine will loop. The default value is 32 loops. If this is exceeded the interrupt service routine gives up and generates a warning message "eth0: Too much work in interrupt". extra_reset=N Where N is 0 or 1 (default 0). Some network cards (notably 3CCFE575CT Cardbus) do not initialise correctly and need an extra transmitter reset. If you find that the card comes up receiving but not transmitting, try giving the module the 'extra_reset=1' option. compaq_ioaddr=N compaq_irq=N compaq_device_id=N "Variables to work-around the Compaq PCI BIOS32 problem".... Additional resources -------------------- Details of the device driver implementation are at the top of the source file. Additional documentation is available at Don Becker's Linux Drivers site: http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html Donald Becker's driver development site: http://www.scyld.com http://cesdis.gsfc.nasa.gov/linux/ Don's vortex-diag program is useful for inspecting the NIC's state: http://www.scyld.com/diag/#pci-diags http://cesdis.gsfc.nasa.gov/linux/diag/vortex-diag.c Don's mii-diag program may be used for inspecting and manipulating the NIC's Media Independent Interface subsystem: http://www.scyld.com/diag/#mii-diag http://cesdis.gsfc.nasa.gov/linux/diag/#mii-diag 3Com's documentation for many NICs, including the ones supported by this driver is available at http://support.3com.com/partners/developer/developer_form.html A detailed changelog for the modifications which were made for 2.3 series kernel is available at http://www.uow.edu.au/~andrewm/linux/#3c59x-2.3 Autonegotiation notes --------------------- The driver uses a one-minute heartbeat for adapting to changes in the external LAN environment. This means that when, for example, a machine is unplugged from a hubbed 10baseT LAN plugged into a switched 100baseT LAN, the throughput will be quite dreadful for up to sixty seconds. Be patient. Cisco interoperability note from Walter Wong : On a side note, adding HAS_NWAY seems to share a problem with the Cisco 6509 switch. Specifically, you need to change the spanning tree parameter for the port the machine is plugged into to 'portfast' mode. Otherwise, the negotiation fails. This has been an issue we've noticed for a while but haven't had the time to track down. Reporting and diagnosing problems --------------------------------- If the driver plays up, there are a number of things you can do analyse the problem and to help others do this: - Turn on debugging in the driver Add 'debug=7' to /etc/modules.conf (/etc/conf.modules) Change 'vortex_debug' to 7 in the source code. - Send all kernel logs, starting with the first probe of the card. - Run 'mii-diag -v' to show the state of the Media Independent Interface. If the card sometimes works and sometimes doesn't, run 'mii-diag -v' in both states. - Please run 'vortex-diag -aaee' in both good and bad states. This show the NIC's registers and EEPROM contents. - Describe your setup: 10baseT, 100baseT, full/half duplex, etc. - Note any additional module insertion commands you're using. - Try different media type settings (see above). - Try inserting the module with 'extra_reset=1' (or compile this into the driver).