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@cesdis.gsfc.nasa.gov>
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 3c900 Cyclone 10Mbps Combo
38 3c900 Cyclone 10Mbps TPC
39 3c900B-FL Cyclone 10base-FL
40 3c905 Boomerang 100baseTx
41 3c905 Boomerang 100baseT4
42 3c905B Cyclone 100baseTx
43 3c905B Cyclone 10/100/BNC
44 3c905B-FX Cyclone 100baseFx
45 3c905C Tornado
46 3c980 Cyclone
47 3cSOHO100-TX Hurricane
48 3c555 Laptop Hurricane
49 3c575 Boomerang CardBus
50 3CCFE575 Cyclone CardBus
51 3CCFE575CT Cyclone CardBus
52 3CCFE656 Cyclone CardBus
53 3CCFEM656 Cyclone CardBus
54 3c450 Cyclone/unknown
55
56
57 Module parameters
58 =================
59
60 There are several parameters which may be provided to the driver when
61 its module is loaded. These are usually placed in /etc/modules.conf
62 (used to be conf.modules). Example:
63
64 options 3c59x debug=3 rx_copybreak=300
65
66 If you are using the PCMCIA tools (cardmgr) then the options may be
67 placed in /etc/pcmcia/config.opts:
68
69 module "3c59x" opts "debug=3 rx_copybreak=300"
70
71
72 The supported parameters are:
73
74 debug=N
75
76 Where N is a number from 0 to 7. Anything above 3 produces a lot
77 of output in your system logs. debug=1 is default.
78
79 options=N1,N2,N3,...
80
81 Each number in the list provides an option to the corresponding
82 network card. So if you have two 3c905's and you wish to provide
83 them with option 0x204 you would use:
84
85 options=0x204,0x204
86
87 The individual options are composed of a number of bitfields which
88 have the following meanings:
89
90 ssible media type settings
91 0 10baseT
92 1 10Mbs AUI
93 2 undefined
94 3 10base2 (BNC)
95 4 100base-TX
96 5 100base-FX
97 6 MII (Media Independent Interface)
98 7 Use default setting from EEPROM
99 8 Autonegotiate
100 9 External MII
101 10 Use default setting from EEPROM
102
103 When generating a value for the 'options' setting, the above media
104 selection values may be OR'ed (or added to) the following:
105
106 512 (0x200) Force full duplex mode.
107 16 (0x10) Bus-master enable bit (Old Vortex cards only)
108
109 For example:
110
111 insmod 3c59x options=0x204
112
113 will force full-duplex 100base-TX, rather than allowing the usual
114 autonegotiation.
115
116 full_duplex=N1,N2,N3...
117
118 Similar to bit 9 of 'options'. Forces the corresponding card into
119 full-duplex mode.
120
121 flow_ctrl=N1,N2,N3...
122
123 Use 802.3x MAC-layer flow control. The 3com cards only support the
124 PAUSE command, which means that they will stop sending packets for a
125 short period if they receive a PAUSE frame from the link partner.
126
127 The driver only allows flow control on a link which is operating in
128 full duplex mode.
129
130 This feature does not appear to work on the 3c905 - only 3c905B and
131 3c905C have been tested.
132
133 The 3com cards appear to only respond to PAUSE frames which are
134 sent to the reserved destination address of 01:80:c2:00:00:01. They
135 do not honour PAUSE frames which are sent to the station MAC address.
136
137 rx_copybreak=M
138
139 The driver preallocates 32 full-sized (1536 byte) network buffers
140 for receiving. When a packet arrives, the driver has to decide
141 whether to leave the packet in its full-sized buffer, or to allocate
142 a smaller buffer and copy the packet across into it.
143
144 This is a speed/space tradeoff.
145
146 The value of rx_copybreak is used to decide when to make the copy.
147 If the packet size is less than rx_copybreak, the packet is copied.
148 The default value for rx_copybreak is 200 bytes.
149
150 max_interrupt_work=N
151
152 The driver's interrupt service routine can handle many receive and
153 transmit packets in a single invocation. It does this in a loop.
154 The value of max_interrupt_work governs how mnay times the interrupt
155 service routine will loop. The default value is 32 loops. If this
156 is exceeded the interrupt service routine gives up and generates a
157 warning message "eth0: Too much work in interrupt".
158
159 compaq_ioaddr=N
160 compaq_irq=N
161 compaq_device_id=N
162
163 "Variables to work-around the Compaq PCI BIOS32 problem"....
164
165 watchdog=N
166
167 Sets the time duration (in milliseconds) after which the kernel
168 decides that the transmitter has become stuck and needs to be reset.
169 This is mainly for debugging purposes, although it may be advantageous
170 to increase this value on LANs which have very high collision rates.
171 The default value is 400 (0.4 seconds).
172
173 Additional resources
174 --------------------
175
176 Details of the device driver implementation are at the top of the source file.
177
178 Additional documentation is available at Don Becker's Linux Drivers site:
179
180 http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html
181
182 Donald Becker's driver development site:
183
184 http://www.scyld.com
185 http://cesdis.gsfc.nasa.gov/linux/
186
187 Don's vortex-diag program is useful for inspecting the NIC's state:
188
189 http://www.scyld.com/diag/#pci-diags
190 http://cesdis.gsfc.nasa.gov/linux/diag/vortex-diag.c
191
192 Don's mii-diag program may be used for inspecting and manipulating the
193 NIC's Media Independent Interface subsystem:
194
195 http://www.scyld.com/diag/#mii-diag
196 http://cesdis.gsfc.nasa.gov/linux/diag/#mii-diag
197
198 3Com's documentation for many NICs, including the ones supported by
199 this driver is available at
200
201 http://support.3com.com/partners/developer/developer_form.html
202
203 A detailed changelog for the modifications which were made for 2.3
204 series kernel is available at
205
206 http://www.uow.edu.au/~andrewm/linux/#3c59x-2.3
207
208
209 Autonegotiation notes
210 ---------------------
211
212 The driver uses a one-minute heartbeat for adapting to changes in
213 the external LAN environment. This means that when, for example, a
214 machine is unplugged from a hubbed 10baseT LAN plugged into a
215 switched 100baseT LAN, the throughput will be quite dreadful for up
216 to sixty seconds. Be patient.
217
218 Cisco interoperability note from Walter Wong <wcw+@CMU.EDU>:
219
220 On a side note, adding HAS_NWAY seems to share a problem with the
221 Cisco 6509 switch. Specifically, you need to change the spanning
222 tree parameter for the port the machine is plugged into to 'portfast'
223 mode. Otherwise, the negotiation fails. This has been an issue
224 we've noticed for a while but haven't had the time to track down.
225
226
227 Reporting and diagnosing problems
228 ---------------------------------
229
230 Maintainers find that accurate and complete problem reports are
231 invaluable in resolving driver problems. We are frequently not able to
232 reproduce problems and must rely on your patience and efforts to get to
233 the bottom of the problem.
234
235 If you believe you have a driver problem here are some of the
236 steps you should take:
237
238 - Is it really a driver problem?
239
240 Eliminate some variables: try different cards, different
241 computers, different cables, different ports on the switch/hub,
242 different versions of the kernel or ofthe driver, etc.
243
244 - OK, it's a driver problem.
245
246 You need to generate a report. Typically this is an email to the
247 maintainer and/or linux-net@vger.kernel.org. The maintainer's
248 email address will be inthe driver source or in the MAINTAINERS file.
249
250 - The contents of your report will vary a lot depending upon the
251 problem. If it's a kernel crash then you should refer to the
252 REPORTING-BUGS file.
253
254 But for most problems it is useful to provide the following:
255
256 o Kernel version, driver version
257
258 o A copy of the banner message which the driver generates when
259 it is initialised. For example:
260
261 eth0: 3Com PCI 3c905C Tornado at 0xa400, 00:50:da:6a:88:f0, IRQ 19
262 8K byte-wide RAM 5:3 Rx:Tx split, autoselect/Autonegotiate interface.
263 MII transceiver found at address 24, status 782d.
264 Enabling bus-master transmits and whole-frame receives.
265
266 o If it is a PCI device, the relevant output from 'lspci -vx', eg:
267
268 00:09.0 Ethernet controller: 3Com Corporation 3c905C-TX [Fast Etherlink] (rev 74)
269 Subsystem: 3Com Corporation: Unknown device 9200
270 Flags: bus master, medium devsel, latency 32, IRQ 19
271 I/O ports at a400 [size=128]
272 Memory at db000000 (32-bit, non-prefetchable) [size=128]
273 Expansion ROM at <unassigned> [disabled] [size=128K]
274 Capabilities: [dc] Power Management version 2
275 00: b7 10 00 92 07 00 10 02 74 00 00 02 08 20 00 00
276 10: 01 a4 00 00 00 00 00 db 00 00 00 00 00 00 00 00
277 20: 00 00 00 00 00 00 00 00 00 00 00 00 b7 10 00 10
278 30: 00 00 00 00 dc 00 00 00 00 00 00 00 05 01 0a 0a
279
280 o A description of the environment: 10baseT? 100baseT?
281 full/half duplex? switched or hubbed?
282
283 o Any additional module parameters which you may be providing to the driver.
284
285 o Any kernel logs which are produced. The more the merrier.
286 If this is a large file and you are sending your report to a
287 mailing list, mention that you have the logfile, but don't send
288 it. If you're reporting direct to the maintainer then just send
289 it.
290
291 To ensure that all kernel logs are available, add the
292 following line to /etc/syslog.conf:
293
294 kern.* /var/log/messages
295
296 Then restart syslogd with:
297
298 /etc/rc.d/init.d/syslog restart
299
300 (The above may vary, depending upon which Linux distribution you use).
301
302 o If your problem is reproducible then that's great. Try the
303 following:
304
305 1) Increase the debug level. Usually this is done via:
306
307 a) modprobe driver.o debug=7
308 b) In /etc/conf.modules (or modules.conf):
309 options driver_name debug=7
310
311 2) Recreate the problem with the higher debug level,
312 send all logs to the maintainer.
313
314 3) Download you card's diagnostic tool from Donald
315 Backer's website http://www.scyld.com/diag. Download
316 mii-diag.c as well. Build these.
317
318 a) Run 'vortex-diag -aaee' and 'mii-diag -v' when the card is
319 working correctly. Save the output.
320
321 b) Run the above commands when the card is malfunctioning. Send
322 both sets of output.
323
324 Finally, please be patient and be prepared to do some work. You may end up working on
325 this problem for a week or more as the maintainer asks more questions, asks for more
326 tests, asks for patches to be applied, etc. At the end of it all, the problem may even
327 remain unresolved.
328
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.