Commit | Line | Data |
---|---|---|
9ea2af8d MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ========================= | |
4 | 3Com Vortex device driver | |
5 | ========================= | |
6 | ||
e1f8e874 | 7 | Andrew Morton |
9ea2af8d | 8 | |
1da177e4 LT |
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 | ||
9ea2af8d | 17 | Don is no longer the prime maintainer of this version of the driver. |
1da177e4 LT |
18 | Please report problems to one or more of: |
19 | ||
9ea2af8d MCC |
20 | - Andrew Morton |
21 | - Netdev mailing list <netdev@vger.kernel.org> | |
22 | - Linux kernel mailing list <linux-kernel@vger.kernel.org> | |
1da177e4 LT |
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 | ||
9ea2af8d MCC |
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 | |
1da177e4 LT |
71 | |
72 | Module parameters | |
73 | ================= | |
74 | ||
75 | There are several parameters which may be provided to the driver when | |
9ea2af8d MCC |
76 | its module is loaded. These are usually placed in ``/etc/modprobe.d/*.conf`` |
77 | configuration files. Example:: | |
1da177e4 | 78 | |
9ea2af8d | 79 | options 3c59x debug=3 rx_copybreak=300 |
1da177e4 LT |
80 | |
81 | If you are using the PCMCIA tools (cardmgr) then the options may be | |
9ea2af8d | 82 | placed in /etc/pcmcia/config.opts:: |
1da177e4 | 83 | |
9ea2af8d | 84 | module "3c59x" opts "debug=3 rx_copybreak=300" |
1da177e4 LT |
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 | |
9ea2af8d | 98 | them with option 0x204 you would use:: |
1da177e4 LT |
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 | |
9ea2af8d MCC |
106 | |
107 | == ================================= | |
1da177e4 LT |
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 | |
9ea2af8d | 119 | == ================================= |
1da177e4 LT |
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 | ||
9ea2af8d | 124 | ====== ============================================= |
1da177e4 LT |
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) | |
9ea2af8d | 130 | ====== ============================================= |
1da177e4 | 131 | |
9ea2af8d | 132 | For example:: |
1da177e4 LT |
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 | ||
9ea2af8d MCC |
141 | Sets the ``options`` parameter for all 3c59x NICs in the machine. |
142 | Entries in the ``options`` array above will override any setting of | |
1da177e4 LT |
143 | this. |
144 | ||
145 | full_duplex=N1,N2,N3... | |
146 | ||
147 | Similar to bit 9 of 'options'. Forces the corresponding card into | |
9ea2af8d | 148 | full-duplex mode. Please use this in preference to the ``options`` |
1da177e4 LT |
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 | |
9ea2af8d | 157 | in the ``full_duplex`` array above will override any setting of this. |
1da177e4 LT |
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 | |
9ea2af8d | 163 | short period if they receive a PAUSE frame from the link partner. |
1da177e4 LT |
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 | ||
9ea2af8d MCC |
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. | |
1da177e4 LT |
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 | |
9ea2af8d | 191 | transmit packets in a single invocation. It does this in a loop. |
c17cb8b5 | 192 | The value of max_interrupt_work governs how many times the interrupt |
1da177e4 LT |
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 | |
9ea2af8d | 200 | in hardware. Linux has used the Rx checksumming for a long time. |
1da177e4 LT |
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 | |
9ea2af8d | 210 | may disable the feature with ``hw_checksums=0``. |
1da177e4 LT |
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 | |
9ea2af8d | 214 | checksumming with ``hw_checksums=1``. |
1da177e4 LT |
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 | ||
9ea2af8d MCC |
224 | compaq_ioaddr=N, |
225 | compaq_irq=N, | |
1da177e4 LT |
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 | |
9ea2af8d | 233 | decides that the transmitter has become stuck and needs to be reset. |
1da177e4 LT |
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 | |
9ea2af8d | 241 | Becker's ``ether-wake`` application may be used to wake suspended |
1da177e4 LT |
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 | |
9ea2af8d | 249 | the ``enable_wol`` array above will override any setting of this. |
1da177e4 LT |
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 | ||
a266ef69 | 257 | Prior to January, 2001 this driver would autoselect the 10base2 or AUI |
1da177e4 LT |
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 | ||
98766fbe | 296 | http://www.scyld.com/vortex.html |
1da177e4 LT |
297 | |
298 | Donald Becker's driver development site: | |
299 | ||
98766fbe | 300 | http://www.scyld.com/network.html |
1da177e4 LT |
301 | |
302 | Donald's vortex-diag program is useful for inspecting the NIC's state: | |
303 | ||
98766fbe | 304 | http://www.scyld.com/ethercard_diag.html |
1da177e4 LT |
305 | |
306 | Donald's mii-diag program may be used for inspecting and manipulating | |
307 | the NIC's Media Independent Interface subsystem: | |
308 | ||
98766fbe | 309 | http://www.scyld.com/ethercard_diag.html#mii-diag |
1da177e4 LT |
310 | |
311 | Donald's wake-on-LAN page: | |
312 | ||
98766fbe | 313 | http://www.scyld.com/wakeonlan.html |
1da177e4 | 314 | |
1da177e4 LT |
315 | 3Com's DOS-based application for setting up the NICs EEPROMs: |
316 | ||
317 | ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe | |
318 | ||
1da177e4 LT |
319 | |
320 | Autonegotiation notes | |
321 | --------------------- | |
322 | ||
323 | The driver uses a one-minute heartbeat for adapting to changes in | |
8219dd57 SK |
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. | |
1da177e4 LT |
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 | ||
9ea2af8d | 339 | My "standard config" for ports to which PC's/servers connect directly:: |
1da177e4 | 340 | |
9ea2af8d MCC |
341 | interface FastEthernet0/N |
342 | description machinename | |
343 | load-interval 30 | |
344 | spanning-tree portfast | |
1da177e4 LT |
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, | |
992caacf | 368 | different versions of the kernel or of the driver, etc. |
1da177e4 LT |
369 | |
370 | - OK, it's a driver problem. | |
371 | ||
372 | You need to generate a report. Typically this is an email to the | |
b78ba72c | 373 | maintainer and/or netdev@vger.kernel.org. The maintainer's |
992caacf | 374 | email address will be in the driver source or in the MAINTAINERS file. |
1da177e4 LT |
375 | |
376 | - The contents of your report will vary a lot depending upon the | |
da514157 TL |
377 | problem. If it's a kernel crash then you should refer to |
378 | 'Documentation/admin-guide/reporting-issues.rst'. | |
1da177e4 LT |
379 | |
380 | But for most problems it is useful to provide the following: | |
381 | ||
9ea2af8d | 382 | - Kernel version, driver version |
1da177e4 | 383 | |
9ea2af8d | 384 | - A copy of the banner message which the driver generates when |
1da177e4 LT |
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 | ||
9ea2af8d MCC |
392 | NOTE: You must provide the ``debug=2`` modprobe option to generate |
393 | a full detection message. Please do this:: | |
1da177e4 LT |
394 | |
395 | modprobe 3c59x debug=2 | |
396 | ||
9ea2af8d MCC |
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? | |
1da177e4 LT |
412 | full/half duplex? switched or hubbed? |
413 | ||
9ea2af8d | 414 | - Any additional module parameters which you may be providing to the driver. |
1da177e4 | 415 | |
9ea2af8d | 416 | - Any kernel logs which are produced. The more the merrier. |
1da177e4 LT |
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 | |
9ea2af8d | 423 | following line to /etc/syslog.conf:: |
1da177e4 | 424 | |
9ea2af8d | 425 | kern.* /var/log/messages |
1da177e4 | 426 | |
9ea2af8d | 427 | Then restart syslogd with:: |
1da177e4 | 428 | |
9ea2af8d | 429 | /etc/rc.d/init.d/syslog restart |
1da177e4 LT |
430 | |
431 | (The above may vary, depending upon which Linux distribution you use). | |
432 | ||
9ea2af8d | 433 | - If your problem is reproducible then that's great. Try the |
1da177e4 LT |
434 | following: |
435 | ||
436 | 1) Increase the debug level. Usually this is done via: | |
437 | ||
9ea2af8d MCC |
438 | a) modprobe driver debug=7 |
439 | b) In /etc/modprobe.d/driver.conf: | |
440 | options driver debug=7 | |
1da177e4 LT |
441 | |
442 | 2) Recreate the problem with the higher debug level, | |
9ea2af8d | 443 | send all logs to the maintainer. |
1da177e4 LT |
444 | |
445 | 3) Download you card's diagnostic tool from Donald | |
9ea2af8d MCC |
446 | Becker's website <http://www.scyld.com/ethercard_diag.html>. |
447 | Download mii-diag.c as well. Build these. | |
1da177e4 | 448 | |
9ea2af8d MCC |
449 | a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is |
450 | working correctly. Save the output. | |
1da177e4 | 451 | |
9ea2af8d MCC |
452 | b) Run the above commands when the card is malfunctioning. Send |
453 | both sets of output. | |
1da177e4 | 454 | |
98766fbe RD |
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. |