blob: 6356d3faed365634bbbe85172b28abdf472c600b [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Documentation/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
Randy Dunlap98766fb2005-11-21 21:32:31 -080014 Andrew Morton <akpm@osdl.org>
Ralf Baechle979b6c12005-06-13 14:30:40 -070015 Netdev mailing list <netdev@vger.kernel.org>
Linus Torvalds1da177e2005-04-16 15:20:36 -070016 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
Steffen Klassert8219dd52006-03-26 01:37:44 -080027 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070065
66Module parameters
67=================
68
69There are several parameters which may be provided to the driver when
70its module is loaded. These are usually placed in /etc/modprobe.conf
71(/etc/modules.conf in 2.4). Example:
72
73options 3c59x debug=3 rx_copybreak=300
74
75If you are using the PCMCIA tools (cardmgr) then the options may be
76placed in /etc/pcmcia/config.opts:
77
78module "3c59x" opts "debug=3 rx_copybreak=300"
79
80
81The supported parameters are:
82
83debug=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
88options=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
128global_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
134full_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
143global_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
148flow_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
164rx_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
177max_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.
181 The value of max_interrupt_work governs how mnay times the interrupt
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
186hw_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
213compaq_ioaddr=N
214compaq_irq=N
215compaq_device_id=N
216
217 "Variables to work-around the Compaq PCI BIOS32 problem"....
218
219watchdog=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
227enable_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
235global_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
240Media selection
241---------------
242
243A number of the older NICs such as the 3c590 and 3c900 series have
24410base2 and AUI interfaces.
245
246Prior to January, 2001 this driver would autoeselect the 10base2 or AUI
247port if it didn't detect activity on the 10baseT port. It would then
248get stuck on the 10base2 port and a driver reload was necessary to
249switch back to 10baseT. This behaviour could not be prevented with a
250module option override.
251
252Later (current) versions of the driver _do_ support locking of the
253media type. So if you load the driver module with
254
255 modprobe 3c59x options=0
256
257it will permanently select the 10baseT port. Automatic selection of
258other media types does not occur.
259
260
261Transmit error, Tx status register 82
262-------------------------------------
263
264This is a common error which is almost always caused by another host on
265the same network being in full-duplex mode, while this host is in
266half-duplex mode. You need to find that other host and make it run in
267half-duplex mode or fix this host to run in full-duplex mode.
268
269As a last resort, you can force the 3c59x driver into full-duplex mode
270with
271
272 options 3c59x full_duplex=1
273
274but this has to be viewed as a workaround for broken network gear and
275should only really be used for equipment which cannot autonegotiate.
276
277
278Additional resources
279--------------------
280
281Details of the device driver implementation are at the top of the source file.
282
283Additional documentation is available at Don Becker's Linux Drivers site:
284
Randy Dunlap98766fb2005-11-21 21:32:31 -0800285 http://www.scyld.com/vortex.html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700286
287Donald Becker's driver development site:
288
Randy Dunlap98766fb2005-11-21 21:32:31 -0800289 http://www.scyld.com/network.html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290
291Donald's vortex-diag program is useful for inspecting the NIC's state:
292
Randy Dunlap98766fb2005-11-21 21:32:31 -0800293 http://www.scyld.com/ethercard_diag.html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700294
295Donald's mii-diag program may be used for inspecting and manipulating
296the NIC's Media Independent Interface subsystem:
297
Randy Dunlap98766fb2005-11-21 21:32:31 -0800298 http://www.scyld.com/ethercard_diag.html#mii-diag
Linus Torvalds1da177e2005-04-16 15:20:36 -0700299
300Donald's wake-on-LAN page:
301
Randy Dunlap98766fb2005-11-21 21:32:31 -0800302 http://www.scyld.com/wakeonlan.html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700303
Linus Torvalds1da177e2005-04-16 15:20:36 -07003043Com's DOS-based application for setting up the NICs EEPROMs:
305
306 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
307
308Driver updates and a detailed changelog for the modifications which
309were made for the 2.3/2,4 series kernel is available at
310
Randy Dunlap98766fb2005-11-21 21:32:31 -0800311 http://www.zip.com.au/~akpm/linux/#3c59x-bc
Linus Torvalds1da177e2005-04-16 15:20:36 -0700312
313
314Autonegotiation notes
315---------------------
316
317 The driver uses a one-minute heartbeat for adapting to changes in
Steffen Klassert8219dd52006-03-26 01:37:44 -0800318 the external LAN environment if link is up and 5 seconds if link is down.
319 This means that when, for example, a machine is unplugged from a hubbed
320 10baseT LAN plugged into a switched 100baseT LAN, the throughput
321 will be quite dreadful for up to sixty seconds. Be patient.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700322
323 Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
324
325 On a side note, adding HAS_NWAY seems to share a problem with the
326 Cisco 6509 switch. Specifically, you need to change the spanning
327 tree parameter for the port the machine is plugged into to 'portfast'
328 mode. Otherwise, the negotiation fails. This has been an issue
329 we've noticed for a while but haven't had the time to track down.
330
331 Cisco switches (Jeff Busch <jbusch@deja.com>)
332
333 My "standard config" for ports to which PC's/servers connect directly:
334
335 interface FastEthernet0/N
336 description machinename
337 load-interval 30
338 spanning-tree portfast
339
340 If autonegotiation is a problem, you may need to specify "speed
341 100" and "duplex full" as well (or "speed 10" and "duplex half").
342
343 WARNING: DO NOT hook up hubs/switches/bridges to these
344 specially-configured ports! The switch will become very confused.
345
346
347Reporting and diagnosing problems
348---------------------------------
349
350Maintainers find that accurate and complete problem reports are
351invaluable in resolving driver problems. We are frequently not able to
352reproduce problems and must rely on your patience and efforts to get to
353the bottom of the problem.
354
355If you believe you have a driver problem here are some of the
356steps you should take:
357
358- Is it really a driver problem?
359
360 Eliminate some variables: try different cards, different
361 computers, different cables, different ports on the switch/hub,
Matt LaPlante992caac2006-10-03 22:52:05 +0200362 different versions of the kernel or of the driver, etc.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700363
364- OK, it's a driver problem.
365
366 You need to generate a report. Typically this is an email to the
367 maintainer and/or linux-net@vger.kernel.org. The maintainer's
Matt LaPlante992caac2006-10-03 22:52:05 +0200368 email address will be in the driver source or in the MAINTAINERS file.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700369
370- The contents of your report will vary a lot depending upon the
371 problem. If it's a kernel crash then you should refer to the
372 REPORTING-BUGS file.
373
374 But for most problems it is useful to provide the following:
375
376 o Kernel version, driver version
377
378 o A copy of the banner message which the driver generates when
379 it is initialised. For example:
380
381 eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19
382 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
383 MII transceiver found at address 24, status 782d.
384 Enabling bus-master transmits and whole-frame receives.
385
386 NOTE: You must provide the `debug=2' modprobe option to generate
387 a full detection message. Please do this:
388
389 modprobe 3c59x debug=2
390
391 o If it is a PCI device, the relevant output from 'lspci -vx', eg:
392
393 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
394 Subsystem: 3Com Corporation: Unknown device 9200
395 Flags: bus master, medium devsel, latency 32, IRQ 19
396 I/O ports at a400 [size=128]
397 Memory at db000000 (32-bit, non-prefetchable) [size=128]
398 Expansion ROM at <unassigned> [disabled] [size=128K]
399 Capabilities: [dc] Power Management version 2
400 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
401 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
402 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
403 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
404
405 o A description of the environment: 10baseT? 100baseT?
406 full/half duplex? switched or hubbed?
407
408 o Any additional module parameters which you may be providing to the driver.
409
410 o Any kernel logs which are produced. The more the merrier.
411 If this is a large file and you are sending your report to a
412 mailing list, mention that you have the logfile, but don't send
413 it. If you're reporting direct to the maintainer then just send
414 it.
415
416 To ensure that all kernel logs are available, add the
417 following line to /etc/syslog.conf:
418
419 kern.* /var/log/messages
420
421 Then restart syslogd with:
422
423 /etc/rc.d/init.d/syslog restart
424
425 (The above may vary, depending upon which Linux distribution you use).
426
427 o If your problem is reproducible then that's great. Try the
428 following:
429
430 1) Increase the debug level. Usually this is done via:
431
432 a) modprobe driver debug=7
433 b) In /etc/modprobe.conf (or /etc/modules.conf for 2.4):
434 options driver debug=7
435
436 2) Recreate the problem with the higher debug level,
437 send all logs to the maintainer.
438
439 3) Download you card's diagnostic tool from Donald
Randy Dunlap98766fb2005-11-21 21:32:31 -0800440 Becker's website <http://www.scyld.com/ethercard_diag.html>.
441 Download mii-diag.c as well. Build these.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700442
443 a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
444 working correctly. Save the output.
445
446 b) Run the above commands when the card is malfunctioning. Send
447 both sets of output.
448
Randy Dunlap98766fb2005-11-21 21:32:31 -0800449Finally, please be patient and be prepared to do some work. You may
450end up working on this problem for a week or more as the maintainer
451asks more questions, asks for more tests, asks for patches to be
452applied, etc. At the end of it all, the problem may even remain
453unresolved.