Documentation/networking/vortex.txtAndrew Morton <andrewm@uow.edu.au>30 April 2000This document describes the usage and errata of the 3Com "Vortex" devicedriver for Linux, 3c59x.c.The driver was written by Donald Becker <becker@scyld.com>Don is no longer the prime maintainer of this version of the driver. Please report problems to one or more of:  Andrew Morton <andrewm@uow.edu.au>  Netdev mailing list <netdev@oss.sgi.com>  Linux kernel mailing list <linux-kernel@vger.kernel.org>Please note the 'Reporting and Diagnosing Problems' section at the endof this file.Since kernel 2.3.99-pre6, this driver incorporates the support for the3c575-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   3c900B Cyclone 10Mbps T   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/unknownModule parameters=================There are several parameters which may be provided to the driver whenits module is loaded.  These are usually placed in /etc/modules.conf(used to be conf.modules).  Example:options 3c59x debug=3 rx_copybreak=300If you are using the PCMCIA tools (cardmgr) then the options may beplaced in /etc/pcmcia/config.opts:module "3c59x" opts "debug=3 rx_copybreak=300"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:  Possible 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:  0x8000  Set driver debugging level to 7  0x4000  Set driver debugging level to 2  0x0400  Enable Wake-on-LAN  0x0200  Force full duplex mode.  0x0010  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.  Please use this in preference to the `options'  parameter.  In fact, please don't use this at all! You're better off getting  autonegotiation working properly.flow_ctrl=N1,N2,N3...  Use 802.3x MAC-layer flow control.  The 3com cards only support the  PAUSE command, which means that they will stop sending packets for a  short period if they receive a PAUSE frame from the link partner.   The driver only allows flow control on a link which is operating in  full duplex mode.  This feature does not appear to work on the 3c905 - only 3c905B and  3c905C have been tested.  The 3com cards appear to only respond to PAUSE frames which are  sent to the reserved destination address of 01:80:c2:00:00:01.  They  do not honour PAUSE frames which are sent to the station MAC address.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 invocation.  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".hw_checksums=N1,N2,N3,...  Recent 3com NICs are able to generate IPv4, TCP and UDP checksums  in hardware.  Linux has used the Rx checksumming for a long time.   The "zero copy" patch which is planned for the 2.4 kernel series  allows you to make use of the NIC's DMA scatter/gather and transmit  checksumming as well.  The driver is set up so that, when the zerocopy patch is applied,  all Tornado and Cyclone devices will use S/G and Tx checksums.  This module parameter has been provided so you can override this  decision.  If you think that Tx checksums are causing a problem, you  may disable the feature with `hw_checksums=0'.  If you think your NIC should be performing Tx checksumming and the  driver isn't enabling it, you can force the use of hardware Tx  checksumming with `hw_checksums=1'.  The driver drops a message in the logfiles to indicate whether or  not it is using hardware scatter/gather and hardware Tx checksums.  Scatter/gather and hardware checksums provide considerable  performance improvement for the sendfile() system call, but a small  decrease in throughput for send().  There is no effect upon receive  efficiency.compaq_ioaddr=Ncompaq_irq=Ncompaq_device_id=N  "Variables to work-around the Compaq PCI BIOS32 problem"....watchdog=N  Sets the time duration (in milliseconds) after which the kernel  decides that the transmitter has become stuck and needs to be reset.   This is mainly for debugging purposes, although it may be advantageous  to increase this value on LANs which have very high collision rates.  The default value is 5000 (5.0 seconds).enable_wol=N1,N2,N3,...  Enable Wake-on-LAN support for the relevant interface.  Donald  Becker's `ether-wake' application may be used to wake suspended  machines.Media selection---------------A number of the older NICs such as the 3c590 and 3c900 series have10base2 and AUI interfaces.Prior to January, 2001 this driver would autoeselect the 10base2 or AUIport if it didn't detect activity on the 10baseT port.  It would thenget stuck on the 10base2 port and a driver reload was necessary toswitch back to 10baseT.  This behaviour could not be prevented with amodule option override.Later (current) versions of the driver _do_ support locking of themedia type.  So if you load the driver module with	modprobe 3c59x options=0it will permanently select the 10baseT port.  Automatic selection ofother media types does not occur.Transmit error, Tx status register 82-------------------------------------This is a common error which is almost always caused by another host onthe same network being in full-duplex mode, while this host is inhalf-duplex mode.  You need to find that other host and make it run inhalf-duplex mode or fix this host to run in full-duplex mode.As a last resort, you can force the 3c59x driver into full-duplex modewith	options 3c59x full_duplex=1but this has to be viewed as a workaround for broken network gear andshould only really be used for equipment which cannot autonegotiate.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://www.scyld.com/network/vortex.htmlDonald Becker's driver development site:     http://www.scyld.com/networkDonald's vortex-diag program is useful for inspecting the NIC's state:     http://www.scyld.com/diag/#pci-diagsDonald's mii-diag program may be used for inspecting and manipulatingthe NIC's Media Independent Interface subsystem:     http://www.scyld.com/diag/#mii-diagDonald's wake-on-LAN page:     http://www.scyld.com/expert/wake-on-lan.html3Com's documentation for many NICs, including the ones supported bythis driver is available at      http://support.3com.com/partners/developer/developer_form.html3Com's DOS-based application for setting up the NICs EEPROMs:	ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exeDriver updates and a detailed changelog for the modifications whichwere made for the 2.3/2,4 series kernel is available at     http://www.uow.edu.au/~andrewm/linux/#3c59x-2.3Autonegotiation 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 <wcw+@CMU.EDU>:  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.  Cisco switches    (Jeff Busch <jbusch@deja.com>)    My "standard config" for ports to which PC's/servers connect directly:        interface FastEthernet0/N        description machinename        load-interval 30        spanning-tree portfast    If autonegotiation is a problem, you may need to specify "speed    100" and "duplex full" as well (or "speed 10" and "duplex half").    WARNING: DO NOT hook up hubs/switches/bridges to these    specially-configured ports! The switch will become very confused.Reporting and diagnosing problems---------------------------------Maintainers find that accurate and complete problem reports areinvaluable in resolving driver problems.  We are frequently not able toreproduce problems and must rely on your patience and efforts to get tothe bottom of the problem.If you believe you have a driver problem here are some of thesteps you should take:- Is it really a driver problem?   Eliminate some variables: try different cards, different   computers, different cables, different ports on the switch/hub,   different versions of the kernel or ofthe driver, etc.- OK, it's a driver problem.   You need to generate a report.  Typically this is an email to the   maintainer and/or linux-net@vger.kernel.org.  The maintainer's   email address will be inthe driver source or in the MAINTAINERS file.- The contents of your report will vary a lot depending upon the  problem.  If it's a kernel crash then you should refer to the  REPORTING-BUGS file.  But for most problems it is useful to provide the following:   o Kernel version, driver version   o A copy of the banner message which the driver generates when     it is initialised.  For example:     eth0: 3Com PCI 3c905C Tornado at 0xa400,  00:50:da:6a:88:f0, IRQ 19     8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.     MII transceiver found at address 24, status 782d.     Enabling bus-master transmits and whole-frame receives.     NOTE: You must provide the `debug=2' modprobe option to generate     a full detection message.  Please do this:	modprobe 3c59x debug=2   o If it is a PCI device, the relevant output from 'lspci -vx', eg:     00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)             Subsystem: 3Com Corporation: Unknown device 9200             Flags: bus master, medium devsel, latency 32, IRQ 19             I/O ports at a400 [size=128]             Memory at db000000 (32-bit, non-prefetchable) [size=128]             Expansion ROM at <unassigned> [disabled] [size=128K]             Capabilities: [dc] Power Management version 2     00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00     10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00     20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10     30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a   o A description of the environment: 10baseT? 100baseT?     full/half duplex? switched or hubbed?   o Any additional module parameters which you may be providing to the driver.   o Any kernel logs which are produced.  The more the merrier.      If this is a large file and you are sending your report to a     mailing list, mention that you have the logfile, but don't send     it.  If you're reporting direct to the maintainer then just send     it.     To ensure that all kernel logs are available, add the     following line to /etc/syslog.conf:         kern.* /var/log/messages     Then restart syslogd with:         /etc/rc.d/init.d/syslog restart     (The above may vary, depending upon which Linux distribution you use).    o If your problem is reproducible then that's great.  Try the      following:      1) Increase the debug level.  Usually this is done via:         a) modprobe driver.o debug=7         b) In /etc/conf.modules (or modules.conf):            options driver_name debug=7      2) Recreate the problem with the higher debug level,         send all logs to the maintainer.      3) Download you card's diagnostic tool from Donald         Backer's website http://www.scyld.com/diag.  Download         mii-diag.c as well.  Build these.         a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is            working correctly.  Save the output.         b) Run the above commands when the card is malfunctioning.  Send            both sets of output.Finally, please be patient and be prepared to do some work.  You may end up working onthis problem for a week or more as the maintainer asks more questions, asks for moretests, asks for patches to be applied, etc.  At the end of it all, the problem may evenremain unresolved.