| 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 <[email protected]> |
| 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 <[email protected]> |
| 22 |
- Linux kernel mailing list <[email protected]> |
| 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 autoselect 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 <[email protected]>: |
| 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 <[email protected]>) |
| 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 [email protected]. 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. |