]>
Commit | Line | Data |
---|---|---|
1da177e4 | 1 | Documentation/networking/vortex.txt |
e1f8e874 | 2 | Andrew Morton |
1da177e4 LT |
3 | 30 April 2000 |
4 | ||
5 | ||
6 | This document describes the usage and errata of the 3Com "Vortex" device | |
7 | driver for Linux, 3c59x.c. | |
8 | ||
9 | The driver was written by Donald Becker <becker@scyld.com> | |
10 | ||
11 | Don is no longer the prime maintainer of this version of the driver. | |
12 | Please report problems to one or more of: | |
13 | ||
e1f8e874 | 14 | Andrew Morton |
979b6c13 | 15 | Netdev mailing list <netdev@vger.kernel.org> |
1da177e4 LT |
16 | Linux kernel mailing list <linux-kernel@vger.kernel.org> |
17 | ||
18 | Please note the 'Reporting and Diagnosing Problems' section at the end | |
19 | of this file. | |
20 | ||
21 | ||
22 | Since kernel 2.3.99-pre6, this driver incorporates the support for the | |
23 | 3c575-series Cardbus cards which used to be handled by 3c575_cb.c. | |
24 | ||
25 | This driver supports the following hardware: | |
26 | ||
8219dd57 SK |
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 | 3c900 Boomerang 10baseT | |
34 | 3c900 Boomerang 10Mbps Combo | |
35 | 3c900 Cyclone 10Mbps TPO | |
36 | 3c900 Cyclone 10Mbps Combo | |
37 | 3c900 Cyclone 10Mbps TPC | |
38 | 3c900B-FL Cyclone 10base-FL | |
39 | 3c905 Boomerang 100baseTx | |
40 | 3c905 Boomerang 100baseT4 | |
41 | 3c905B Cyclone 100baseTx | |
42 | 3c905B Cyclone 10/100/BNC | |
43 | 3c905B-FX Cyclone 100baseFx | |
44 | 3c905C Tornado | |
45 | 3c920B-EMB-WNM (ATI Radeon 9100 IGP) | |
46 | 3c980 Cyclone | |
47 | 3c980C Python-T | |
48 | 3cSOHO100-TX Hurricane | |
49 | 3c555 Laptop Hurricane | |
50 | 3c556 Laptop Tornado | |
51 | 3c556B Laptop Hurricane | |
52 | 3c575 [Megahertz] 10/100 LAN CardBus | |
53 | 3c575 Boomerang CardBus | |
54 | 3CCFE575BT Cyclone CardBus | |
55 | 3CCFE575CT Tornado CardBus | |
56 | 3CCFE656 Cyclone CardBus | |
57 | 3CCFEM656B Cyclone+Winmodem CardBus | |
58 | 3CXFEM656C Tornado+Winmodem CardBus | |
59 | 3c450 HomePNA Tornado | |
60 | 3c920 Tornado | |
61 | 3c982 Hydra Dual Port A | |
62 | 3c982 Hydra Dual Port B | |
63 | 3c905B-T4 | |
64 | 3c920B-EMB-WNM Tornado | |
1da177e4 LT |
65 | |
66 | Module parameters | |
67 | ================= | |
68 | ||
69 | There are several parameters which may be provided to the driver when | |
970e2486 | 70 | its module is loaded. These are usually placed in /etc/modprobe.d/*.conf |
c17cb8b5 | 71 | configuration files. Example: |
1da177e4 LT |
72 | |
73 | options 3c59x debug=3 rx_copybreak=300 | |
74 | ||
75 | If you are using the PCMCIA tools (cardmgr) then the options may be | |
76 | placed in /etc/pcmcia/config.opts: | |
77 | ||
78 | module "3c59x" opts "debug=3 rx_copybreak=300" | |
79 | ||
80 | ||
81 | The supported parameters are: | |
82 | ||
83 | debug=N | |
84 | ||
85 | Where N is a number from 0 to 7. Anything above 3 produces a lot | |
86 | of output in your system logs. debug=1 is default. | |
87 | ||
88 | options=N1,N2,N3,... | |
89 | ||
90 | Each number in the list provides an option to the corresponding | |
91 | network card. So if you have two 3c905's and you wish to provide | |
92 | them with option 0x204 you would use: | |
93 | ||
94 | options=0x204,0x204 | |
95 | ||
96 | The individual options are composed of a number of bitfields which | |
97 | have the following meanings: | |
98 | ||
99 | Possible media type settings | |
100 | 0 10baseT | |
101 | 1 10Mbs AUI | |
102 | 2 undefined | |
103 | 3 10base2 (BNC) | |
104 | 4 100base-TX | |
105 | 5 100base-FX | |
106 | 6 MII (Media Independent Interface) | |
107 | 7 Use default setting from EEPROM | |
108 | 8 Autonegotiate | |
109 | 9 External MII | |
110 | 10 Use default setting from EEPROM | |
111 | ||
112 | When generating a value for the 'options' setting, the above media | |
113 | selection values may be OR'ed (or added to) the following: | |
114 | ||
115 | 0x8000 Set driver debugging level to 7 | |
116 | 0x4000 Set driver debugging level to 2 | |
117 | 0x0400 Enable Wake-on-LAN | |
118 | 0x0200 Force full duplex mode. | |
119 | 0x0010 Bus-master enable bit (Old Vortex cards only) | |
120 | ||
121 | For example: | |
122 | ||
123 | insmod 3c59x options=0x204 | |
124 | ||
125 | will force full-duplex 100base-TX, rather than allowing the usual | |
126 | autonegotiation. | |
127 | ||
128 | global_options=N | |
129 | ||
130 | Sets the `options' parameter for all 3c59x NICs in the machine. | |
131 | Entries in the `options' array above will override any setting of | |
132 | this. | |
133 | ||
134 | full_duplex=N1,N2,N3... | |
135 | ||
136 | Similar to bit 9 of 'options'. Forces the corresponding card into | |
137 | full-duplex mode. Please use this in preference to the `options' | |
138 | parameter. | |
139 | ||
140 | In fact, please don't use this at all! You're better off getting | |
141 | autonegotiation working properly. | |
142 | ||
143 | global_full_duplex=N1 | |
144 | ||
145 | Sets full duplex mode for all 3c59x NICs in the machine. Entries | |
146 | in the `full_duplex' array above will override any setting of this. | |
147 | ||
148 | flow_ctrl=N1,N2,N3... | |
149 | ||
150 | Use 802.3x MAC-layer flow control. The 3com cards only support the | |
151 | PAUSE command, which means that they will stop sending packets for a | |
152 | short period if they receive a PAUSE frame from the link partner. | |
153 | ||
154 | The driver only allows flow control on a link which is operating in | |
155 | full duplex mode. | |
156 | ||
157 | This feature does not appear to work on the 3c905 - only 3c905B and | |
158 | 3c905C have been tested. | |
159 | ||
160 | The 3com cards appear to only respond to PAUSE frames which are | |
161 | sent to the reserved destination address of 01:80:c2:00:00:01. They | |
162 | do not honour PAUSE frames which are sent to the station MAC address. | |
163 | ||
164 | rx_copybreak=M | |
165 | ||
166 | The driver preallocates 32 full-sized (1536 byte) network buffers | |
167 | for receiving. When a packet arrives, the driver has to decide | |
168 | whether to leave the packet in its full-sized buffer, or to allocate | |
169 | a smaller buffer and copy the packet across into it. | |
170 | ||
171 | This is a speed/space tradeoff. | |
172 | ||
173 | The value of rx_copybreak is used to decide when to make the copy. | |
174 | If the packet size is less than rx_copybreak, the packet is copied. | |
175 | The default value for rx_copybreak is 200 bytes. | |
176 | ||
177 | max_interrupt_work=N | |
178 | ||
179 | The driver's interrupt service routine can handle many receive and | |
180 | transmit packets in a single invocation. It does this in a loop. | |
c17cb8b5 | 181 | The value of max_interrupt_work governs how many times the interrupt |
1da177e4 LT |
182 | service routine will loop. The default value is 32 loops. If this |
183 | is exceeded the interrupt service routine gives up and generates a | |
184 | warning message "eth0: Too much work in interrupt". | |
185 | ||
186 | hw_checksums=N1,N2,N3,... | |
187 | ||
188 | Recent 3com NICs are able to generate IPv4, TCP and UDP checksums | |
189 | in hardware. Linux has used the Rx checksumming for a long time. | |
190 | The "zero copy" patch which is planned for the 2.4 kernel series | |
191 | allows you to make use of the NIC's DMA scatter/gather and transmit | |
192 | checksumming as well. | |
193 | ||
194 | The driver is set up so that, when the zerocopy patch is applied, | |
195 | all Tornado and Cyclone devices will use S/G and Tx checksums. | |
196 | ||
197 | This module parameter has been provided so you can override this | |
198 | decision. If you think that Tx checksums are causing a problem, you | |
199 | may disable the feature with `hw_checksums=0'. | |
200 | ||
201 | If you think your NIC should be performing Tx checksumming and the | |
202 | driver isn't enabling it, you can force the use of hardware Tx | |
203 | checksumming with `hw_checksums=1'. | |
204 | ||
205 | The driver drops a message in the logfiles to indicate whether or | |
206 | not it is using hardware scatter/gather and hardware Tx checksums. | |
207 | ||
208 | Scatter/gather and hardware checksums provide considerable | |
209 | performance improvement for the sendfile() system call, but a small | |
210 | decrease in throughput for send(). There is no effect upon receive | |
211 | efficiency. | |
212 | ||
213 | compaq_ioaddr=N | |
214 | compaq_irq=N | |
215 | compaq_device_id=N | |
216 | ||
217 | "Variables to work-around the Compaq PCI BIOS32 problem".... | |
218 | ||
219 | watchdog=N | |
220 | ||
221 | Sets the time duration (in milliseconds) after which the kernel | |
222 | decides that the transmitter has become stuck and needs to be reset. | |
223 | This is mainly for debugging purposes, although it may be advantageous | |
224 | to increase this value on LANs which have very high collision rates. | |
225 | The default value is 5000 (5.0 seconds). | |
226 | ||
227 | enable_wol=N1,N2,N3,... | |
228 | ||
229 | Enable Wake-on-LAN support for the relevant interface. Donald | |
230 | Becker's `ether-wake' application may be used to wake suspended | |
231 | machines. | |
232 | ||
233 | Also enables the NIC's power management support. | |
234 | ||
235 | global_enable_wol=N | |
236 | ||
237 | Sets enable_wol mode for all 3c59x NICs in the machine. Entries in | |
238 | the `enable_wol' array above will override any setting of this. | |
239 | ||
240 | Media selection | |
241 | --------------- | |
242 | ||
243 | A number of the older NICs such as the 3c590 and 3c900 series have | |
244 | 10base2 and AUI interfaces. | |
245 | ||
246 | Prior to January, 2001 this driver would autoeselect the 10base2 or AUI | |
247 | port if it didn't detect activity on the 10baseT port. It would then | |
248 | get stuck on the 10base2 port and a driver reload was necessary to | |
249 | switch back to 10baseT. This behaviour could not be prevented with a | |
250 | module option override. | |
251 | ||
252 | Later (current) versions of the driver _do_ support locking of the | |
253 | media type. So if you load the driver module with | |
254 | ||
255 | modprobe 3c59x options=0 | |
256 | ||
257 | it will permanently select the 10baseT port. Automatic selection of | |
258 | other media types does not occur. | |
259 | ||
260 | ||
261 | Transmit error, Tx status register 82 | |
262 | ------------------------------------- | |
263 | ||
264 | This is a common error which is almost always caused by another host on | |
265 | the same network being in full-duplex mode, while this host is in | |
266 | half-duplex mode. You need to find that other host and make it run in | |
267 | half-duplex mode or fix this host to run in full-duplex mode. | |
268 | ||
269 | As a last resort, you can force the 3c59x driver into full-duplex mode | |
270 | with | |
271 | ||
272 | options 3c59x full_duplex=1 | |
273 | ||
274 | but this has to be viewed as a workaround for broken network gear and | |
275 | should only really be used for equipment which cannot autonegotiate. | |
276 | ||
277 | ||
278 | Additional resources | |
279 | -------------------- | |
280 | ||
281 | Details of the device driver implementation are at the top of the source file. | |
282 | ||
283 | Additional documentation is available at Don Becker's Linux Drivers site: | |
284 | ||
98766fbe | 285 | http://www.scyld.com/vortex.html |
1da177e4 LT |
286 | |
287 | Donald Becker's driver development site: | |
288 | ||
98766fbe | 289 | http://www.scyld.com/network.html |
1da177e4 LT |
290 | |
291 | Donald's vortex-diag program is useful for inspecting the NIC's state: | |
292 | ||
98766fbe | 293 | http://www.scyld.com/ethercard_diag.html |
1da177e4 LT |
294 | |
295 | Donald's mii-diag program may be used for inspecting and manipulating | |
296 | the NIC's Media Independent Interface subsystem: | |
297 | ||
98766fbe | 298 | http://www.scyld.com/ethercard_diag.html#mii-diag |
1da177e4 LT |
299 | |
300 | Donald's wake-on-LAN page: | |
301 | ||
98766fbe | 302 | http://www.scyld.com/wakeonlan.html |
1da177e4 | 303 | |
1da177e4 LT |
304 | 3Com's DOS-based application for setting up the NICs EEPROMs: |
305 | ||
306 | ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe | |
307 | ||
1da177e4 LT |
308 | |
309 | Autonegotiation notes | |
310 | --------------------- | |
311 | ||
312 | The driver uses a one-minute heartbeat for adapting to changes in | |
8219dd57 SK |
313 | the external LAN environment if link is up and 5 seconds if link is down. |
314 | This means that when, for example, a machine is unplugged from a hubbed | |
315 | 10baseT LAN plugged into a switched 100baseT LAN, the throughput | |
316 | will be quite dreadful for up to sixty seconds. Be patient. | |
1da177e4 LT |
317 | |
318 | Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>: | |
319 | ||
320 | On a side note, adding HAS_NWAY seems to share a problem with the | |
321 | Cisco 6509 switch. Specifically, you need to change the spanning | |
322 | tree parameter for the port the machine is plugged into to 'portfast' | |
323 | mode. Otherwise, the negotiation fails. This has been an issue | |
324 | we've noticed for a while but haven't had the time to track down. | |
325 | ||
326 | Cisco switches (Jeff Busch <jbusch@deja.com>) | |
327 | ||
328 | My "standard config" for ports to which PC's/servers connect directly: | |
329 | ||
330 | interface FastEthernet0/N | |
331 | description machinename | |
332 | load-interval 30 | |
333 | spanning-tree portfast | |
334 | ||
335 | If autonegotiation is a problem, you may need to specify "speed | |
336 | 100" and "duplex full" as well (or "speed 10" and "duplex half"). | |
337 | ||
338 | WARNING: DO NOT hook up hubs/switches/bridges to these | |
339 | specially-configured ports! The switch will become very confused. | |
340 | ||
341 | ||
342 | Reporting and diagnosing problems | |
343 | --------------------------------- | |
344 | ||
345 | Maintainers find that accurate and complete problem reports are | |
346 | invaluable in resolving driver problems. We are frequently not able to | |
347 | reproduce problems and must rely on your patience and efforts to get to | |
348 | the bottom of the problem. | |
349 | ||
350 | If you believe you have a driver problem here are some of the | |
351 | steps you should take: | |
352 | ||
353 | - Is it really a driver problem? | |
354 | ||
355 | Eliminate some variables: try different cards, different | |
356 | computers, different cables, different ports on the switch/hub, | |
992caacf | 357 | different versions of the kernel or of the driver, etc. |
1da177e4 LT |
358 | |
359 | - OK, it's a driver problem. | |
360 | ||
361 | You need to generate a report. Typically this is an email to the | |
b78ba72c | 362 | maintainer and/or netdev@vger.kernel.org. The maintainer's |
992caacf | 363 | email address will be in the driver source or in the MAINTAINERS file. |
1da177e4 LT |
364 | |
365 | - The contents of your report will vary a lot depending upon the | |
366 | problem. If it's a kernel crash then you should refer to the | |
367 | REPORTING-BUGS file. | |
368 | ||
369 | But for most problems it is useful to provide the following: | |
370 | ||
371 | o Kernel version, driver version | |
372 | ||
373 | o A copy of the banner message which the driver generates when | |
374 | it is initialised. For example: | |
375 | ||
376 | eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19 | |
377 | 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface. | |
378 | MII transceiver found at address 24, status 782d. | |
379 | Enabling bus-master transmits and whole-frame receives. | |
380 | ||
381 | NOTE: You must provide the `debug=2' modprobe option to generate | |
382 | a full detection message. Please do this: | |
383 | ||
384 | modprobe 3c59x debug=2 | |
385 | ||
386 | o If it is a PCI device, the relevant output from 'lspci -vx', eg: | |
387 | ||
388 | 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74) | |
389 | Subsystem: 3Com Corporation: Unknown device 9200 | |
390 | Flags: bus master, medium devsel, latency 32, IRQ 19 | |
391 | I/O ports at a400 [size=128] | |
392 | Memory at db000000 (32-bit, non-prefetchable) [size=128] | |
393 | Expansion ROM at <unassigned> [disabled] [size=128K] | |
394 | Capabilities: [dc] Power Management version 2 | |
395 | 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00 | |
396 | 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00 | |
397 | 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10 | |
398 | 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a | |
399 | ||
400 | o A description of the environment: 10baseT? 100baseT? | |
401 | full/half duplex? switched or hubbed? | |
402 | ||
403 | o Any additional module parameters which you may be providing to the driver. | |
404 | ||
405 | o Any kernel logs which are produced. The more the merrier. | |
406 | If this is a large file and you are sending your report to a | |
407 | mailing list, mention that you have the logfile, but don't send | |
408 | it. If you're reporting direct to the maintainer then just send | |
409 | it. | |
410 | ||
411 | To ensure that all kernel logs are available, add the | |
412 | following line to /etc/syslog.conf: | |
413 | ||
414 | kern.* /var/log/messages | |
415 | ||
416 | Then restart syslogd with: | |
417 | ||
418 | /etc/rc.d/init.d/syslog restart | |
419 | ||
420 | (The above may vary, depending upon which Linux distribution you use). | |
421 | ||
422 | o If your problem is reproducible then that's great. Try the | |
423 | following: | |
424 | ||
425 | 1) Increase the debug level. Usually this is done via: | |
426 | ||
427 | a) modprobe driver debug=7 | |
970e2486 | 428 | b) In /etc/modprobe.d/driver.conf: |
1da177e4 LT |
429 | options driver debug=7 |
430 | ||
431 | 2) Recreate the problem with the higher debug level, | |
432 | send all logs to the maintainer. | |
433 | ||
434 | 3) Download you card's diagnostic tool from Donald | |
98766fbe RD |
435 | Becker's website <http://www.scyld.com/ethercard_diag.html>. |
436 | Download mii-diag.c as well. Build these. | |
1da177e4 LT |
437 | |
438 | a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is | |
439 | working correctly. Save the output. | |
440 | ||
441 | b) Run the above commands when the card is malfunctioning. Send | |
442 | both sets of output. | |
443 | ||
98766fbe RD |
444 | Finally, please be patient and be prepared to do some work. You may |
445 | end up working on this problem for a week or more as the maintainer | |
446 | asks more questions, asks for more tests, asks for patches to be | |
447 | applied, etc. At the end of it all, the problem may even remain | |
448 | unresolved. |