0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =========================
0004 3Com Vortex device driver
0005 =========================
0006
0007 Andrew Morton
0008
0009 30 April 2000
0010
0011
0012 This document describes the usage and errata of the 3Com "Vortex" device
0013 driver for Linux, 3c59x.c.
0014
0015 The driver was written by Donald Becker <becker@scyld.com>
0016
0017 Don is no longer the prime maintainer of this version of the driver.
0018 Please report problems to one or more of:
0019
0020 - Andrew Morton
0021 - Netdev mailing list <netdev@vger.kernel.org>
0022 - Linux kernel mailing list <linux-kernel@vger.kernel.org>
0023
0024 Please note the 'Reporting and Diagnosing Problems' section at the end
0025 of this file.
0026
0027
0028 Since kernel 2.3.99-pre6, this driver incorporates the support for the
0029 3c575-series Cardbus cards which used to be handled by 3c575_cb.c.
0030
0031 This driver supports the following hardware:
0032
0033 - 3c590 Vortex 10Mbps
0034 - 3c592 EISA 10Mbps Demon/Vortex
0035 - 3c597 EISA Fast Demon/Vortex
0036 - 3c595 Vortex 100baseTx
0037 - 3c595 Vortex 100baseT4
0038 - 3c595 Vortex 100base-MII
0039 - 3c900 Boomerang 10baseT
0040 - 3c900 Boomerang 10Mbps Combo
0041 - 3c900 Cyclone 10Mbps TPO
0042 - 3c900 Cyclone 10Mbps Combo
0043 - 3c900 Cyclone 10Mbps TPC
0044 - 3c900B-FL Cyclone 10base-FL
0045 - 3c905 Boomerang 100baseTx
0046 - 3c905 Boomerang 100baseT4
0047 - 3c905B Cyclone 100baseTx
0048 - 3c905B Cyclone 10/100/BNC
0049 - 3c905B-FX Cyclone 100baseFx
0050 - 3c905C Tornado
0051 - 3c920B-EMB-WNM (ATI Radeon 9100 IGP)
0052 - 3c980 Cyclone
0053 - 3c980C Python-T
0054 - 3cSOHO100-TX Hurricane
0055 - 3c555 Laptop Hurricane
0056 - 3c556 Laptop Tornado
0057 - 3c556B Laptop Hurricane
0058 - 3c575 [Megahertz] 10/100 LAN CardBus
0059 - 3c575 Boomerang CardBus
0060 - 3CCFE575BT Cyclone CardBus
0061 - 3CCFE575CT Tornado CardBus
0062 - 3CCFE656 Cyclone CardBus
0063 - 3CCFEM656B Cyclone+Winmodem CardBus
0064 - 3CXFEM656C Tornado+Winmodem CardBus
0065 - 3c450 HomePNA Tornado
0066 - 3c920 Tornado
0067 - 3c982 Hydra Dual Port A
0068 - 3c982 Hydra Dual Port B
0069 - 3c905B-T4
0070 - 3c920B-EMB-WNM Tornado
0071
0072 Module parameters
0073 =================
0074
0075 There are several parameters which may be provided to the driver when
0076 its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf``
0077 configuration files. Example::
0078
0079 options 3c59x debug=3 rx_copybreak=300
0080
0081 If you are using the PCMCIA tools (cardmgr) then the options may be
0082 placed in /etc/pcmcia/config.opts::
0083
0084 module "3c59x" opts "debug=3 rx_copybreak=300"
0085
0086
0087 The supported parameters are:
0088
0089 debug=N
0090
0091 Where N is a number from 0 to 7. Anything above 3 produces a lot
0092 of output in your system logs. debug=1 is default.
0093
0094 options=N1,N2,N3,...
0095
0096 Each number in the list provides an option to the corresponding
0097 network card. So if you have two 3c905's and you wish to provide
0098 them with option 0x204 you would use::
0099
0100 options=0x204,0x204
0101
0102 The individual options are composed of a number of bitfields which
0103 have the following meanings:
0104
0105 Possible media type settings
0106
0107 == =================================
0108 0 10baseT
0109 1 10Mbs AUI
0110 2 undefined
0111 3 10base2 (BNC)
0112 4 100base-TX
0113 5 100base-FX
0114 6 MII (Media Independent Interface)
0115 7 Use default setting from EEPROM
0116 8 Autonegotiate
0117 9 External MII
0118 10 Use default setting from EEPROM
0119 == =================================
0120
0121 When generating a value for the 'options' setting, the above media
0122 selection values may be OR'ed (or added to) the following:
0123
0124 ====== =============================================
0125 0x8000 Set driver debugging level to 7
0126 0x4000 Set driver debugging level to 2
0127 0x0400 Enable Wake-on-LAN
0128 0x0200 Force full duplex mode.
0129 0x0010 Bus-master enable bit (Old Vortex cards only)
0130 ====== =============================================
0131
0132 For example::
0133
0134 insmod 3c59x options=0x204
0135
0136 will force full-duplex 100base-TX, rather than allowing the usual
0137 autonegotiation.
0138
0139 global_options=N
0140
0141 Sets the ``options`` parameter for all 3c59x NICs in the machine.
0142 Entries in the ``options`` array above will override any setting of
0143 this.
0144
0145 full_duplex=N1,N2,N3...
0146
0147 Similar to bit 9 of 'options'. Forces the corresponding card into
0148 full-duplex mode. Please use this in preference to the ``options``
0149 parameter.
0150
0151 In fact, please don't use this at all! You're better off getting
0152 autonegotiation working properly.
0153
0154 global_full_duplex=N1
0155
0156 Sets full duplex mode for all 3c59x NICs in the machine. Entries
0157 in the ``full_duplex`` array above will override any setting of this.
0158
0159 flow_ctrl=N1,N2,N3...
0160
0161 Use 802.3x MAC-layer flow control. The 3com cards only support the
0162 PAUSE command, which means that they will stop sending packets for a
0163 short period if they receive a PAUSE frame from the link partner.
0164
0165 The driver only allows flow control on a link which is operating in
0166 full duplex mode.
0167
0168 This feature does not appear to work on the 3c905 - only 3c905B and
0169 3c905C have been tested.
0170
0171 The 3com cards appear to only respond to PAUSE frames which are
0172 sent to the reserved destination address of 01:80:c2:00:00:01. They
0173 do not honour PAUSE frames which are sent to the station MAC address.
0174
0175 rx_copybreak=M
0176
0177 The driver preallocates 32 full-sized (1536 byte) network buffers
0178 for receiving. When a packet arrives, the driver has to decide
0179 whether to leave the packet in its full-sized buffer, or to allocate
0180 a smaller buffer and copy the packet across into it.
0181
0182 This is a speed/space tradeoff.
0183
0184 The value of rx_copybreak is used to decide when to make the copy.
0185 If the packet size is less than rx_copybreak, the packet is copied.
0186 The default value for rx_copybreak is 200 bytes.
0187
0188 max_interrupt_work=N
0189
0190 The driver's interrupt service routine can handle many receive and
0191 transmit packets in a single invocation. It does this in a loop.
0192 The value of max_interrupt_work governs how many times the interrupt
0193 service routine will loop. The default value is 32 loops. If this
0194 is exceeded the interrupt service routine gives up and generates a
0195 warning message "eth0: Too much work in interrupt".
0196
0197 hw_checksums=N1,N2,N3,...
0198
0199 Recent 3com NICs are able to generate IPv4, TCP and UDP checksums
0200 in hardware. Linux has used the Rx checksumming for a long time.
0201 The "zero copy" patch which is planned for the 2.4 kernel series
0202 allows you to make use of the NIC's DMA scatter/gather and transmit
0203 checksumming as well.
0204
0205 The driver is set up so that, when the zerocopy patch is applied,
0206 all Tornado and Cyclone devices will use S/G and Tx checksums.
0207
0208 This module parameter has been provided so you can override this
0209 decision. If you think that Tx checksums are causing a problem, you
0210 may disable the feature with ``hw_checksums=0``.
0211
0212 If you think your NIC should be performing Tx checksumming and the
0213 driver isn't enabling it, you can force the use of hardware Tx
0214 checksumming with ``hw_checksums=1``.
0215
0216 The driver drops a message in the logfiles to indicate whether or
0217 not it is using hardware scatter/gather and hardware Tx checksums.
0218
0219 Scatter/gather and hardware checksums provide considerable
0220 performance improvement for the sendfile() system call, but a small
0221 decrease in throughput for send(). There is no effect upon receive
0222 efficiency.
0223
0224 compaq_ioaddr=N,
0225 compaq_irq=N,
0226 compaq_device_id=N
0227
0228 "Variables to work-around the Compaq PCI BIOS32 problem"....
0229
0230 watchdog=N
0231
0232 Sets the time duration (in milliseconds) after which the kernel
0233 decides that the transmitter has become stuck and needs to be reset.
0234 This is mainly for debugging purposes, although it may be advantageous
0235 to increase this value on LANs which have very high collision rates.
0236 The default value is 5000 (5.0 seconds).
0237
0238 enable_wol=N1,N2,N3,...
0239
0240 Enable Wake-on-LAN support for the relevant interface. Donald
0241 Becker's ``ether-wake`` application may be used to wake suspended
0242 machines.
0243
0244 Also enables the NIC's power management support.
0245
0246 global_enable_wol=N
0247
0248 Sets enable_wol mode for all 3c59x NICs in the machine. Entries in
0249 the ``enable_wol`` array above will override any setting of this.
0250
0251 Media selection
0252 ---------------
0253
0254 A number of the older NICs such as the 3c590 and 3c900 series have
0255 10base2 and AUI interfaces.
0256
0257 Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
0258 port if it didn't detect activity on the 10baseT port. It would then
0259 get stuck on the 10base2 port and a driver reload was necessary to
0260 switch back to 10baseT. This behaviour could not be prevented with a
0261 module option override.
0262
0263 Later (current) versions of the driver _do_ support locking of the
0264 media type. So if you load the driver module with
0265
0266 modprobe 3c59x options=0
0267
0268 it will permanently select the 10baseT port. Automatic selection of
0269 other media types does not occur.
0270
0271
0272 Transmit error, Tx status register 82
0273 -------------------------------------
0274
0275 This is a common error which is almost always caused by another host on
0276 the same network being in full-duplex mode, while this host is in
0277 half-duplex mode. You need to find that other host and make it run in
0278 half-duplex mode or fix this host to run in full-duplex mode.
0279
0280 As a last resort, you can force the 3c59x driver into full-duplex mode
0281 with
0282
0283 options 3c59x full_duplex=1
0284
0285 but this has to be viewed as a workaround for broken network gear and
0286 should only really be used for equipment which cannot autonegotiate.
0287
0288
0289 Additional resources
0290 --------------------
0291
0292 Details of the device driver implementation are at the top of the source file.
0293
0294 Additional documentation is available at Don Becker's Linux Drivers site:
0295
0296 http://www.scyld.com/vortex.html
0297
0298 Donald Becker's driver development site:
0299
0300 http://www.scyld.com/network.html
0301
0302 Donald's vortex-diag program is useful for inspecting the NIC's state:
0303
0304 http://www.scyld.com/ethercard_diag.html
0305
0306 Donald's mii-diag program may be used for inspecting and manipulating
0307 the NIC's Media Independent Interface subsystem:
0308
0309 http://www.scyld.com/ethercard_diag.html#mii-diag
0310
0311 Donald's wake-on-LAN page:
0312
0313 http://www.scyld.com/wakeonlan.html
0314
0315 3Com's DOS-based application for setting up the NICs EEPROMs:
0316
0317 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
0318
0319
0320 Autonegotiation notes
0321 ---------------------
0322
0323 The driver uses a one-minute heartbeat for adapting to changes in
0324 the external LAN environment if link is up and 5 seconds if link is down.
0325 This means that when, for example, a machine is unplugged from a hubbed
0326 10baseT LAN plugged into a switched 100baseT LAN, the throughput
0327 will be quite dreadful for up to sixty seconds. Be patient.
0328
0329 Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
0330
0331 On a side note, adding HAS_NWAY seems to share a problem with the
0332 Cisco 6509 switch. Specifically, you need to change the spanning
0333 tree parameter for the port the machine is plugged into to 'portfast'
0334 mode. Otherwise, the negotiation fails. This has been an issue
0335 we've noticed for a while but haven't had the time to track down.
0336
0337 Cisco switches (Jeff Busch <jbusch@deja.com>)
0338
0339 My "standard config" for ports to which PC's/servers connect directly::
0340
0341 interface FastEthernet0/N
0342 description machinename
0343 load-interval 30
0344 spanning-tree portfast
0345
0346 If autonegotiation is a problem, you may need to specify "speed
0347 100" and "duplex full" as well (or "speed 10" and "duplex half").
0348
0349 WARNING: DO NOT hook up hubs/switches/bridges to these
0350 specially-configured ports! The switch will become very confused.
0351
0352
0353 Reporting and diagnosing problems
0354 ---------------------------------
0355
0356 Maintainers find that accurate and complete problem reports are
0357 invaluable in resolving driver problems. We are frequently not able to
0358 reproduce problems and must rely on your patience and efforts to get to
0359 the bottom of the problem.
0360
0361 If you believe you have a driver problem here are some of the
0362 steps you should take:
0363
0364 - Is it really a driver problem?
0365
0366 Eliminate some variables: try different cards, different
0367 computers, different cables, different ports on the switch/hub,
0368 different versions of the kernel or of the driver, etc.
0369
0370 - OK, it's a driver problem.
0371
0372 You need to generate a report. Typically this is an email to the
0373 maintainer and/or netdev@vger.kernel.org. The maintainer's
0374 email address will be in the driver source or in the MAINTAINERS file.
0375
0376 - The contents of your report will vary a lot depending upon the
0377 problem. If it's a kernel crash then you should refer to
0378 'Documentation/admin-guide/reporting-issues.rst'.
0379
0380 But for most problems it is useful to provide the following:
0381
0382 - Kernel version, driver version
0383
0384 - A copy of the banner message which the driver generates when
0385 it is initialised. For example:
0386
0387 eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19
0388 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
0389 MII transceiver found at address 24, status 782d.
0390 Enabling bus-master transmits and whole-frame receives.
0391
0392 NOTE: You must provide the ``debug=2`` modprobe option to generate
0393 a full detection message. Please do this::
0394
0395 modprobe 3c59x debug=2
0396
0397 - If it is a PCI device, the relevant output from 'lspci -vx', eg::
0398
0399 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
0400 Subsystem: 3Com Corporation: Unknown device 9200
0401 Flags: bus master, medium devsel, latency 32, IRQ 19
0402 I/O ports at a400 [size=128]
0403 Memory at db000000 (32-bit, non-prefetchable) [size=128]
0404 Expansion ROM at <unassigned> [disabled] [size=128K]
0405 Capabilities: [dc] Power Management version 2
0406 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
0407 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
0408 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
0409 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
0410
0411 - A description of the environment: 10baseT? 100baseT?
0412 full/half duplex? switched or hubbed?
0413
0414 - Any additional module parameters which you may be providing to the driver.
0415
0416 - Any kernel logs which are produced. The more the merrier.
0417 If this is a large file and you are sending your report to a
0418 mailing list, mention that you have the logfile, but don't send
0419 it. If you're reporting direct to the maintainer then just send
0420 it.
0421
0422 To ensure that all kernel logs are available, add the
0423 following line to /etc/syslog.conf::
0424
0425 kern.* /var/log/messages
0426
0427 Then restart syslogd with::
0428
0429 /etc/rc.d/init.d/syslog restart
0430
0431 (The above may vary, depending upon which Linux distribution you use).
0432
0433 - If your problem is reproducible then that's great. Try the
0434 following:
0435
0436 1) Increase the debug level. Usually this is done via:
0437
0438 a) modprobe driver debug=7
0439 b) In /etc/modprobe.d/driver.conf:
0440 options driver debug=7
0441
0442 2) Recreate the problem with the higher debug level,
0443 send all logs to the maintainer.
0444
0445 3) Download you card's diagnostic tool from Donald
0446 Becker's website <http://www.scyld.com/ethercard_diag.html>.
0447 Download mii-diag.c as well. Build these.
0448
0449 a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
0450 working correctly. Save the output.
0451
0452 b) Run the above commands when the card is malfunctioning. Send
0453 both sets of output.
0454
0455 Finally, please be patient and be prepared to do some work. You may
0456 end up working on this problem for a week or more as the maintainer
0457 asks more questions, asks for more tests, asks for patches to be
0458 applied, etc. At the end of it all, the problem may even remain
0459 unresolved.
