diff options
Diffstat (limited to 'share/man/man4/rl.4')
| -rw-r--r-- | share/man/man4/rl.4 | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/share/man/man4/rl.4 b/share/man/man4/rl.4 new file mode 100644 index 0000000..583274b --- /dev/null +++ b/share/man/man4/rl.4 @@ -0,0 +1,312 @@ +.\" Copyright (c) 1997, 1998 +.\" Bill Paul <wpaul@ctr.columbia.edu>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2013 +.Dt RL 4 +.Os +.Sh NAME +.Nm rl +.Nd "RealTek 8129/8139 Fast Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device rl" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the RealTek 8129 and 8139 Fast Ethernet controller +chips. +.Pp +The RealTek 8129/8139 series controllers use bus master DMA but do not use a +descriptor-based data transfer mechanism. +The receiver uses a +single fixed size ring buffer from which packets must be copied +into mbufs. +For transmission, there are only four outbound packet +address registers which require all outgoing packets to be stored +as contiguous buffers. +Furthermore, outbound packet buffers must +be longword aligned or else transmission will fail. +.Pp +The 8129 differs from the 8139 in that the 8139 has an internal +PHY which is controlled through special direct access registers +whereas the 8129 uses an external PHY via an MII bus. +The 8139 +supports both 10 and 100Mbps speeds in either full or half duplex. +The 8129 can support the same speeds and modes given an appropriate +PHY chip. +.Pp +Note: support for the 8139C+ chip is provided by the +.Xr re 4 +driver. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +This is only +supported if the PHY chip attached to the RealTek controller +supports NWAY autonegotiation. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +Note that the 100baseTX media type is only available if supported +by the adapter. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Accton +.Dq Cheetah +EN1207D (MPX 5030/5038; RealTek 8139 clone) +.It +Allied Telesyn AT2550 +.It +Allied Telesyn AT2500TX +.It +Belkin F5D5000 +.It +BUFFALO (Melco INC.) LPC-CB-CLX (CardBus) +.It +Compaq HNE-300 +.It +CompUSA no-name 10/100 PCI Ethernet NIC +.It +Corega FEther CB-TXD +.It +Corega FEtherII CB-TXD +.It +D-Link DFE-520TX (rev. C1) +.It +D-Link DFE-528TX +.It +D-Link DFE-530TX+ +.It +D-Link DFE-538TX +.It +D-Link DFE-690TXD +.It +Edimax EP-4103DL CardBus +.It +Encore ENL832-TX 10/100 M PCI +.It +Farallon NetLINE 10/100 PCI +.It +Genius GF100TXR +.It +GigaFast Ethernet EE100-AXP +.It +KTX-9130TX 10/100 Fast Ethernet +.It +LevelOne FPC-0106TX +.It +Longshine LCS-8038TX-R +.It +NDC Communications NE100TX-E +.It +Netronix Inc.\& EA-1210 NetEther 10/100 +.It +Nortel Networks 10/100BaseTX +.It +OvisLink LEF-8129TX +.It +OvisLink LEF-8139TX +.It +Peppercon AG ROL-F +.It +Planex FNW-3603-TX +.It +Planex FNW-3800-TX +.It +SMC EZ Card 10/100 PCI 1211-TX +.It +SOHO (PRAGMATIC) UE-1211C +.El +.Sh LOADER TUNABLES +.Bl -tag -width indent +.It Va dev.rl.%unit.prefer_iomap +This tunable controls which register mapping should be used on the +specified device. +A non-zero value enables I/O space register mapping. +For controllers that have no I/O space register mapping this tunable +should be set to 0 to use memory space register mapping. +The default value is 1 to use I/O space register mapping. +.It Va dev.rl.%unit.twister_enable +Non-zero value enables the long cable tuning on the specified device. +Disabled by default. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "rl%d: couldn't map memory" +A fatal initialization error has occurred. +.It "rl%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "rl%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "rl%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "rl%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "rl%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr ifconfig 8 +.Rs +.%B The RealTek 8129, 8139 and 8139C+ datasheets +.%U http://www.realtek.com.tw +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq wpaul@ctr.columbia.edu . +.Sh BUGS +Since outbound packets must be longword aligned, the transmit +routine has to copy an unaligned packet into an mbuf cluster buffer +before transmission. +The driver abuses the fact that the cluster buffer +pool is allocated at system startup time in a contiguous region starting +at a page boundary. +Since cluster buffers are 2048 bytes, they are +longword aligned by definition. +The driver probably should not be +depending on this characteristic. +.Pp +The RealTek data sheets are of especially poor quality, +and there is a lot of information missing +particularly concerning the receiver operation. +One particularly +important fact that the data sheets fail to mention relates to the +way in which the chip fills in the receive buffer. +When an interrupt +is posted to signal that a frame has been received, it is possible that +another frame might be in the process of being copied into the receive +buffer while the driver is busy handling the first one. +If the driver +manages to finish processing the first frame before the chip is done +DMAing the rest of the next frame, the driver may attempt to process +the next frame in the buffer before the chip has had a chance to finish +DMAing all of it. +.Pp +The driver can check for an incomplete frame by inspecting the frame +length in the header preceding the actual packet data: an incomplete +frame will have the magic length of 0xFFF0. +When the driver encounters +this value, it knows that it has finished processing all currently +available packets. +Neither this magic value nor its significance are +documented anywhere in the RealTek data sheets. |
