1Documentation/networking/vortex.txt 2Andrew Morton <andrewm@uow.edu.au> 330 April 2000 4 5 6This document describes the usage and errata of the 3Com "Vortex" device 7driver for Linux, 3c59x.c. 8 9The driver was written by Donald Becker <becker@scyld.com> 10 11Don is no longer the prime maintainer of this version of the driver. 12Please 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 18Please note the 'Reporting and Diagnosing Problems' section at the end 19of this file. 20 21 22Since kernel 2.3.99-pre6, this driver incorporates the support for the 233c575-series Cardbus cards which used to be handled by 3c575_cb.c. 24 25This 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 58Module parameters 59================= 60 61There are several parameters which may be provided to the driver when 62its module is loaded. These are usually placed in /etc/modules.conf 63(used to be conf.modules). Example: 64 65options 3c59x debug=3 rx_copybreak=300 66 67If you are using the PCMCIA tools (cardmgr) then the options may be 68placed in /etc/pcmcia/config.opts: 69 70module "3c59x" opts "debug=3 rx_copybreak=300" 71 72 73The supported parameters are: 74 75debug=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 80options=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 120global_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 126full_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 135global_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 140flow_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 156rx_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 169max_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 178hw_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 205compaq_ioaddr=N 206compaq_irq=N 207compaq_device_id=N 208 209 "Variables to work-around the Compaq PCI BIOS32 problem".... 210 211watchdog=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 219enable_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 227global_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 232Media selection 233--------------- 234 235A number of the older NICs such as the 3c590 and 3c900 series have 23610base2 and AUI interfaces. 237 238Prior to January, 2001 this driver would autoeselect the 10base2 or AUI 239port if it didn't detect activity on the 10baseT port. It would then 240get stuck on the 10base2 port and a driver reload was necessary to 241switch back to 10baseT. This behaviour could not be prevented with a 242module option override. 243 244Later (current) versions of the driver _do_ support locking of the 245media type. So if you load the driver module with 246 247 modprobe 3c59x options=0 248 249it will permanently select the 10baseT port. Automatic selection of 250other media types does not occur. 251 252 253Transmit error, Tx status register 82 254------------------------------------- 255 256This is a common error which is almost always caused by another host on 257the same network being in full-duplex mode, while this host is in 258half-duplex mode. You need to find that other host and make it run in 259half-duplex mode or fix this host to run in full-duplex mode. 260 261As a last resort, you can force the 3c59x driver into full-duplex mode 262with 263 264 options 3c59x full_duplex=1 265 266but this has to be viewed as a workaround for broken network gear and 267should only really be used for equipment which cannot autonegotiate. 268 269 270Additional resources 271-------------------- 272 273Details of the device driver implementation are at the top of the source file. 274 275Additional documentation is available at Don Becker's Linux Drivers site: 276 277 http://www.scyld.com/network/vortex.html 278 279Donald Becker's driver development site: 280 281 http://www.scyld.com/network 282 283Donald's vortex-diag program is useful for inspecting the NIC's state: 284 285 http://www.scyld.com/diag/#pci-diags 286 287Donald's mii-diag program may be used for inspecting and manipulating 288the NIC's Media Independent Interface subsystem: 289 290 http://www.scyld.com/diag/#mii-diag 291 292Donald's wake-on-LAN page: 293 294 http://www.scyld.com/expert/wake-on-lan.html 295 2963Com's documentation for many NICs, including the ones supported by 297this driver is available at 298 299 http://support.3com.com/partners/developer/developer_form.html 300 3013Com's DOS-based application for setting up the NICs EEPROMs: 302 303 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe 304 305Driver updates and a detailed changelog for the modifications which 306were 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 311Autonegotiation 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 344Reporting and diagnosing problems 345--------------------------------- 346 347Maintainers find that accurate and complete problem reports are 348invaluable in resolving driver problems. We are frequently not able to 349reproduce problems and must rely on your patience and efforts to get to 350the bottom of the problem. 351 352If you believe you have a driver problem here are some of the 353steps 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.o debug=7 430 b) In /etc/conf.modules (or modules.conf): 431 options driver_name 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 446Finally, please be patient and be prepared to do some work. You may end up working on 447this problem for a week or more as the maintainer asks more questions, asks for more 448tests, asks for patches to be applied, etc. At the end of it all, the problem may even 449remain unresolved. 450 451