linux/Documentation/networking/vortex.txt
<<
>>
Prefs
   1Documentation/networking/vortex.txt
   2Andrew Morton
   330 April 2000
   4
   5
   6This document describes the usage and errata of the 3Com "Vortex" device
   7driver for Linux, 3c59x.c.
   8
   9The driver was written by Donald Becker <becker@scyld.com>
  10
  11Don is no longer the prime maintainer of this version of the driver. 
  12Please report problems to one or more of:
  13
  14  Andrew Morton
  15  Netdev mailing list <netdev@vger.kernel.org>
  16  Linux kernel mailing list <linux-kernel@vger.kernel.org>
  17
  18Please note the 'Reporting and Diagnosing Problems' section at the end
  19of this file.
  20
  21
  22Since kernel 2.3.99-pre6, this driver incorporates the support for the
  233c575-series Cardbus cards which used to be handled by 3c575_cb.c.
  24
  25This driver supports the following hardware:
  26
  27        3c590 Vortex 10Mbps
  28        3c592 EISA 10Mbps Demon/Vortex
  29        3c597 EISA Fast Demon/Vortex
  30        3c595 Vortex 100baseTx
  31        3c595 Vortex 100baseT4
  32        3c595 Vortex 100base-MII
  33        3c900 Boomerang 10baseT
  34        3c900 Boomerang 10Mbps Combo
  35        3c900 Cyclone 10Mbps TPO
  36        3c900 Cyclone 10Mbps Combo
  37        3c900 Cyclone 10Mbps TPC
  38        3c900B-FL Cyclone 10base-FL
  39        3c905 Boomerang 100baseTx
  40        3c905 Boomerang 100baseT4
  41        3c905B Cyclone 100baseTx
  42        3c905B Cyclone 10/100/BNC
  43        3c905B-FX Cyclone 100baseFx
  44        3c905C Tornado
  45        3c920B-EMB-WNM (ATI Radeon 9100 IGP)
  46        3c980 Cyclone
  47        3c980C Python-T
  48        3cSOHO100-TX Hurricane
  49        3c555 Laptop Hurricane
  50        3c556 Laptop Tornado
  51        3c556B Laptop Hurricane
  52        3c575 [Megahertz] 10/100 LAN  CardBus
  53        3c575 Boomerang CardBus
  54        3CCFE575BT Cyclone CardBus
  55        3CCFE575CT Tornado CardBus
  56        3CCFE656 Cyclone CardBus
  57        3CCFEM656B Cyclone+Winmodem CardBus
  58        3CXFEM656C Tornado+Winmodem CardBus
  59        3c450 HomePNA Tornado
  60        3c920 Tornado
  61        3c982 Hydra Dual Port A
  62        3c982 Hydra Dual Port B
  63        3c905B-T4
  64        3c920B-EMB-WNM Tornado
  65
  66Module parameters
  67=================
  68
  69There are several parameters which may be provided to the driver when
  70its module is loaded.  These are usually placed in /etc/modprobe.d/*.conf
  71configuretion files.  Example:
  72
  73options 3c59x debug=3 rx_copybreak=300
  74
  75If you are using the PCMCIA tools (cardmgr) then the options may be
  76placed in /etc/pcmcia/config.opts:
  77
  78module "3c59x" opts "debug=3 rx_copybreak=300"
  79
  80
  81The supported parameters are:
  82
  83debug=N
  84
  85  Where N is a number from 0 to 7.  Anything above 3 produces a lot
  86  of output in your system logs.  debug=1 is default.
  87
  88options=N1,N2,N3,...
  89
  90  Each number in the list provides an option to the corresponding
  91  network card.  So if you have two 3c905's and you wish to provide
  92  them with option 0x204 you would use:
  93
  94    options=0x204,0x204
  95
  96  The individual options are composed of a number of bitfields which
  97  have the following meanings:
  98
  99  Possible media type settings
 100        0       10baseT
 101        1       10Mbs AUI
 102        2       undefined
 103        3       10base2 (BNC)
 104        4       100base-TX
 105        5       100base-FX
 106        6       MII (Media Independent Interface)
 107        7       Use default setting from EEPROM
 108        8       Autonegotiate
 109        9       External MII
 110        10      Use default setting from EEPROM
 111
 112  When generating a value for the 'options' setting, the above media
 113  selection values may be OR'ed (or added to) the following:
 114
 115  0x8000  Set driver debugging level to 7
 116  0x4000  Set driver debugging level to 2
 117  0x0400  Enable Wake-on-LAN
 118  0x0200  Force full duplex mode.
 119  0x0010  Bus-master enable bit (Old Vortex cards only)
 120
 121  For example:
 122
 123    insmod 3c59x options=0x204
 124
 125  will force full-duplex 100base-TX, rather than allowing the usual
 126  autonegotiation.
 127
 128global_options=N
 129
 130  Sets the `options' parameter for all 3c59x NICs in the machine. 
 131  Entries in the `options' array above will override any setting of
 132  this.
 133
 134full_duplex=N1,N2,N3...
 135
 136  Similar to bit 9 of 'options'.  Forces the corresponding card into
 137  full-duplex mode.  Please use this in preference to the `options'
 138  parameter.
 139
 140  In fact, please don't use this at all! You're better off getting
 141  autonegotiation working properly.
 142
 143global_full_duplex=N1
 144
 145  Sets full duplex mode for all 3c59x NICs in the machine.  Entries
 146  in the `full_duplex' array above will override any setting of this.
 147
 148flow_ctrl=N1,N2,N3...
 149
 150  Use 802.3x MAC-layer flow control.  The 3com cards only support the
 151  PAUSE command, which means that they will stop sending packets for a
 152  short period if they receive a PAUSE frame from the link partner. 
 153
 154  The driver only allows flow control on a link which is operating in
 155  full duplex mode.
 156
 157  This feature does not appear to work on the 3c905 - only 3c905B and
 158  3c905C have been tested.
 159
 160  The 3com cards appear to only respond to PAUSE frames which are
 161  sent to the reserved destination address of 01:80:c2:00:00:01.  They
 162  do not honour PAUSE frames which are sent to the station MAC address.
 163
 164rx_copybreak=M
 165
 166  The driver preallocates 32 full-sized (1536 byte) network buffers
 167  for receiving.  When a packet arrives, the driver has to decide
 168  whether to leave the packet in its full-sized buffer, or to allocate
 169  a smaller buffer and copy the packet across into it.
 170
 171  This is a speed/space tradeoff.
 172
 173  The value of rx_copybreak is used to decide when to make the copy. 
 174  If the packet size is less than rx_copybreak, the packet is copied. 
 175  The default value for rx_copybreak is 200 bytes.
 176
 177max_interrupt_work=N
 178
 179  The driver's interrupt service routine can handle many receive and
 180  transmit packets in a single invocation.  It does this in a loop. 
 181  The value of max_interrupt_work governs how mnay times the interrupt
 182  service routine will loop.  The default value is 32 loops.  If this
 183  is exceeded the interrupt service routine gives up and generates a
 184  warning message "eth0: Too much work in interrupt".
 185
 186hw_checksums=N1,N2,N3,...
 187
 188  Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
 189  in hardware.  Linux has used the Rx checksumming for a long time. 
 190  The "zero copy" patch which is planned for the 2.4 kernel series
 191  allows you to make use of the NIC's DMA scatter/gather and transmit
 192  checksumming as well.
 193
 194  The driver is set up so that, when the zerocopy patch is applied,
 195  all Tornado and Cyclone devices will use S/G and Tx checksums.
 196
 197  This module parameter has been provided so you can override this
 198  decision.  If you think that Tx checksums are causing a problem, you
 199  may disable the feature with `hw_checksums=0'.
 200
 201  If you think your NIC should be performing Tx checksumming and the
 202  driver isn't enabling it, you can force the use of hardware Tx
 203  checksumming with `hw_checksums=1'.
 204
 205  The driver drops a message in the logfiles to indicate whether or
 206  not it is using hardware scatter/gather and hardware Tx checksums.
 207
 208  Scatter/gather and hardware checksums provide considerable
 209  performance improvement for the sendfile() system call, but a small
 210  decrease in throughput for send().  There is no effect upon receive
 211  efficiency.
 212
 213compaq_ioaddr=N
 214compaq_irq=N
 215compaq_device_id=N
 216
 217  "Variables to work-around the Compaq PCI BIOS32 problem"....
 218
 219watchdog=N
 220
 221  Sets the time duration (in milliseconds) after which the kernel
 222  decides that the transmitter has become stuck and needs to be reset. 
 223  This is mainly for debugging purposes, although it may be advantageous
 224  to increase this value on LANs which have very high collision rates.
 225  The default value is 5000 (5.0 seconds).
 226
 227enable_wol=N1,N2,N3,...
 228
 229  Enable Wake-on-LAN support for the relevant interface.  Donald
 230  Becker's `ether-wake' application may be used to wake suspended
 231  machines.
 232
 233  Also enables the NIC's power management support.
 234
 235global_enable_wol=N
 236
 237  Sets enable_wol mode for all 3c59x NICs in the machine.  Entries in
 238  the `enable_wol' array above will override any setting of this.
 239
 240Media selection
 241---------------
 242
 243A number of the older NICs such as the 3c590 and 3c900 series have
 24410base2 and AUI interfaces.
 245
 246Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
 247port if it didn't detect activity on the 10baseT port.  It would then
 248get stuck on the 10base2 port and a driver reload was necessary to
 249switch back to 10baseT.  This behaviour could not be prevented with a
 250module option override.
 251
 252Later (current) versions of the driver _do_ support locking of the
 253media type.  So if you load the driver module with
 254
 255        modprobe 3c59x options=0
 256
 257it will permanently select the 10baseT port.  Automatic selection of
 258other media types does not occur.
 259
 260
 261Transmit error, Tx status register 82
 262-------------------------------------
 263
 264This is a common error which is almost always caused by another host on
 265the same network being in full-duplex mode, while this host is in
 266half-duplex mode.  You need to find that other host and make it run in
 267half-duplex mode or fix this host to run in full-duplex mode.
 268
 269As a last resort, you can force the 3c59x driver into full-duplex mode
 270with
 271
 272        options 3c59x full_duplex=1
 273
 274but this has to be viewed as a workaround for broken network gear and
 275should only really be used for equipment which cannot autonegotiate.
 276
 277
 278Additional resources
 279--------------------
 280
 281Details of the device driver implementation are at the top of the source file.
 282
 283Additional documentation is available at Don Becker's Linux Drivers site:
 284
 285     http://www.scyld.com/vortex.html
 286
 287Donald Becker's driver development site:
 288
 289     http://www.scyld.com/network.html
 290
 291Donald's vortex-diag program is useful for inspecting the NIC's state:
 292
 293     http://www.scyld.com/ethercard_diag.html
 294
 295Donald's mii-diag program may be used for inspecting and manipulating
 296the NIC's Media Independent Interface subsystem:
 297
 298     http://www.scyld.com/ethercard_diag.html#mii-diag
 299
 300Donald's wake-on-LAN page:
 301
 302     http://www.scyld.com/wakeonlan.html
 303
 3043Com's DOS-based application for setting up the NICs EEPROMs:
 305
 306        ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
 307
 308
 309Autonegotiation notes
 310---------------------
 311
 312  The driver uses a one-minute heartbeat for adapting to changes in
 313  the external LAN environment if link is up and 5 seconds if link is down.
 314  This means that when, for example, a machine is unplugged from a hubbed
 315  10baseT LAN plugged into a  switched 100baseT LAN, the throughput
 316  will be quite dreadful for up to sixty seconds.  Be patient.
 317
 318  Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
 319
 320  On a side note, adding HAS_NWAY seems to share a problem with the
 321  Cisco 6509 switch.  Specifically, you need to change the spanning
 322  tree parameter for the port the machine is plugged into to 'portfast'
 323  mode.  Otherwise, the negotiation fails.  This has been an issue
 324  we've noticed for a while but haven't had the time to track down.
 325
 326  Cisco switches    (Jeff Busch <jbusch@deja.com>)
 327
 328    My "standard config" for ports to which PC's/servers connect directly:
 329
 330        interface FastEthernet0/N
 331        description machinename
 332        load-interval 30
 333        spanning-tree portfast
 334
 335    If autonegotiation is a problem, you may need to specify "speed
 336    100" and "duplex full" as well (or "speed 10" and "duplex half").
 337
 338    WARNING: DO NOT hook up hubs/switches/bridges to these
 339    specially-configured ports! The switch will become very confused.
 340
 341
 342Reporting and diagnosing problems
 343---------------------------------
 344
 345Maintainers find that accurate and complete problem reports are
 346invaluable in resolving driver problems.  We are frequently not able to
 347reproduce problems and must rely on your patience and efforts to get to
 348the bottom of the problem.
 349
 350If you believe you have a driver problem here are some of the
 351steps you should take:
 352
 353- Is it really a driver problem?
 354
 355   Eliminate some variables: try different cards, different
 356   computers, different cables, different ports on the switch/hub,
 357   different versions of the kernel or of the driver, etc.
 358
 359- OK, it's a driver problem.
 360
 361   You need to generate a report.  Typically this is an email to the
 362   maintainer and/or linux-net@vger.kernel.org.  The maintainer's
 363   email address will be in the driver source or in the MAINTAINERS file.
 364
 365- The contents of your report will vary a lot depending upon the
 366  problem.  If it's a kernel crash then you should refer to the
 367  REPORTING-BUGS file.
 368
 369  But for most problems it is useful to provide the following:
 370
 371   o Kernel version, driver version
 372
 373   o A copy of the banner message which the driver generates when
 374     it is initialised.  For example:
 375
 376     eth0: 3Com PCI 3c905C Tornado at 0xa400,  00:50:da:6a:88:f0, IRQ 19
 377     8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
 378     MII transceiver found at address 24, status 782d.
 379     Enabling bus-master transmits and whole-frame receives.
 380
 381     NOTE: You must provide the `debug=2' modprobe option to generate
 382     a full detection message.  Please do this:
 383
 384        modprobe 3c59x debug=2
 385
 386   o If it is a PCI device, the relevant output from 'lspci -vx', eg:
 387
 388     00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
 389             Subsystem: 3Com Corporation: Unknown device 9200
 390             Flags: bus master, medium devsel, latency 32, IRQ 19
 391             I/O ports at a400 [size=128]
 392             Memory at db000000 (32-bit, non-prefetchable) [size=128]
 393             Expansion ROM at <unassigned> [disabled] [size=128K]
 394             Capabilities: [dc] Power Management version 2
 395     00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
 396     10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
 397     20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
 398     30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
 399
 400   o A description of the environment: 10baseT? 100baseT?
 401     full/half duplex? switched or hubbed?
 402
 403   o Any additional module parameters which you may be providing to the driver.
 404
 405   o Any kernel logs which are produced.  The more the merrier. 
 406     If this is a large file and you are sending your report to a
 407     mailing list, mention that you have the logfile, but don't send
 408     it.  If you're reporting direct to the maintainer then just send
 409     it.
 410
 411     To ensure that all kernel logs are available, add the
 412     following line to /etc/syslog.conf:
 413
 414         kern.* /var/log/messages
 415
 416     Then restart syslogd with:
 417
 418         /etc/rc.d/init.d/syslog restart
 419
 420     (The above may vary, depending upon which Linux distribution you use).
 421
 422    o If your problem is reproducible then that's great.  Try the
 423      following:
 424
 425      1) Increase the debug level.  Usually this is done via:
 426
 427         a) modprobe driver debug=7
 428         b) In /etc/modprobe.d/driver.conf:
 429            options driver debug=7
 430
 431      2) Recreate the problem with the higher debug level,
 432         send all logs to the maintainer.
 433
 434      3) Download you card's diagnostic tool from Donald
 435         Becker's website <http://www.scyld.com/ethercard_diag.html>.
 436         Download mii-diag.c as well.  Build these.
 437
 438         a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
 439            working correctly.  Save the output.
 440
 441         b) Run the above commands when the card is malfunctioning.  Send
 442            both sets of output.
 443
 444Finally, please be patient and be prepared to do some work.  You may
 445end up working on this problem for a week or more as the maintainer
 446asks more questions, asks for more tests, asks for patches to be
 447applied, etc.  At the end of it all, the problem may even remain
 448unresolved.
 449
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.