1.. SPDX-License-Identifier: GPL-2.0
2
3=============================================================================
4Linux and the 3Com EtherLink III Series Ethercards (driver v1.18c and higher)
5=============================================================================
6
7This file contains the instructions and caveats for v1.18c and higher versions
8of the 3c509 driver. You should not use the driver without reading this file.
9
10release 1.0
11
1228 February 2002
13
14Current maintainer (corrections to):
15  David Ruggiero <jdr@farfalle.com>
16
17Introduction
18============
19
20The following are notes and information on using the 3Com EtherLink III series
21ethercards in Linux. These cards are commonly known by the most widely-used
22card's 3Com model number, 3c509. They are all 10mb/s ISA-bus cards and shouldn't
23be (but sometimes are) confused with the similarly-numbered PCI-bus "3c905"
24(aka "Vortex" or "Boomerang") series.  Kernel support for the 3c509 family is
25provided by the module 3c509.c, which has code to support all of the following
26models:
27
28 - 3c509 (original ISA card)
29 - 3c509B (later revision of the ISA card; supports full-duplex)
30 - 3c589 (PCMCIA)
31 - 3c589B (later revision of the 3c589; supports full-duplex)
32 - 3c579 (EISA)
33
34Large portions of this documentation were heavily borrowed from the guide
35written the original author of the 3c509 driver, Donald Becker. The master
36copy of that document, which contains notes on older versions of the driver,
37currently resides on Scyld web server: http://www.scyld.com/.
38
39
40Special Driver Features
41=======================
42
43Overriding card settings
44
45The driver allows boot- or load-time overriding of the card's detected IOADDR,
46IRQ, and transceiver settings, although this capability shouldn't generally be
47needed except to enable full-duplex mode (see below). An example of the syntax
48for LILO parameters for doing this::
49
50    ether=10,0x310,3,0x3c509,eth0
51
52This configures the first found 3c509 card for IRQ 10, base I/O 0x310, and
53transceiver type 3 (10base2). The flag "0x3c509" must be set to avoid conflicts
54with other card types when overriding the I/O address. When the driver is
55loaded as a module, only the IRQ may be overridden. For example,
56setting two cards to IRQ10 and IRQ11 is done by using the irq module
57option::
58
59   options 3c509 irq=10,11
60
61
62Full-duplex mode
63================
64
65The v1.18c driver added support for the 3c509B's full-duplex capabilities.
66In order to enable and successfully use full-duplex mode, three conditions
67must be met:
68
69(a) You must have a Etherlink III card model whose hardware supports full-
70duplex operations. Currently, the only members of the 3c509 family that are
71positively known to support full-duplex are the 3c509B (ISA bus) and 3c589B
72(PCMCIA) cards. Cards without the "B" model designation do *not* support
73full-duplex mode; these include the original 3c509 (no "B"), the original
743c589, the 3c529 (MCA bus), and the 3c579 (EISA bus).
75
76(b) You must be using your card's 10baseT transceiver (i.e., the RJ-45
77connector), not its AUI (thick-net) or 10base2 (thin-net/coax) interfaces.
78AUI and 10base2 network cabling is physically incapable of full-duplex
79operation.
80
81(c) Most importantly, your 3c509B must be connected to a link partner that is
82itself full-duplex capable. This is almost certainly one of two things: a full-
83duplex-capable  Ethernet switch (*not* a hub), or a full-duplex-capable NIC on
84another system that's connected directly to the 3c509B via a crossover cable.
85
86Full-duplex mode can be enabled using 'ethtool'.
87
88.. warning::
89
90  Extremely important caution concerning full-duplex mode
91
92  Understand that the 3c509B's hardware's full-duplex support is much more
93  limited than that provide by more modern network interface cards. Although
94  at the physical layer of the network it fully supports full-duplex operation,
95  the card was designed before the current Ethernet auto-negotiation (N-way)
96  spec was written. This means that the 3c509B family ***cannot and will not
97  auto-negotiate a full-duplex connection with its link partner under any
98  circumstances, no matter how it is initialized***. If the full-duplex mode
99  of the 3c509B is enabled, its link partner will very likely need to be
100  independently _forced_ into full-duplex mode as well; otherwise various nasty
101  failures will occur - at the very least, you'll see massive numbers of packet
102  collisions. This is one of very rare circumstances where disabling auto-
103  negotiation and forcing the duplex mode of a network interface card or switch
104  would ever be necessary or desirable.
105
106
107Available Transceiver Types
108===========================
109
110For versions of the driver v1.18c and above, the available transceiver types are:
111
112== =========================================================================
1130  transceiver type from EEPROM config (normally 10baseT); force half-duplex
1141  AUI (thick-net / DB15 connector)
1152  (undefined)
1163  10base2 (thin-net == coax / BNC connector)
1174  10baseT (RJ-45 connector); force half-duplex mode
1188  transceiver type and duplex mode taken from card's EEPROM config settings
11912 10baseT (RJ-45 connector); force full-duplex mode
120== =========================================================================
121
122Prior to driver version 1.18c, only transceiver codes 0-4 were supported. Note
123that the new transceiver codes 8 and 12 are the *only* ones that will enable
124full-duplex mode, no matter what the card's detected EEPROM settings might be.
125This insured that merely upgrading the driver from an earlier version would
126never automatically enable full-duplex mode in an existing installation;
127it must always be explicitly enabled via one of these code in order to be
128activated.
129
130The transceiver type can be changed using 'ethtool'.
131
132
133Interpretation of error messages and common problems
134----------------------------------------------------
135
136Error Messages
137^^^^^^^^^^^^^^
138
139eth0: Infinite loop in interrupt, status 2011.
140These are "mostly harmless" message indicating that the driver had too much
141work during that interrupt cycle. With a status of 0x2011 you are receiving
142packets faster than they can be removed from the card. This should be rare
143or impossible in normal operation. Possible causes of this error report are:
144
145   - a "green" mode enabled that slows the processor down when there is no
146     keyboard activity.
147
148   - some other device or device driver hogging the bus or disabling interrupts.
149     Check /proc/interrupts for excessive interrupt counts. The timer tick
150     interrupt should always be incrementing faster than the others.
151
152No received packets
153^^^^^^^^^^^^^^^^^^^
154
155If a 3c509, 3c562 or 3c589 can successfully transmit packets, but never
156receives packets (as reported by /proc/net/dev or 'ifconfig') you likely
157have an interrupt line problem. Check /proc/interrupts to verify that the
158card is actually generating interrupts. If the interrupt count is not
159increasing you likely have a physical conflict with two devices trying to
160use the same ISA IRQ line. The common conflict is with a sound card on IRQ10
161or IRQ5, and the easiest solution is to move the 3c509 to a different
162interrupt line. If the device is receiving packets but 'ping' doesn't work,
163you have a routing problem.
164
165Tx Carrier Errors Reported in /proc/net/dev
166^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
167
168
169If an EtherLink III appears to transmit packets, but the "Tx carrier errors"
170field in /proc/net/dev increments as quickly as the Tx packet count, you
171likely have an unterminated network or the incorrect media transceiver selected.
172
1733c509B card is not detected on machines with an ISA PnP BIOS.
174^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
175
176While the updated driver works with most PnP BIOS programs, it does not work
177with all. This can be fixed by disabling PnP support using the 3Com-supplied
178setup program.
179
1803c509 card is not detected on overclocked machines
181^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
182
183Increase the delay time in id_read_eeprom() from the current value, 500,
184to an absurdly high value, such as 5000.
185
186
187Decoding Status and Error Messages
188----------------------------------
189
190
191The bits in the main status register are:
192
193=====	======================================
194value 	description
195=====	======================================
1960x01 	Interrupt latch
1970x02 	Tx overrun, or Rx underrun
1980x04 	Tx complete
1990x08 	Tx FIFO room available
2000x10 	A complete Rx packet has arrived
2010x20 	A Rx packet has started to arrive
2020x40 	The driver has requested an interrupt
2030x80 	Statistics counter nearly full
204=====	======================================
205
206The bits in the transmit (Tx) status word are:
207
208=====	============================================
209value	description
210=====	============================================
2110x02	Out-of-window collision.
2120x04	Status stack overflow (normally impossible).
2130x08	16 collisions.
2140x10	Tx underrun (not enough PCI bus bandwidth).
2150x20	Tx jabber.
2160x40	Tx interrupt requested.
2170x80	Status is valid (this should always be set).
218=====	============================================
219
220
221When a transmit error occurs the driver produces a status message such as::
222
223   eth0: Transmit error, Tx status register 82
224
225The two values typically seen here are:
226
2270x82
228^^^^
229
230Out of window collision. This typically occurs when some other Ethernet
231host is incorrectly set to full duplex on a half duplex network.
232
2330x88
234^^^^
235
23616 collisions. This typically occurs when the network is exceptionally busy
237or when another host doesn't correctly back off after a collision. If this
238error is mixed with 0x82 errors it is the result of a host incorrectly set
239to full duplex (see above).
240
241Both of these errors are the result of network problems that should be
242corrected. They do not represent driver malfunction.
243
244
245Revision history (this file)
246============================
247
24828Feb02 v1.0  DR   New; major portions based on Becker original 3c509 docs
249
250