/share/man/man4/dc.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 450 lines · 450 code · 0 blank · 0 comment · 23 complexity · a3068a9552e029e656c81ecdfeec3efd MD5 · raw file
- .\" 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 October 24, 2011
- .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 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:
- .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:
- .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
- ALi/ULi M5261 and M5263
- .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
- transferred 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 vlan 4 ,
- .Xr eeprom 8 ,
- .Xr ifconfig 8
- .Rs
- .%T ADMtek AL981, AL983 and AL985 data sheets
- .%U http://www.admtek.com.tw
- .Re
- .Rs
- .%T ASIX Electronics AX88140A and AX88141 data sheets
- .%U http://www.asix.com.tw
- .Re
- .Rs
- .%T Davicom DM9102 data sheet
- .%U http://www.davicom.com.tw/userfile/24247/DM9102H-DS-F01-021508.pdf
- .Re
- .Rs
- .%T Intel 21143 Hardware Reference Manual
- .%U http://developer.intel.com
- .Re
- .Rs
- .%T Macronix 98713/A, 98715/A and 98725 data sheets
- .%U http://www.macronix.com
- .Re
- .Rs
- .%T Macronix 98713/A and 98715/A app notes
- .%U 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 transferred 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.