1.. SPDX-License-Identifier: GPL-2.0 2 3========================= 43Com Vortex device driver 5========================= 6 7Andrew Morton 8 930 April 2000 10 11 12This document describes the usage and errata of the 3Com "Vortex" device 13driver for Linux, 3c59x.c. 14 15The driver was written by Donald Becker <becker@scyld.com> 16 17Don is no longer the prime maintainer of this version of the driver. 18Please 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 24Please note the 'Reporting and Diagnosing Problems' section at the end 25of this file. 26 27 28Since kernel 2.3.99-pre6, this driver incorporates the support for the 293c575-series Cardbus cards which used to be handled by 3c575_cb.c. 30 31This 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 72Module parameters 73================= 74 75There are several parameters which may be provided to the driver when 76its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf`` 77configuration files. Example:: 78 79 options 3c59x debug=3 rx_copybreak=300 80 81If you are using the PCMCIA tools (cardmgr) then the options may be 82placed in /etc/pcmcia/config.opts:: 83 84 module "3c59x" opts "debug=3 rx_copybreak=300" 85 86 87The supported parameters are: 88 89debug=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 94options=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 139global_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 145full_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 154global_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 159flow_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 175rx_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 188max_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 197hw_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 224compaq_ioaddr=N, 225compaq_irq=N, 226compaq_device_id=N 227 228 "Variables to work-around the Compaq PCI BIOS32 problem".... 229 230watchdog=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 238enable_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 246global_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 251Media selection 252--------------- 253 254A number of the older NICs such as the 3c590 and 3c900 series have 25510base2 and AUI interfaces. 256 257Prior to January, 2001 this driver would autoselect the 10base2 or AUI 258port if it didn't detect activity on the 10baseT port. It would then 259get stuck on the 10base2 port and a driver reload was necessary to 260switch back to 10baseT. This behaviour could not be prevented with a 261module option override. 262 263Later (current) versions of the driver _do_ support locking of the 264media type. So if you load the driver module with 265 266 modprobe 3c59x options=0 267 268it will permanently select the 10baseT port. Automatic selection of 269other media types does not occur. 270 271 272Transmit error, Tx status register 82 273------------------------------------- 274 275This is a common error which is almost always caused by another host on 276the same network being in full-duplex mode, while this host is in 277half-duplex mode. You need to find that other host and make it run in 278half-duplex mode or fix this host to run in full-duplex mode. 279 280As a last resort, you can force the 3c59x driver into full-duplex mode 281with 282 283 options 3c59x full_duplex=1 284 285but this has to be viewed as a workaround for broken network gear and 286should only really be used for equipment which cannot autonegotiate. 287 288 289Additional resources 290-------------------- 291 292Details of the device driver implementation are at the top of the source file. 293 294Additional documentation is available at Don Becker's Linux Drivers site: 295 296 http://www.scyld.com/vortex.html 297 298Donald Becker's driver development site: 299 300 http://www.scyld.com/network.html 301 302Donald's vortex-diag program is useful for inspecting the NIC's state: 303 304 http://www.scyld.com/ethercard_diag.html 305 306Donald's mii-diag program may be used for inspecting and manipulating 307the NIC's Media Independent Interface subsystem: 308 309 http://www.scyld.com/ethercard_diag.html#mii-diag 310 311Donald's wake-on-LAN page: 312 313 http://www.scyld.com/wakeonlan.html 314 3153Com's DOS-based application for setting up the NICs EEPROMs: 316 317 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe 318 319 320Autonegotiation 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 353Reporting and diagnosing problems 354--------------------------------- 355 356Maintainers find that accurate and complete problem reports are 357invaluable in resolving driver problems. We are frequently not able to 358reproduce problems and must rely on your patience and efforts to get to 359the bottom of the problem. 360 361If you believe you have a driver problem here are some of the 362steps 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 455Finally, please be patient and be prepared to do some work. You may 456end up working on this problem for a week or more as the maintainer 457asks more questions, asks for more tests, asks for patches to be 458applied, etc. At the end of it all, the problem may even remain 459unresolved. 460