Documentation/networking/vortex.txt
Andrew Morton <andrewm@uow.edu.au>
18 Feb 2001


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@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 end
of this file.

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 Combo
	3c900B-FL Cyclone 10base-FL
	3c900 Cyclone 10Mbps TPO
	3c900 Cyclone 10Mbps TPC
	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
	3c556 10/100 Mini PCI Adapter
	3c556B Laptop Hurricane
	3c575 Boomerang CardBus
	3CCFE575 Cyclone CardBus
	3CCFE656 Cyclone CardBus
	3CCFEM656 Cyclone CardBus
	3c575 series CardBus (unknown version)
	3c450 HomePNA Tornado
	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

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

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

compaq_ioaddr=N
compaq_irq=N
compaq_device_id=N

  "Variables to work-around the Compaq PCI BIOS32 problem"....

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 have
10base2 and AUI interfaces.

Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
port if it didn't detect activity on the 10baseT port.  It would then
get stuck on the 10base2 port and a driver reload was necessary to
switch back to 10baseT.  This behaviour could not be prevented with a
module option override.

Later (current) versions of the driver _do_ support locking of the
media type.  So if you load the driver module with

	modprobe 3c59x options=0

it will permanently select the 10baseT port.  Automatic selection of
other media types does not occur.


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

Donald Becker's driver development site:

     http://www.scyld.com/network

Donald's vortex-diag program is useful for inspecting the NIC's state:

     http://www.scyld.com/diag/#pci-diags

Donald'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

Donald's wake-on-LAN page:

     http://www.scyld.com/expert/wake-on-lan.html

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

3Com's DOS-based application for setting up the NICs EEPROMs:

	ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe

Driver updates and a detailed changelog for the modifications which
were made for the 2.3/2,4 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.

  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 are
invaluable in resolving driver problems.  We are frequently not able to
reproduce problems and must rely on your patience and efforts to get to
the bottom of the problem.

If you believe you have a driver problem here are some of the
steps 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.

   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 on
this problem for a week or more as the maintainer asks more questions, asks for more
tests, asks for patches to be applied, etc.  At the end of it all, the problem may even
remain unresolved.

