Documentation/networking/vortex.txt

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