Documentation/networking/vortex.txt
Andrew Morton <andrewm@uow.edu.au>
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 <becker@cesdis.gsfc.nasa.gov>

Don is no longer the prime maintener 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.rutgers.edu>

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"....

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.  The default value is 400 (0.4
  seconds).

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 <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.


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).


