Documentation/networking/8139too.txt

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