About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / vortex.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	Documentation/networking/vortex.txt
2	Andrew Morton
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
15	  Netdev mailing list <netdev@vger.kernel.org>
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		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
65	
66	Module parameters
67	=================
68	
69	There are several parameters which may be provided to the driver when
70	its module is loaded.  These are usually placed in /etc/modprobe.d/*.conf
71	configuration files.  Example:
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. 
181	  The value of max_interrupt_work governs how many 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	
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	
285	     http://www.scyld.com/vortex.html
286	
287	Donald Becker's driver development site:
288	
289	     http://www.scyld.com/network.html
290	
291	Donald's vortex-diag program is useful for inspecting the NIC's state:
292	
293	     http://www.scyld.com/ethercard_diag.html
294	
295	Donald's mii-diag program may be used for inspecting and manipulating
296	the NIC's Media Independent Interface subsystem:
297	
298	     http://www.scyld.com/ethercard_diag.html#mii-diag
299	
300	Donald's wake-on-LAN page:
301	
302	     http://www.scyld.com/wakeonlan.html
303	
304	3Com's DOS-based application for setting up the NICs EEPROMs:
305	
306		ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
307	
308	
309	Autonegotiation notes
310	---------------------
311	
312	  The driver uses a one-minute heartbeat for adapting to changes in
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.
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,
357	   different versions of the kernel or of the driver, etc.
358	
359	- OK, it's a driver problem.
360	
361	   You need to generate a report.  Typically this is an email to the
362	   maintainer and/or netdev@vger.kernel.org.  The maintainer's
363	   email address will be in the driver source or in the MAINTAINERS file.
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	  admin-guide/reporting-bugs.rst 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
428	         b) In /etc/modprobe.d/driver.conf:
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
435	         Becker's website <http://www.scyld.com/ethercard_diag.html>.
436	         Download mii-diag.c as well.  Build these.
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	
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog