1
2		"8139too" Fast Ethernet driver for Linux
3	 RTL-8139, -8129, and -8130 10/100 Fast Ethernet adapters
4
5	Copyright 2000,2001 Jeff Garzik <jgarzik@mandrakesoft.com>
6
7                http://sourceforge.net/projects/gkernel/
8
9
10	      Architectures supported (all PCI platforms):
11		    x86, Alpha AXP, PowerPC, Sparc64
12
13		    Kernel versions supported: 2.4.x
14
15
16
17Disclaimer
18----------
19
20DO NOT CONTACT DONALD BECKER FOR SUPPORT OF THIS DRIVER, his driver is
21completely different and maintained independently of the 8139too code base.
22
23
24
25Requirements
26------------
27Kernel 2.4.3 or later.
28A Fast Ethernet adapter containing an RTL8139-based chip.
29
30
31
32Introduction
33------------
34
35The "8139too" Fast Ethernet driver for Linux 2.4.0 is a substantial
36modification of the experimental rtl8139 driver from Donald Becker,
37some versions of which appeared in 2.2.x and 2.3.x kernels.  The
38RTL-8139 is a very low-cost Fast Ethernet chip, which makes it very
39popular.
40
41The step from 2.2.x to 2.4.x kernels brings many new features to Linux
42device drivers.  Features for MMIO resources, a standard hot-plug API,
43and other interfaces are now becoming requirements, as drivers move
44off the x86 platform.  With that in mind, I have begun updating the
45RTL-8139 driver to current 2.3.x (2.4) kernel standards and APIs, and
46fixing the problems that users have been encountering.
47
48
49
50Features of 8139too
51-------------------
52[note - this list intended for people familiar with kernel drivers]
53
54** 100% MMIO, for full speed operation.  All users (so far) have
55reported performance increases over their existing RTL drivers.
56
57** Multi-platform support:  x86, Alpha, PPC, ...
58
59** Use proper SMP spinlocking, fixing SMP interrupt bugs, making the
60driver portable to non-x86 SMP platforms in the process.
61
62** Use new PCI driver API for seamless, low-maintenance hot-plug support
63
64** Several bugs fixes from original rtl8139 1.08r (October 5, 1999),
65including the very common "transmit timeout" problem.
66
67* Use new resource allocation API, required for hot-plug support
68* Use new register read/write macros
69* initcall support (module_init/exit)
70* vastly improved debug tracing support
71* code formatting in many places for readability
72* use new init_etherdev() facilities
73
74...and probably some other less important changes which I forgot.
75
76
77
78Installation
79------------
80
81OPTION 1: Build inside kernel tree (into kernel image, or as module)
82
83	(overwrite 8139too driver in kernel tree with different version)
84	1) cp 8139too.c $my_source_tree/drivers/net/8139too.c
85
86OPTION 2: Build outside kernel tree
87
88	Use the included Makefile.
89
90
91
92Tested Adapters
93---------------
94AOpen ALN-325C
95AT-2500TX 10/100 PCI Fast Ethernet Network Adapter Card
96KTI KF-230TX
97KTI KF-230TX/2
98Lantech FastNet TX
99Ovislink Fast Ethernet
100Planet ENW-9504 (V.4) 10/100
101SDT Jeoun Fast PCI-TX
102SMC EZNET 10/100
103UNEX NexNIC ND012C
104
105(please add your adapter model to this list)
106
107
108
109Status of Platform Support
110--------------------------
111
112(see errata below for details)
113
114x86:		tested, stable
115Alpha AXP:	tested, stable
116PowerPC:	tested, unstable
117Sparc64:	not tested
118
119
120
121Special Thanks
122--------------
123The following people contributed invaluable testing time, feedback
124and/or patches during the development of this driver.  Thanks to all
125of them.
126
127Donald Becker, Alan Cox, Richard Stallman, Linus Torvalds - inspiration
128
129Alan Cox, Gerard Roudier - insight on posted MMIO writes
130
131Martin Mares - code review
132
133Tigran Aivazian - testing, code review, and a bug fix
134
135Chmouel Boudjnah, Alexander Dietrich, Oleg Drokin,
136James Fidell, Taso Hatzi, Peter K - intrepid test team
137
138And thanks to every supporter free software.
139
140(see top of 8139too.c for further credits and kudos)
141
142
143
144Submitting Bug Reports
145----------------------
146Obtain and compile the modified rtl8139-diag source code from the
1478139too driver Web site, http://sourceforge.net/projects/gkernel/
148This diagnostics programs, originally from Donald Becker, has been
149modified to display all registers on your RTL8139 chip, not just the
150first 0x80.
151
152If possible, send the output of a working and broken driver with
153	rtl8139-diag -mmaaavvveefN > my-output-file.txt
154
155Send "lspci -vvv" or "cat /proc/pci" output for PCI information.
156
157
158
159Known Bugs / Errata / To-Do
160---------------------------
161The following issues are known, and are actively being pursued.  Patches
162to resolve these issues is welcome.  If a problem occurs which is not in
163the list, please report it.  That's why we do beta releases, after all...
164
165
166
1671) Work with Donald to merge fixes and updates into his driver.
168
1692) ETHTOOL_SSET support
170
1713) PPC platform has stability problems. (XXX: verify this is still true)
172
1734) Sparc64 platform not tested at all.
174
1758) Much improved command line / module parameter setup.  (patches and
176suggestions welcome)  (WIP)
177
1789) Better documentation.  (patches welcome)
179
18012) 10base-T support flaky or slow (todo: verify this is still true)
181
182
183
184
185Change History
186--------------
187
188Version 0.9.26 - August 9, 2002
189
190* Fix MII ioctl phy id corruption.
191* Fix big-endian multicast bug.
192* Support register dumps via ethtool.
193* Fix several uses of 'len' after potential skb free, in dev->hard_start_xmit
194* Replace several "magic numbers" with their proper representation
195  constants in linux/mii.h.
196* Support ethtool media interface via generic kernel MII API
197* Export NIC-specific statistics via ethtool.
198* Proper support for RTL8139 rev K. (can be disabled via
199  compile-time conditional)
200* Add PCI ids for new 8139 boards.
201* Use ethernet crc via generic linux/crc32.h kernel API.
202* Better RX reset.  Old rx-reset method still available via
203  a compile-time conditional.
204* Only account specific RX errors if rx_status is !OK
205
206
207Version 0.9.22 - November 8, 2001
208
209* Additional retries before aborting Tx
210* Do not write other TxConfig bits when writing clear-abort bit.
211* Ack TxErr intr status after each Tx abort, too.
212* Fix oops in interface restart
213
214
215Version 0.9.21 - November 1, 2001
216
217* Disable early Rx, it hurts performance and creates races.
218* Remove DPRINTK macro function tracing.
219* Better interrupt sharing behavior.
220* Acknowledge PCI errors.
221* Remove early-Rx acknowledgement, unnecessary
222* Remove code for uncommon case where Tx packets are
223  properly aligned, and do not need to be copied.
224  Tx packets are now always copied into a static DMA buffer,
225  which is allocated at interface open.
226* Fix problems with kernel thread exit.
227
228
229Version 0.9.20 - October 18, 2001
230
231* Print out notice when 8139C+ chip is detected
232* Add id for D-Link DFE690TXD pcmcia cardbus card (Gert Dewit)
233
234
235Version 0.9.19 - October 9, 2001
236
237* Eliminate buffer copy for unaligned Tx's (manfred)
238* Better RX error recovery (manfred)
239* Wake-On-LAN and ETHTOOL_GSET support (Kalle Niemitalo)
240* Fix assertion in PIO mode (various)
241
242
243Version 0.9.18 - July 6, 2001
244
245* Fix race leading to crashes on some machines.
246* Minimize race leading to low performance.
247* Correct interrupt acknowledgement to cover all three
248  relevant Rx events.
249* Add ethtool driver info support.
250* Collect additional driver-internal statistics.
251* Add descriptions for module parameters.
252* Support new SIOCxMIIxxx ioctls added in kernel 2.4.6.
253* Multicast filter big endian fix.
254* Support new PCI PM API added in kernel 2.4.6.
255
256
257Version 0.9.17 - May 7, 2001
258
259* Fix chipset wakeup bug which prevent media connection for 8139B
260* Print out "media is unconnected..." instead of
261  "partner ability 0000"
262
263
264Version 0.9.16 - April 14, 2001
265
266* Complete MMIO audit, disable read-after-every-write
267* Update Rx interrupt handling
268* Enable Early Rx thresholds, highly recommended to reduce
269  Rx FIFO overflow
270* Make 8129 support conditional
271* Support for new 2.4.3 kernel APIs
272* More correct PIO/MMIO PCI BAR region size checking
273* Add check for totally dead/missing hardware
274* Disable media timer code to "set full duplex"
275* s/spin_lock_irq/spin_lock_irqsave/
276* Only set AcceptMulticast if more than one mc address
277* Only set rx_mode if changed, in set_rx_mode
278* Only suspend/resume if interface is up
279* Always print out version upon module load, even if no devices found
280
281
282Version 0.9.15 - February 20, 2001
283
284* Call pci_enable_device to wake up/assign resource to device,
285  before actually using it.
286* Support wacky clone PCI ids (report from Norival Toniato Junior)
287* Text spelling corrections
288* Make sure tp->phys[] is signed
289* Always wake queue after hw restart, in tx_timeout
290* Record time of last received packet
291
292
293Version 0.9.14 - January 11, 2001
294
295* Merge some changes from Becker version 1.13:
296	* Add DFE 538TX PCI id
297	* MII read/write functions updated
298	* Cfg93[45]6 lock/unlock fix
299	* RTL-8129 (MII) support
300* Clean up spinlocking
301
302
303Version 0.9.13 - December, 2000
304
305* Clear blocked signals, avoid buffer overrun setting current->comm
306* Remove bogus PCI BAR length assertions
307* Remove unused 'debug' module parameter
308
309
310Version 0.9.12 - November 23, 2000
311
312* Kill major Tx stop/wake queue race
313* Use SET_MODULE_OWNER and fix module unload race
314* Fix cable length ("Twister") tuning
315* Proper media[] array length checking
316* Replace timer with kernel thread for twister tuning state machine
317  and media checking.  Fixes mdio_xxx locking, now mdio_xxx is always
318  protected by rtnl_lock semaphore.
319* Correct some sledgehammer a.k.a. overzealous spin-locks
320* Performance: Eliminate atomic_t for Tx counters, we don't need it
321* Performance: Don't copy Tx buffer if the rare case occurs where it
322  is aligned perfectly for us.
323* Eliminate needless casting of dev->priv
324* PIO mode selection and Twister tuning are now CONFIG_xxx options
325  (though purposefully not in net/Config.in... yet)
326
327
328Version 0.9.11 - October 28, 2000
329
330* Do not fail when PIO and MMIO region lengths do not match.
331  (They don't on some CardBus models, at least)
332* Sanity check Rx packet status and size (Tobias)
333* When handling a Tx timeout, disable Tx ASAP if not already.
334* Do not inline Tx interrupt handler (better register usage)
335* Handle dirty_tx signed integer wrap
336* Do not abort Rx processing on lack of memory, keep going
337  until the current Rx ring is completely handling. (Tobias)
338* Clean up rtl8139_close
339* Whitespace correction for dev_kfree_skb_irq call
340
341
342Version 0.9.10 - September 12, 2000
343
344* Never wrap an Rx packet (faster Rx interrupt handling)
345* Clear all TxAborted conditions (bug fix)
346* Correct copyright
347* More credits
348* Update NWay doc URL
349* Clean up commonly used ifdef switches
350* Reorg info displayed at bootup/modprobe time
351* Remove some unneeded spinlocks
352* Misc cosmetic code cleanup
353* Always print interrupt status for abnormal interrupts
354* Use RealTek-recommended FIFO and DMA burst settings (1024 bytes)
355
356
357Version 0.9.9 - September 9, 2000
358
359* Fix oops-able bug in Rx ring wrap calculation (David Ford)
360* Use PIO instead of MMIO when USE_IO_OPS is defined
361* Move Rx error handling out of Rx interrupt handler, resulting in
362  tighter Rx interrupt processing
363
364
365Version 0.9.8 - September 7, 2000
366
367* Propagate request_irq error value (andrew morton)
368* Correct potential oops bug in PCI DMA unmap code
369* Fix bugs related to counting/discounting of 32-bit CRC in each Rx packet
370* Fix 16/32-bit bug in interrupt status check
371* Timer cleanups (andrew morton)
372
373
374Version 0.9.7 - June 11, 2000
375
376* Fix support for older chips (RTL8139 early chips should now work again)
377
378
379Version 0.9.6 - May 30, 2000
380
381* Fix 4-extra-bytes bug
382  (thanks to Markus Westergren, via Santiago Garcia Mantinan)
383* Yet more improved chip recognition
384
385
386Version 0.9.5 - May 17, 2000
387
388* Improved chip version recognition
389* Continue banging away at receiver hang problem
390* Use spin_lock_irq in another spot
391* Don't print anything on pci_enable_device, it does so for us
392* Disable buggy NWay code
393* Define TxConfig bitmasks
394
395
396Version 0.9.4.1 - April 27, 2000 - third public beta release
397
398* Replace several "magic numbers" with symbolic constants
399* Differentiate between board-specific info and chip-specific info
400  (allows for easier support of specific boards or chips)
401* Move some of the transmit side outside of the spinlock
402  by using atomic variables.  Use spin_lock_irq instead of
403  spin_lock_irq{save,restore} in select places, for better performance.
404* New module option "media" for forcing media selection.  Functions the
405  same as "options" in other drivers, and will soon be renamed
406  'options' to be homogeneous.
407* New power management wake-up code
408* Slightly more verbose chip id messages in kernel log
409* Add/correct chip register constant list
410* New chipset wake up (open) logic
411* No longer locks CONFIGx updates
412* Do not set Interfame Gap (IFG) bits in TxConfig
413* Better Rx reset logic in case of Rx FIFO Overflow
414* For chips which support it, enable bit to automatically clear Rx
415  FIFO overflow
416* No longer enable and disable interrupts in interrupt handler
417  (technique borrowed from BSD driver, appears to have problems
418   with some chips)
419* H/W spinlock now protects ioctl
420* Chipset-dependent RxConfig settings
421
422
423Version 0.9.3.3.2 - Feb 22, 2000 - second public beta release
424
425* Begin integration of Daniel Kobras' MMIO flush patch (disabled for now)
426* Softnet logic updates to fix bugs and improve performance
427* Dynamic sizing of I/O resources (0x80 for older chips, 0xFF for newer ones)
428* Remove bogus SiS entries from PCI probe table
429* Add support for cards
430	"Delta Electronics 8139 10/100BaseTX"
431	"Addtron Technolgy 8139 10/100BaseTX"
432* Fix major bug with rx ring buffer size (also present in rtl8139.c 1.08r)
433* PCI DMA mapping by Dave Miller
434* Complete rewrite of SMP locking logic
435* Hotplug support
436* Call rtl8139_hw_start from rtl8139_open, and remove duplicated code
437  from rtl8139_open
438* Reset NWay registers to sane defaults on rtl8139_open/hw_start
439* Miscellaneous code cleanup
440
441
442Version 0.7.0 - Feb 7, 2000 - first public beta release
443* Initial public version, derived from Donald Becker's rtl8139.c v1.08r
444
445[EOF]
446
447