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