1.\" Copyright (c) 2003 2.\" Bill Paul <wpaul@windriver.com>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by Bill Paul. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 29.\" THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd November 28, 2014 34.Dt RE 4 35.Os 36.Sh NAME 37.Nm re 38.Nd "RealTek 8139C+/8169/816xS/811xS/8101E/8105E PCI/PCIe Ethernet adapter driver" 39.Sh SYNOPSIS 40.Cd "device miibus" 41.Cd "device re" 42.Pp 43Alternatively, to load the driver as a module at boot time, place the 44following line in 45.Pa /boot/loader.conf : 46.Bd -literal -offset indent 47if_re_load="YES" 48.Ed 49.Sh DESCRIPTION 50The 51.Nm 52driver provides support for various NICs based on the RealTek 53RTL8139C+, RTL8169, RTL8169S, RTL8110S, RTL8168S, RTL8111S and RTL8101E 54PCI and PCIe ethernet controllers. 55.Pp 56NICs based on the 578139C+ and 8101E 58are capable of 10 and 100Mbps speeds over CAT5 cable. 59NICs based on the 608169, 816xS and 811xS 61are capable of 10, 100 and 1000Mbps operation. 62.Pp 63All NICs supported by the 64.Nm 65driver have TCP/IP checksum offload and hardware VLAN tagging/insertion 66features, and use a descriptor-based DMA mechanism. They are also 67capable of TCP large send (TCP segmentation offload). 68.Pp 69The 8139C+ is a single-chip solution combining both a 10/100 MAC and PHY. 70The 8169 is a 10/100/1000 MAC only, requiring a GMII or TBI external PHY. 71The 8169S and 8110S are single-chip devices containing both a 10/100/1000 72MAC and 10/100/1000 copper PHY. Standalone 10/100/1000 cards are available 73in both 32-bit PCI and 64-bit PCI models. The 8110S is designed for 74embedded LAN-on-motherboard applications. 75.Pp 76The 8169, 8169S and 8110S also support jumbo frames, which can be configured 77via the interface MTU setting. 78Selecting an MTU larger than 1500 bytes with the 79.Xr ifconfig 8 80utility configures the adapter to receive and transmit jumbo frames. 81The maximum MTU setting for Jumbo Frames is 7426. 82This value coincides with the maximum Jumbo Frames size of 7440. 83.Pp 84The 85.Nm 86driver supports the following media types: 87.Bl -tag -width 10baseTXUTP 88.It Cm autoselect 89Enable autoselection of the media type and options. 90The user can manually override 91the autoselected mode by adding media options to 92.Xr rc.conf 5 . 93.It Cm 10baseT/UTP 94Set 10Mbps operation. 95The 96.Xr ifconfig 8 97.Ic mediaopt 98option can also be used to select either 99.Cm full-duplex 100or 101.Cm half-duplex 102modes. 103.It Cm 100baseTX 104Set 100Mbps (fast ethernet) operation. 105The 106.Xr ifconfig 8 107.Ic mediaopt 108option can also be used to select either 109.Cm full-duplex 110or 111.Cm half-duplex 112modes. 113.It Cm 1000baseT 114Set 1000baseT operation over twisted pair. 115The RealTek gigE chips support 1000Mbps in 116.Cm full-duplex 117mode only. 118.\" .It Cm 1000baseSX 119.\" Set 1000Mbps (gigabit ethernet) operation. 120.\" Both 121.\" .Cm full-duplex 122.\" and 123.\" .Cm half-duplex 124.\" modes are supported. 125.El 126.Pp 127The 128.Nm 129driver supports the following media options: 130.Bl -tag -width full-duplex 131.It Cm full-duplex 132Force full duplex operation. 133.It Cm half-duplex 134Force half duplex operation. 135.El 136.Pp 137For more information on configuring this device, see 138.Xr ifconfig 8 . 139The 140.Nm 141driver supports 142.Xr polling 4 . 143.Ss MIB Variables 144A number of per-interface variables are implemented in the 145.Va dev.re. Ns Em X 146branch of the 147.Xr sysctl 3 148MIB. 149.Bl -tag -width ".Va rx_desc_count" 150.It Va rx_desc_count 151Number of RX descriptors (read-only). 152Use the tunable 153.Va hw.re.rx_desc_count 154to configure it. 155.It Va tx_desc_count 156Number of TX descriptors (read-only). 157Use the tunable 158.Va hw.re.tx_desc_count 159to configure it. 160.It Va imtype 161Interrupt moderation type. 1620 means disable interrupt moderation. 1631 means using simulated interrupt moderation (default). 1642 means using hardware interrupt moderation, 165if hardware supports it. 166Due to lack of proper document, 167hardware interrupt moderation (2) may not work as expected. 168.It Va sim_time 169If 170.Va imtype 171is set to 1, 172it controls interrupt moderation time (unit: 1us). 173It will not have any effect, 174if 175.Va imtype 176is 0 or 2. 177By default, it is set to 75us for PCIe controllers and 178125us for PCI controllers. 179.It Va hw_txtime 180If the controller does not support hardware interrupt moderation, 181then this sysctl node will not exist. 182If 183.Va imtype 184is set to 2, 185it controls TX interrupt moderation time (unit: 25us). 186It will not have any effect, 187if 188.Va imtype 189is 0 or 1. 190It is set to 5 (125us) by default. 191Due to lack of chip document, 192it may not work reliably. 193.It Va hw_rxtime 194If the controller does not support hardware interrupt moderation, 195then this sysctl node will not exist. 196If 197.Va imtype 198is set to 2, 199it controls RX interrupt moderation time (unit: 25us). 200It will not have any effect, 201if 202.Va imtype 203is 0 or 1. 204It is set to 2 (50us) by default. 205Due to lack of chip document, 206it may not work reliably. 207.El 208.Sh HARDWARE 209The 210.Nm 211driver supports RealTek RTL8139C+, RTL8169, RTL816xS, RTL811xS, 212RTL8105E, and RTL8101E based Fast Ethernet and Gigabit Ethernet adapters 213including: 214.Pp 215.Bl -bullet -compact 216.It 217Alloy Computer Products EtherGOLD 1439E 10/100 (8139C+) 218.It 219Compaq Evo N1015v Integrated Ethernet (8139C+) 220.It 221Corega CG-LAPCIGT Gigabit Ethernet (8169S) 222.It 223D-Link DGE-528(T) Gigabit Ethernet (8169S) 224.It 225Gigabyte 7N400 Pro2 Integrated Gigabit Ethernet (8110S) 226.It 227LevelOne GNC-0105T (8169S) 228.It 229LinkSys EG1032 (32-bit PCI) 230.It 231PLANEX COMMUNICATIONS Inc.\& GN-1200TC (8169S) 232.It 233Xterasys XN-152 10/100/1000 NIC (8169) 234.El 235.Sh DIAGNOSTICS 236.Bl -diag 237.It "re%d: couldn't map ports" 238A fatal initialization error has occurred. 239.It "re%d: couldn't map interrupt" 240A fatal initialization error has occurred. 241.It "re%d: watchdog timeout" 242The device has stopped responding to the network, or there is a problem with 243the network connection (cable). 244.El 245.Sh SEE ALSO 246.Xr arp 4 , 247.Xr ifmedia 4 , 248.Xr miibus 4 , 249.Xr netintro 4 , 250.Xr ng_ether 4 , 251.Xr polling 4 , 252.Xr vlan 4 , 253.Xr ifconfig 8 254.Rs 255.%T RealTek Semiconductor RTL8139C+, RTL8169, RTL8169S and RTL8110S datasheets 256.%O http://www.realtek.com.tw 257.Re 258.Sh HISTORY 259The 260.Nm 261device driver first appeared in 262.Fx 5.2 263and 264.Dx 1.0 . 265.Sh AUTHORS 266The 267.Nm 268driver was written by 269.An Bill Paul Aq Mt wpaul@windriver.com . 270.Sh BUGS 271The Xterasys XN-152 32-bit PCI NIC, which uses the RTL8169 MAC and 272Marvell 88E1000 PHY, has a defect that causes DMA corruption 273if the board is plugged into a 64-bit PCI slot. The defect 274lies in the board design, not the chip itself: the PCI REQ64# and ACK64# 275lines should be pulled high, but they are not. The result is that the 2768169 chip is tricked into performing 64-bit DMA transfers even though 277a 64-bit data path between the NIC and the bus does not actually exist. 278.Pp 279Unfortunately, it is not possible to correct this problem in software, 280however it is possible to detect it. When the 281.Nm 282driver is loaded, it will run a diagnostic routine designed to 283validate DMA operation by placing the chip in digital loopback mode 284and initiating a packet transmission. If the card functions properly, 285the transmitted data will 286be echoed back unmodified. If the echoed data is corrupt, the driver 287will print an error message on the console and abort the device attach. The 288user should insure the NIC is installed in a 32-bit PCI slot to 289avoid this problem. 290