Products
Scyld Beowulf Professional Edition
Scyld Enterprise Solutions
Scyld Training
Scyld Beowulf Overview

Support
Documentation
FAQs
Network Drivers
Network Diagnostics
Network driver mailing lists

Vendors

About Scyld
Press Releases
Employment
Contact

Search

Linux and the RealTek RTL8129/8139 Chips

Index

Products Supported
Installation Instructions
Run-time Configuration
Support and Mailing lists
Diagnostic program
How this driver differs from the 2.4 "8139too.c"
RTL8129/RTL8139 Multicast Support

Products Supported

This page contains information on using Linux with the Realtek RTL8129 and RTL8139 Fast Ethernet Controllers for PCI.

The master copy of this page resides on the Scyld web server.

The Linux driver for the RealTek RTL8129/8139 is available from ftp://ftp.scyld.com/pub/network/rtl8139.c.

This driver was written to support the Scyld Beowulf cluster distribution. For Beowulf-specific information, read the Beowulf project web page. For commercial Beowulf support, contact SCYLD directly.

This driver is for the RealTek 8129 and 8139 chips only. The 8019 and 8029 chips are unrelated designs. They are PCI NE2000 clones, and are supported by updates to the NE2000 driver available from the Linux PCI NE2000 Driver page.

Usage instructions

Installation

The driver installation directions are on the Driver Updates page. You may install just one driver (see below), or install all updated drivers using either the netdriver.tgz file or the SRPM.

To install a single updated driver read the Network Drivers as Modules page for instructions. You should, of course, substitute the proper driver file name.

When updating a single driver you will need to build pci-scan.o along with the specific driver.o file. This means that in addition to the driver.c file, you must download pci-scan.c, pci-scan.h, and kern_compat.h.

Run-time Configuration

This driver provide a interface to the Media Independent Interface, "MII" transceiver configuration and diagnostic settings. This interface allows the media type (i.e. 10Mbps or 100Mbps, half or full duplex) to be configured. The settings are usually configured by the (slightly misnamed) mii-diag program. The details of this program may found on the diagnostic home page.

Support

Mailing lists

Support for the RTL8139 driver is handled through the following mailing lists:

realtek-announce: Annoucements of new drivers and features.
realtek: General driver discussions, including bug fixes.
realtek-bug: Reporting driver bugs.

See http://www.scyld.com/mailman/listinfo for information on subscribing to these lists.

Using the above lists for unrelated advertisements is subject to a charge of /home/httpd/html-scyld/network.34 per destination address, payable in advance.

Driver Updates

The most recent testing version may be available from ftp://www.scyld.com/pub/network/test/rtl8139.c. If this link is invalid, the released version is the most recent publicly available driver.

Diagnostic Program

All fully supported chips have a specific diagnostic program. These programs examine the device registers, EEPROM values, and MII transceiver management registers - external connections that are likely to fail or be misconfigured. A few run tests of internal functionality, but on-chip subsystems rarely fail.

The RTL8139-specific diagnostic program is used to examine the device registers, EEPROM values, and MII transceiver management registers. The command for compiling this program is at the bottom of the source file. This program may optionally be compiled with an additional MII register diagnostic library by using the following compile command:

  cc -o rtl8139-diag -O -DLIBMII rtl8139-diag.c libmii.c

The diagnostic programs are father described at http://www.scyld.com/diag/index.html and source and binary packages are available from ftp://ftp.scyld.com/pub/diag/*

How this driver differs from the 2.4 "8139too.c"

The 8139too driver is based almost entirely on the on the 8139 driver written by Donald Becker. It has a few operational changes, most of which are flawed or pointless.

MMIO vs. PIO operation

The 8139 is mapped to both PCI I/O and memory space. Using I/O space is traditional on x86 architectures, and most drivers are written to use this mode. However, using the memory space mapping (MMIO) is more efficient for isolated writes since these are stored in a write buffer and the processor can continue execution without waiting for the PCI operation to complete. An added advantage is the processors without native I/O operations avoid extra address space calculations.

A problem with using this MMIO mode is that the 8139 has different access alignment restrictions with memory space, and the write buffer potentially changes the ordering of command writes and subsequent memory reads.

The 8139too driver attempts to work around the latter problem by doing a read immediately following a register write. Not only does this completely eliminate the advantage of having a write buffer, it doubles the overhead over just using I/O operations!

Added Spin-locks

The 8139too adds spin-locks. However, as with so many of the 2.3 spin-locks, it added them without considering if they were actually needed. The only code with a potential conflict is when reading and writing MII registers. But the 8139too driver supports only the 8139, which has an internal transceiver that is directly accessed by registers reads. So no spin-lock is needed!

The "rx_size" patch

The 8139too driver adds a patch taken from the BSD driver. This patch claims to fix a bug in the Rx ring: when copying a packet into RAM, the length will be 0xfff0. But the BSD "bug" is an artifact of that driver trying to avoid PCI bus operations by guessing if a packet has arrived, rather than following the documented method of check the RxBufEmpty status.

The BSD method is more efficient. Checking the next entry and guessing can potentially save one or two expensive PCI transactions per Rx packet. But (as they found out) it is prone to races and failure.

The Linux driver never encounters this problem, but the BSD "bug fix" was blindly added anyway.

Misleading Copyright

The copyright has been subtly changed on several drivers. The rtl8139 driver original stated "Written 1997-1999 by Donald Becker". It now states "Written by 1997-1999 Donald Becker, Copyright 2000 by Jeff Garzik". While the latter statement appear to be only an added copyright, legally they are far different. The first phrase alone implies that the copyright is held by solely by Donald Becker. The addition of the second phrase claims that the copyright has been assigned to Jeff Garzik. This is not the case, and the change is fraudulent misrepresentation.

The copyright on 8139too also fails to note that it includes substantial new code from the March 2000 release of the rtl8139.c driver.

Driver Operation and Comments

The RTL8129 series is a low-cost design, and thus should be considered a "connectivity solution" rather a performance-oriented product.

The RTL8139 series improves on the integration and feature set, adding advanced features such as 802.3x Flow Control and incorporating the transceiver onto a single chip. The data transfer engine remains the same, with much improved PCI burst performance in the B and C versions.

While the chip is a bus master, it's not a descriptor-based bus master. The receive side transfers packets into a single linear ring (compile-time selectable as 8KB, 16KB, 32KB or 64KB) in host memory. The driver immediately copies the packets from the ring to newly-allocated buffers ("skbuffs"). Most other Fast Ethernet designs use a descriptor-based architecture, which allows packets the chip to transfer directly into pre-allocated maximum-sized skbuffs. The driver then optionally copies only tiny packets into smaller-sized skbuffs.

On the transmit side four register sets hold the address and size of the packets to be transmitted. While this results in a rather small, fixed-size transmit queue, four entries is adequate for full performance in most environments.

The transmit performance loss comes from an initially undocumented (yes, that means it took many hours to find) word-alignment requirement of the current chip. Linux cache-aligns the IP header and following payload data when constructing a packet. When the 14 byte Ethernet header is prepended, the complete packet is 2-byte aligned, but not 4-byte aligned. The result is that all IP packets must be copied to an alignment buffer before being queued for transmit.

RTL8129/RTL8139 Multicast Support

The RTL chips can match a single unicast address (their own station address) and support a 64 slot statistical (AKA hash) filter for initial filtering of unwanted multicast packets. This filter functionality appears to be implemented the "usual" way: taking the CRC intermediate result just after destination address arrives, and using six bits as the index into a table of which multicast packets are acceptable.

Programming Information

Online information is available at http://www.realtek.com.tw/cn/cn.html

Compatibility, Errata and Bugs

The driver has been tested with

Chips: rtl8129, rtl8139/8139A/8139B chips (limited 8139C testing).
Kernels: starting with 2.0.30/RedHat-4.2 and many later kernels.
Architectures: x86 and Alpha (limited PowerPC testing).

but not with all combinations of each.

If you encounter Rx overflow errors and transmit timeouts you may have the card in a non-bus-master slot. Other possible problems are older PCI implementations, especially i486-class motherboards, that have bugs when using long PCI burst transfers.

Cards using RTL8139 chips

There are too many vendors selling RTL8139 boards to list them all. The RTL8139 and RTL8139A chips have the ability to load a different PCI Vendor and Device ID from the EEPROM. Combined with a unique chip label, some boards give the appearance of being new and unique chips. Identified chips that fall into this category are

Accton MPX5030 series (relabeled RTL8139)
SMC 1211TX (relabeled RTL8139)

A few commonly available board with the Realtek chip are:

ALFA GFC2206
Allied Telesyn AT2550
Genius GF100TXR (RTL8139)
NDC Communications NE100TX-E
Accton MPX5030 series (relabeled RTL8139)
SMC 1211TX (relabeled RTL8139)

The RTL8139 is used on many boards due to its low cost, and thus this list is far from complete.

Revision History

The CVS log is not yet online.

Some history...

This driver was originally written by Donald Becker while he was at CESDIS, located at the NASA Goddard Space Flight Center in Greenbelt MD. The Beowulf work moved to Scyld before CESDIS was dissolved in July 2000.

Linux Network Drivers Page
SCYLD information.
Author: Donald Becker.
See the drivers for the contact email address. Do not bother sending email to

zinc.anode@scyld.com

as email to that address adds your domain or IP address to the known-spammer list.

Linux Network Drivers Page
SCYLD information.
Author: Donald Becker
See the drivers for the contact email address. Do not bother sending email to zinc.anode@scyld.com, as email to that address adds your domain or IP address to the known-spammer list.






Products Scyld Beowulf Professional Edition Scyld Enterprise Solutions Scyld Training Scyld Beowulf Overview Support Documentation FAQs Network Drivers Network Diagnostics Network driver mailing lists Vendors About Scyld Press Releases Employment Contact Search	Linux and the RealTek RTL8129/8139 Chips Index Products Supported Installation Instructions Run-time Configuration Support and Mailing lists Diagnostic program How this driver differs from the 2.4 "8139too.c" RTL8129/RTL8139 Multicast Support Products Supported This page contains information on using Linux with the Realtek RTL8129 and RTL8139 Fast Ethernet Controllers for PCI. The master copy of this page resides on the Scyld web server. The Linux driver for the RealTek RTL8129/8139 is available from ftp://ftp.scyld.com/pub/network/rtl8139.c. This driver was written to support the Scyld Beowulf cluster distribution. For Beowulf-specific information, read the Beowulf project web page. For commercial Beowulf support, contact SCYLD directly. This driver is for the RealTek 8129 and 8139 chips only. The 8019 and 8029 chips are unrelated designs. They are PCI NE2000 clones, and are supported by updates to the NE2000 driver available from the Linux PCI NE2000 Driver page. Usage instructions Installation The driver installation directions are on the Driver Updates page. You may install just one driver (see below), or install all updated drivers using either the netdriver.tgz file or the SRPM. To install a single updated driver read the Network Drivers as Modules page for instructions. You should, of course, substitute the proper driver file name. When updating a single driver you will need to build pci-scan.o along with the specific driver.o file. This means that in addition to the driver.c file, you must download pci-scan.c, pci-scan.h, and kern_compat.h. Run-time Configuration This driver provide a interface to the Media Independent Interface, "MII" transceiver configuration and diagnostic settings. This interface allows the media type (i.e. 10Mbps or 100Mbps, half or full duplex) to be configured. The settings are usually configured by the (slightly misnamed) mii-diag program. The details of this program may found on the diagnostic home page. Support Mailing lists Mailing List archive Mailing lists Support for the RTL8139 driver is handled through the following mailing lists: realtek-announce Annoucements of new drivers and features. realtek General driver discussions, including bug fixes. realtek-bug Reporting driver bugs. See http://www.scyld.com/mailman/listinfo for information on subscribing to these lists. Using the above lists for unrelated advertisements is subject to a charge of /home/httpd/html-scyld/network.34 per destination address, payable in advance. Driver Updates The most recent testing version may be available from ftp://www.scyld.com/pub/network/test/rtl8139.c. If this link is invalid, the released version is the most recent publicly available driver. Diagnostic Program All fully supported chips have a specific diagnostic program. These programs examine the device registers, EEPROM values, and MII transceiver management registers - external connections that are likely to fail or be misconfigured. A few run tests of internal functionality, but on-chip subsystems rarely fail. The RTL8139-specific diagnostic program is used to examine the device registers, EEPROM values, and MII transceiver management registers. The command for compiling this program is at the bottom of the source file. This program may optionally be compiled with an additional MII register diagnostic library by using the following compile command: cc -o rtl8139-diag -O -DLIBMII rtl8139-diag.c libmii.c The diagnostic programs are father described at http://www.scyld.com/diag/index.html and source and binary packages are available from ftp://ftp.scyld.com/pub/diag/* How this driver differs from the 2.4 "8139too.c" The 8139too driver is based almost entirely on the on the 8139 driver written by Donald Becker. It has a few operational changes, most of which are flawed or pointless. MMIO vs. PIO operation The 8139 is mapped to both PCI I/O and memory space. Using I/O space is traditional on x86 architectures, and most drivers are written to use this mode. However, using the memory space mapping (MMIO) is more efficient for isolated writes since these are stored in a write buffer and the processor can continue execution without waiting for the PCI operation to complete. An added advantage is the processors without native I/O operations avoid extra address space calculations. A problem with using this MMIO mode is that the 8139 has different access alignment restrictions with memory space, and the write buffer potentially changes the ordering of command writes and subsequent memory reads. The 8139too driver attempts to work around the latter problem by doing a read immediately following a register write. Not only does this completely eliminate the advantage of having a write buffer, it doubles the overhead over just using I/O operations! Added Spin-locks The 8139too adds spin-locks. However, as with so many of the 2.3 spin-locks, it added them without considering if they were actually needed. The only code with a potential conflict is when reading and writing MII registers. But the 8139too driver supports only the 8139, which has an internal transceiver that is directly accessed by registers reads. So no spin-lock is needed! The "rx_size" patch The 8139too driver adds a patch taken from the BSD driver. This patch claims to fix a bug in the Rx ring: when copying a packet into RAM, the length will be 0xfff0. But the BSD "bug" is an artifact of that driver trying to avoid PCI bus operations by guessing if a packet has arrived, rather than following the documented method of check the RxBufEmpty status. The BSD method is more efficient. Checking the next entry and guessing can potentially save one or two expensive PCI transactions per Rx packet. But (as they found out) it is prone to races and failure. The Linux driver never encounters this problem, but the BSD "bug fix" was blindly added anyway. Misleading Copyright The copyright has been subtly changed on several drivers. The rtl8139 driver original stated "Written 1997-1999 by Donald Becker". It now states "Written by 1997-1999 Donald Becker, Copyright 2000 by Jeff Garzik". While the latter statement appear to be only an added copyright, legally they are far different. The first phrase alone implies that the copyright is held by solely by Donald Becker. The addition of the second phrase claims that the copyright has been assigned to Jeff Garzik. This is not the case, and the change is fraudulent misrepresentation. The copyright on 8139too also fails to note that it includes substantial new code from the March 2000 release of the rtl8139.c driver. Driver Operation and Comments The RTL8129 series is a low-cost design, and thus should be considered a "connectivity solution" rather a performance-oriented product. The RTL8139 series improves on the integration and feature set, adding advanced features such as 802.3x Flow Control and incorporating the transceiver onto a single chip. The data transfer engine remains the same, with much improved PCI burst performance in the B and C versions. While the chip is a bus master, it's not a descriptor-based bus master. The receive side transfers packets into a single linear ring (compile-time selectable as 8KB, 16KB, 32KB or 64KB) in host memory. The driver immediately copies the packets from the ring to newly-allocated buffers ("skbuffs"). Most other Fast Ethernet designs use a descriptor-based architecture, which allows packets the chip to transfer directly into pre-allocated maximum-sized skbuffs. The driver then optionally copies only tiny packets into smaller-sized skbuffs. On the transmit side four register sets hold the address and size of the packets to be transmitted. While this results in a rather small, fixed-size transmit queue, four entries is adequate for full performance in most environments. The transmit performance loss comes from an initially undocumented (yes, that means it took many hours to find) word-alignment requirement of the current chip. Linux cache-aligns the IP header and following payload data when constructing a packet. When the 14 byte Ethernet header is prepended, the complete packet is 2-byte aligned, but not 4-byte aligned. The result is that all IP packets must be copied to an alignment buffer before being queued for transmit. RTL8129/RTL8139 Multicast Support The RTL chips can match a single unicast address (their own station address) and support a 64 slot statistical (AKA hash) filter for initial filtering of unwanted multicast packets. This filter functionality appears to be implemented the "usual" way: taking the CRC intermediate result just after destination address arrives, and using six bits as the index into a table of which multicast packets are acceptable. Programming Information Online information is available at http://www.realtek.com.tw/cn/cn.html Compatibility, Errata and Bugs The driver has been tested with Chips: rtl8129, rtl8139/8139A/8139B chips (limited 8139C testing). Kernels: starting with 2.0.30/RedHat-4.2 and many later kernels. Architectures: x86 and Alpha (limited PowerPC testing). but not with all combinations of each. If you encounter Rx overflow errors and transmit timeouts you may have the card in a non-bus-master slot. Other possible problems are older PCI implementations, especially i486-class motherboards, that have bugs when using long PCI burst transfers. Cards using RTL8139 chips There are too many vendors selling RTL8139 boards to list them all. The RTL8139 and RTL8139A chips have the ability to load a different PCI Vendor and Device ID from the EEPROM. Combined with a unique chip label, some boards give the appearance of being new and unique chips. Identified chips that fall into this category are Accton MPX5030 series (relabeled RTL8139) SMC 1211TX (relabeled RTL8139) A few commonly available board with the Realtek chip are: ALFA GFC2206 Allied Telesyn AT2550 Genius GF100TXR (RTL8139) NDC Communications NE100TX-E Accton MPX5030 series (relabeled RTL8139) SMC 1211TX (relabeled RTL8139) The RTL8139 is used on many boards due to its low cost, and thus this list is far from complete. Revision History The CVS log is not yet online. Related Links http://www.realtek.com.tw/cn/cn.html OvisLink LEF-8129TX Global Data Systems GDS-84628 Allied Telesyn AT2500 and AT2500v2 Some history... This driver was originally written by Donald Becker while he was at CESDIS, located at the NASA Goddard Space Flight Center in Greenbelt MD. The Beowulf work moved to Scyld before CESDIS was dissolved in July 2000. Linux Network Drivers Page SCYLD information. Author: Donald Becker. See the drivers for the contact email address. Do not bother sending email to zinc.anode@scyld.com as email to that address adds your domain or IP address to the known-spammer list. Linux Network Drivers Page SCYLD information. Author: Donald Becker See the drivers for the contact email address. Do not bother sending email to zinc.anode@scyld.com, as email to that address adds your domain or IP address to the known-spammer list.


© 2000-2002 Scyld Computing Corporation