diff options
Diffstat (limited to 'share/man/man4/dc.4')
| -rw-r--r-- | share/man/man4/dc.4 | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/share/man/man4/dc.4 b/share/man/man4/dc.4 new file mode 100644 index 000000000000..351624544286 --- /dev/null +++ b/share/man/man4/dc.4 @@ -0,0 +1,449 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul <wpaul@ee.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 July 16, 2005 +.Dt DC 4 +.Os +.Sh NAME +.Nm dc +.Nd "DEC/Intel 21143 and clone 10/100 Ethernet 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 dc" +.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_dc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for several PCI Fast Ethernet adapters and +embedded controllers based on the the DEC/Intel 21143 chipset and clones. +.Pp +All of supported chipsets have the same general register layout, DMA +descriptor format and method of operation. +All of the clone chips +are based on the 21143 design with various modifications. +The +21143 itself has support for 10baseT, BNC, AUI, MII and symbol +media attachments, 10 and 100Mbps speeds in full or half duplex, +built in NWAY autonegotiation and wake on LAN. +The 21143 also +offers several receive filter programming options including +perfect filtering, inverse perfect filtering and hash table +filtering. +.Pp +Some clone chips duplicate the 21143 fairly closely while others +only maintain superficial similarities. +Some support only MII +media attachments. +Others use different receiver filter programming +mechanisms. +At least one supports only chained DMA descriptors +(most support both chained descriptors and contiguously allocated +fixed size rings). +Some chips (especially the PNIC) also have +peculiar bugs. +The +.Nm +driver does its best to provide generalized support for all +of these chipsets in order to keep special case code to a minimum. +.Pp +These chips are used by many vendors which makes it +difficult to provide a complete list of all supported cards. +.Pp +The +.Nm +driver supports the following media types: +.Pp +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.Pp +Note: the built-in NWAY autonegotiation on the original PNIC 82c168 +chip is horribly broken and is not supported by the +.Nm +driver at this time (see the +.Sx BUGS +section for details). +The original 82c168 appears +on very early revisions of the LinkSys LNE100TX and Matrox FastNIC. +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Cm mediaopt +option can also be used to enable +.Cm full-duplex +operation. +Not specifying +.Cm full-duplex +implies +.Cm half-duplex +mode. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Cm mediaopt +option can also be used to enable +.Cm full-duplex +operation. +Not specifying +.Cm full-duplex +implies +.Cm half-duplex +mode. +.El +.Pp +The +.Nm +driver supports the following media options: +.Pp +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +The interface will operate in +half duplex mode if this media option is not specified. +.El +.Pp +Note that the 100baseTX media type may not be available on certain +Intel 21143 adapters which support 10Mbps media attachments only. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for the following chipsets: +.Pp +.Bl -bullet -compact +.It +DEC/Intel 21143 +.It +ADMtek AL981 Comet, AN985 Centaur, ADM9511 Centaur II and ADM9513 +Centaur II +.It +ASIX Electronics AX88140A and AX88141 +.It +Conexant LANfinity RS7112 (miniPCI) +.It +Davicom DM9009, DM9100, DM9102 and DM9102A +.It +Lite-On 82c168 and 82c169 PNIC +.It +Lite-On/Macronix 82c115 PNIC II +.It +Macronix 98713, 98713A, 98715, 98715A, 98715AEC-C, 98725, 98727 and 98732 +.It +Xircom X3201 (cardbus only) +.El +.Pp +The +following NICs are known to work with the +.Nm +driver at this time: +.Pp +.Bl -bullet -compact +.It +3Com OfficeConnect 10/100B (ADMtek AN985 Centaur-P) +.It +Abocom FE2500 +.It +Accton EN1217 (98715A) +.It +Accton EN2242 MiniPCI +.It +Adico AE310TX (98715A) +.It +Alfa Inc GFC2204 (ASIX AX88140A) +.It +Built in 10Mbps only Ethernet on Compaq Presario 7900 series +desktops (21143, non-MII) +.It +Built in Sun DMFE 10/100 Mbps Ethernet on Sun Netra X1 and Sun Fire V100 +(DM9102A, MII) +.It +Built in Ethernet on LinkSys EtherFast 10/100 Instant GigaDrive (DM9102, MII) +.It +CNet Pro110B (ASIX AX88140A) +.It +CNet Pro120A (98715A or 98713A) and CNet Pro120B (98715) +.It +Compex RL100-TX (98713 or 98713A) +.It +D-Link DFE-570TX (21143, MII, quad port) +.It +Digital DE500-BA 10/100 (21143, non-MII) +.It +ELECOM Laneed LD-CBL/TXA (ADMtek AN985) +.It +Hawking CB102 CardBus +.It +IBM EtherJet Cardbus Adapter +.It +Intel PRO/100 Mobile Cardbus (versions that use the X3201 chipset) +.It +Jaton XpressNet (Davicom DM9102) +.It +Kingston KNE100TX (21143, MII) +.It +Kingston KNE110TX (PNIC 82c169) +.It +LinkSys LNE100TX (PNIC 82c168, 82c169) +.It +LinkSys LNE100TX v2.0 (PNIC II 82c115) +.It +LinkSys LNE100TX v4.0/4.1 (ADMtek AN985 Centaur-P) +.It +Matrox FastNIC 10/100 (PNIC 82c168, 82c169) +.It +Melco LGY-PCI-TXL +.It +Microsoft MN-120 10/100 CardBus (ADMTek Centaur-C) +.It +Microsoft MN-130 10/100 PCI (ADMTek Centaur-P) +.It +NDC SOHOware SFA110A (98713A) +.It +NDC SOHOware SFA110A Rev B4 (98715AEC-C) +.It +NetGear FA310-TX Rev.\& D1, D2 or D3 (PNIC 82c169) +.It +Netgear FA511 +.It +PlaneX FNW-3602-T (ADMtek AN985) +.It +SMC EZ Card 10/100 1233A-TX (ADMtek AN985) +.It +SVEC PN102-TX (98713) +.It +Xircom Cardbus Realport +.It +Xircom Cardbus Ethernet 10/100 +.It +Xircom Cardbus Ethernet II 10/100 +.El +.Sh NOTES +On sparc64 the +.Nm +driver respects the +.Va local-mac-address? +system configuration variable for the built in Sun DMFE 10/100 Mbps Ethernet +interfaces on Sun Netra X1 and Sun Fire V100. +This system configuration variable can be set in the Open Firmware boot +monitor using the +.Ic setenv +command or by +.Xr eeprom 8 . +If set to +.Dq Li false +(the default), the +.Nm +driver will use the system's default MAC address for both of the built in +devices. +If set to +.Dq Li true , +the unique MAC address of each interface is used rather than the system's +default MAC address. +.Sh DIAGNOSTICS +.Bl -diag +.It "dc%d: couldn't map ports/memory" +A fatal initialization error has occurred. +.It "dc%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "dc%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, but the device failed to acknowledge the transmission +before a timeout expired. +This can happen if the device is unable +to deliver interrupts for some reason, of if there is a problem with +the network connection (cable or network equipment) that results in a loss +of link. +.It "dc%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "dc%d: TX underrun -- increasing TX threshold" +The device generated a transmit underrun error while attempting to +DMA and transmit a packet. +This happens if the host is not able to +DMA the packet data into the NIC's FIFO fast enough. +The driver +will dynamically increase the transmit start threshold so that +more data must be DMAed into the FIFO before the NIC will start +transmitting it onto the wire. +.It "dc%d: TX underrun -- using store and forward mode" +The device continued to generate transmit underruns even after all +possible transmit start threshold settings had been tried, so the +driver programmed the chip for store and forward mode. +In this mode, +the NIC will not begin transmission until the entire packet has been +transfered into its FIFO memory. +.It "dc%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 a 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 eeprom 8 , +.Xr ifconfig 8 +.Rs +.%T ADMtek AL981, AL983 and AL985 data sheets +.%O http://www.admtek.com.tw +.Re +.Rs +.%T ASIX Electronics AX88140A and AX88141 data sheets +.%O http://www.asix.com.tw +.Re +.Rs +.%T Davicom DM9102 data sheet +.%O http://www.davicom8.com +.Re +.Rs +.%T Intel 21143 Hardware Reference Manual +.%O http://developer.intel.com +.Re +.Rs +.%T Macronix 98713/A, 98715/A and 98725 data sheets +.%O http://www.macronix.com +.Re +.Rs +.%T Macronix 98713/A and 98715/A app notes +.%O http://www.macronix.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq wpaul@ee.columbia.edu . +.Sh BUGS +The Macronix application notes claim that in order to put the +chips in normal operation, the driver must write a certain magic +number into the CSR16 register. +The numbers are documented in +the app notes, but the exact meaning of the bits is not. +.Pp +The 98713A seems to have a problem with 10Mbps full duplex mode. +The transmitter works but the receiver tends to produce many +unexplained errors leading to very poor overall performance. +The +98715A does not exhibit this problem. +All other modes on the +98713A seem to work correctly. +.Pp +The original 82c168 PNIC chip has built in NWAY support which is +used on certain early LinkSys LNE100TX and Matrox FastNIC cards, +however it is horribly broken and difficult to use reliably. +Consequently, autonegotiation is not currently supported for this +chipset: the driver defaults the NIC to 10baseT half duplex, and it is +up to the operator to manually select a different mode if necessary. +(Later cards use an external MII transceiver to implement NWAY +autonegotiation and work correctly.) +.Pp +The +.Nm +driver programs 82c168 and 82c169 PNIC chips to use the store and +forward setting for the transmit start threshold by default. +This +is to work around problems with some NIC/PCI bus combinations where +the PNIC can transmit corrupt frames when operating at 100Mbps, +probably due to PCI DMA burst transfer errors. +.Pp +The 82c168 and 82c169 PNIC chips also have a receiver bug that +sometimes manifests during periods of heavy receive and transmit +activity, where the chip will improperly DMA received frames to +the host. +The chips appear to upload several kilobytes of garbage +data along with the received frame data, dirtying several RX buffers +instead of just the expected one. +The +.Nm +driver detects this condition and will salvage the frame; however, +it incurs a serious performance penalty in the process. +.Pp +The PNIC chips also sometimes generate a transmit underrun error when +the driver attempts to download the receiver filter setup frame, which +can result in the receive filter being incorrectly programmed. +The +.Nm +driver will watch for this condition and requeue the setup frame until +it is transfered successfully. +.Pp +The ADMtek AL981 chip (and possibly the AN985 as well) has been observed +to sometimes wedge on transmit: this appears to happen when the driver +queues a sequence of frames which cause it to wrap from the end of the +transmit descriptor ring back to the beginning. +The +.Nm +driver attempts to avoid this condition by not queuing any frames past +the end of the transmit ring during a single invocation of the +.Fn dc_start +routine. +This workaround has a negligible impact on transmit performance. |