451 lines
14 KiB
Groff
451 lines
14 KiB
Groff
.\" 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 Mt 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.
|