PageRenderTime 13ms CodeModel.GetById 2ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 1ms

/Documentation/networking/vortex.txt

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