Documentation/networking/device_drivers/ethernet/3com/vortex.rst

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