"8139too" Fast Ethernet driver for Linux Improved support for RTL-8139 Fast Ethernet adapters Copyright 2000 Jeff Garzik Architectures supported (all PCI platforms): x86, Alpha AXP, PowerPC, Sparc64 Disclaimer ---------- THIS DRIVER IS A DEVELOPMENT RELEASE FOR A DEVELOPMENT KERNEL. DO NOT USE IN A PRODUCTION ENVIRONMENT. DO NOT CONTACT DONALD BECKER FOR SUPPORT OF THIS DRIVER, his driver is completely different and maintained independently of the 8139too code base. Requirements ------------ Kernel 2.3.41 or later. A Fast Ethernet adapter containing an RTL8139-based chip. Introduction ------------ The "8139too" Fast Ethernet driver for Linux 2.4.0 is a substantial modification of the experimental rtl8139 driver from Donald Becker, some versions of which appeared in 2.2.x and 2.3.x kernels. The RTL-8139 is a very low-cost Fast Ethernet chip, which makes it very popular. The step from 2.2.x to 2.4.x kernels brings many new features to Linux device drivers. Features for MMIO resources, a standard hot-plug API, and other interfaces are now becoming requirements, as drivers move off the x86 platform. With that in mind, I have begun updating the RTL-8139 driver to current 2.3.x (2.4) kernel standards and APIs, and fixing the problems that users have been encountering. Features of 8139too ------------------- [note - this list intended for people familiar with kernel drivers] ** 100% MMIO, for full speed operation. All users (so far) have reported performance increases over their existing RTL drivers. ** Multi-platform support: x86, Alpha, PPC, ... ** Use proper SMP spinlocking, fixing SMP interrupt bugs, making the driver portable to non-x86 SMP platforms in the process. ** Use new PCI driver API for seamless, low-maintenance hot-plug support ** Several bugs fixes from original rtl8139 1.08r (October 5, 1999), including the very common "transmit timeout" problem. * Use new resource allocation API, required for hot-plug support * Use new register read/write macros * initcall support (module_init/exit) * vastly improved debug tracing support * code formatting in many places for readability * use new init_etherdev() facilities ...and probably some other less important changes which I forgot. Installation ------------ OPTION 1: Build inside kernel tree (into kernel image, or as module) (overwrite 8139too driver in kernel tree with different version) 1) cp 8139too.c $my_source_tree/drivers/net/8139too.c OPTION 2: Build outside kernel tree Use the included Makefile. Tested Adapters --------------- AOpen ALN-325C KTI KF-230TX KTI KF-230TX/2 (please add your adapter model to this list) Status of Platform Support -------------------------- (see errata below for details) x86: tested, stable Alpha AXP: tested, stable PowerPC: tested, unstable Sparc64: not tested Special Thanks -------------- The following people contributed invaluable testing time, feedback and/or patches during the development of this driver. Thanks to all of them. Donald Becker, Alan Cox, Richard Stallman, Linus Torvalds - inspiration Alan Cox, Gerard Roudier - insight on posted MMIO writes Martin Mares - code review Tigran Aivazian - testing, code review, and a bug fix Chmouel Boudjnah, Alexander Dietrich, Oleg Drokin, James Fidell, Taso Hatzi, Peter K - intrepid test team And thanks to every supporter free software. Submitting Bug Reports ---------------------- Obtain and compile the modified rtl8139-diag source code from the 8139too driver Web site. This diagnostics programs, originally from Donald Becker, has been modified to display all registers on your RTL8139 chip, not just the first 0x80. If possible, send the output of a working and broken driver with rtl8139-diag -mmmaaavvveefN > my-output-file.txt Send "lspci -vvv" or "cat /proc/pci" output for PCI information. Known Bugs / Errata / To-Do --------------------------- The following issues are known, and are actively being pursued. Patches to resolve these issues is welcome. If a problem occurs which is not in the list, please report it. That's why we do beta releases, after all... 1) Work with Donald to merge fixes and updates into his driver. 2) 2.2.x COMPATIBILITY SUPPORT IS BROKEN. DO NOT USE IT. It is included only for enterprising hackers willing to help fix it. 3) PPC platform has stability problems. 4) Sparc64 platform not tested at all. 5) Identify and fix "rx wedge" when ping flooded. (WIP) 7) N-Way auto-negotiation is known to fail in some cases. This problem also occurs in the rtl8139 driver in kernels 2.2.x/2.3.x. Solution: Following technique in sunhme and sunbmac, use a kernel timer to manually perform autonegotiation in case the network or card cannot do it automatically. (patches welcome) 8) Much improved command line / module parameter setup. (patches and suggestions welcome) (WIP) 9) Better documentation. (patches welcome) 10) (rtl8139-diag modified from Becker version, DONE) User-mode (or maybe optional /proc) diagnostics program. 11) RTL8139C support untested. 12) 10base-T support flaky or slow Change History -------------- Version 0.9.7 - June 11, 2000 * Fix support for older chips (RTL8139 early chips should now work again) Version 0.9.6 - May 30, 2000 * Fix 4-extra-bytes bug (thanks to Markus Westergren, via Santiago Garcia Mantinan) * Yet more improved chip recognition Version 0.9.5 - May 17, 2000 * Improved chip version recognition * Continue banging away at receiver hang problem * Use spin_lock_irq in another spot * Don't print anything on pci_enable_device, it does so for us * Disable buggy NWay code * Define TxConfig bitmasks Version 0.9.4.1 - April 27, 2000 - third public beta release * Replace several "magic numbers" with symbolic constants * Differentiate between board-specific info and chip-specific info (allows for easier support of specific boards or chips) * Move some of the transmit side outside of the spinlock by using atomic variables. Use spin_lock_irq instead of spin_lock_irq{save,restore} in select places, for better performance. * New module option "media" for forcing media selection. Functions the same as "options" in other drivers, and will soon be renamed 'options' to be homogeneous. * New power management wake-up code * Slightly more verbose chip id messages in kernel log * Add/correct chip register constant list * New chipset wake up (open) logic * No longer locks CONFIGx updates * Do not set Interfame Gap (IFG) bits in TxConfig * Better Rx reset logic in case of Rx FIFO Overflow * For chips which support it, enable bit to automatically clear Rx FIFO overflow * No longer enable and disable interrupts in interrupt handler (technique borrowed from BSD driver, appears to have problems with some chips) * H/W spinlock now protects ioctl * Chipset-dependent RxConfig settings Version 0.9.3.3.2 - Feb 22, 2000 - second public beta release * Begin integration of Daniel Kobras' MMIO flush patch (disabled for now) * Softnet logic updates to fix bugs and improve performance * Dynamic sizing of I/O resources (0x80 for older chips, 0xFF for newer ones) * Remove bogus SiS entries from PCI probe table * Add support for cards "Delta Electronics 8139 10/100BaseTX" "Addtron Technolgy 8139 10/100BaseTX" * Fix major bug with rx ring buffer size (also present in rtl8139.c 1.08r) * PCI DMA mapping by Dave Miller * Complete rewrite of SMP locking logic * Hotplug support * Call rtl8139_hw_start from rtl8139_open, and remove duplicated code from rtl8139_open * Reset NWay registers to sane defaults on rtl8139_open/hw_start * Miscellaneous code cleanup Version 0.7.0 - Feb 7, 2000 - first public beta release * Initial public version, derived from Donald Becker's rtl8139.c v1.08r [EOF]