Documentation/networking/device_drivers/3com/vortex.txt

   1 Documentation/networking/device_drivers/3com/vortex.txt
   2 Andrew Morton
   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
  15   Netdev mailing list <netdev@vger.kernel.org>
  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         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
  66 Module parameters
  67 =================
  68
  69 There are several parameters which may be provided to the driver when
  70 its module is loaded.  These are usually placed in /etc/modprobe.d/*.conf
  71 configuration files.  Example:
  72
  73 options 3c59x debug=3 rx_copybreak=300
  74
  75 If you are using the PCMCIA tools (cardmgr) then the options may be
  76 placed in /etc/pcmcia/config.opts:
  77
  78 module "3c59x" opts "debug=3 rx_copybreak=300"
  79
  80
  81 The supported parameters are:
  82
  83 debug=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
  88 options=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
 128 global_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
 134 full_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
 143 global_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
 148 flow_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
 164 rx_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
 177 max_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 many 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
 186 hw_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
 213 compaq_ioaddr=N
 214 compaq_irq=N
 215 compaq_device_id=N
 216
 217   "Variables to work-around the Compaq PCI BIOS32 problem"....
 218
 219 watchdog=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
 227 enable_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
 235 global_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
 240 Media selection
 241 ---------------
 242
 243 A number of the older NICs such as the 3c590 and 3c900 series have
 244 10base2 and AUI interfaces.
 245
 246 Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
 247 port if it didn't detect activity on the 10baseT port.  It would then
 248 get stuck on the 10base2 port and a driver reload was necessary to
 249 switch back to 10baseT.  This behaviour could not be prevented with a
 250 module option override.
 251
 252 Later (current) versions of the driver _do_ support locking of the
 253 media type.  So if you load the driver module with
 254
 255         modprobe 3c59x options=0
 256
 257 it will permanently select the 10baseT port.  Automatic selection of
 258 other media types does not occur.
 259
 260
 261 Transmit error, Tx status register 82
 262 -------------------------------------
 263
 264 This is a common error which is almost always caused by another host on
 265 the same network being in full-duplex mode, while this host is in
 266 half-duplex mode.  You need to find that other host and make it run in
 267 half-duplex mode or fix this host to run in full-duplex mode.
 268
 269 As a last resort, you can force the 3c59x driver into full-duplex mode
 270 with
 271
 272         options 3c59x full_duplex=1
 273
 274 but this has to be viewed as a workaround for broken network gear and
 275 should only really be used for equipment which cannot autonegotiate.
 276
 277
 278 Additional resources
 279 --------------------
 280
 281 Details of the device driver implementation are at the top of the source file.
 282
 283 Additional documentation is available at Don Becker's Linux Drivers site:
 284
 285      http://www.scyld.com/vortex.html
 286
 287 Donald Becker's driver development site:
 288
 289      http://www.scyld.com/network.html
 290
 291 Donald's vortex-diag program is useful for inspecting the NIC's state:
 292
 293      http://www.scyld.com/ethercard_diag.html
 294
 295 Donald's mii-diag program may be used for inspecting and manipulating
 296 the NIC's Media Independent Interface subsystem:
 297
 298      http://www.scyld.com/ethercard_diag.html#mii-diag
 299
 300 Donald's wake-on-LAN page:
 301
 302      http://www.scyld.com/wakeonlan.html
 303
 304 3Com's DOS-based application for setting up the NICs EEPROMs:
 305
 306         ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
 307
 308
 309 Autonegotiation 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
 342 Reporting and diagnosing problems
 343 ---------------------------------
 344
 345 Maintainers find that accurate and complete problem reports are
 346 invaluable in resolving driver problems.  We are frequently not able to
 347 reproduce problems and must rely on your patience and efforts to get to
 348 the bottom of the problem.
 349
 350 If you believe you have a driver problem here are some of the
 351 steps 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 netdev@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   admin-guide/reporting-bugs.rst 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
 444 Finally, please be patient and be prepared to do some work.  You may
 445 end up working on this problem for a week or more as the maintainer
 446 asks more questions, asks for more tests, asks for patches to be
 447 applied, etc.  At the end of it all, the problem may even remain
 448 unresolved.