.\"	$NetBSD: we.4,v 1.19 2017/07/03 21:30:58 wiz Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
.\" NASA Ames Research Center.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 THE FOUNDATION OR CONTRIBUTORS
.\" 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.
.\"
.Dd March 23, 2010
.Dt WE 4
.Os
.Sh NAME
.Nm we
.Nd "Western Digital/SMC WD80x3, SMC Elite Ultra, and SMC EtherEZ Ethernet cards device driver"
.Sh SYNOPSIS
.Ss ISA boards
.Cd "we0 at isa? port 0x280 iomem 0xd0000 irq 9"
.Cd "we1 at isa? port 0x300 iomem 0xcc000 irq 10"
.Ss MCA boards
.Cd "we* at mca? slot ?"
.Ss atari
.Cd "we0 at vme0 irq 4 # SMC Elite Ultra with SMC_TT VME-ISA bridge"
.Sh DESCRIPTION
The
.Nm
device driver supports Western Digital/SMC WD80x3, SMC Elite Ultra, and
SMC EtherEZ Ethernet cards.
.Sh FLAG VALUES
For some clone boards the driver is not able to recognize 16bit or 8bit
interfaces correctly.
Since this makes a huge difference (see diagnostic section below)
you can override this by specifying flags value in the config file:
.Pp
.Cd "we2 at isa? port 0x300 iomem 0xe0000 irq 15 flags 4"
.Pp
The values to add together for flags are:
.Pp
.Bl -diag
.It 2
force adapter to be treated as 8bit, even if it probes
as a 16bit interface.
Improper use of this flag will make the driver fail or send invalid
Ethernet packets.
.It 4
force adapter to be treated as 16bit, even if it probes
as a 8bit interface.
For example the COMPEX ENT/U boards identify as WD8003 compatibles,
but are in fact 16bit cards.
Using this flag on a board that really is a 8bit board will result
in bogus packets being sent.
.It 8
disable the use of double transmit buffers to save space in
the on-board RAM for more receive buffers.
.El
.Pp
Note that all supported MCA cards are 16bit, and the SMC_TT VME-ISA bridge
interface for atari supports only SMC Elite Ultra.
.Sh MEDIA SELECTION
The ability to select media from software is dependent on the particular
model of WD/SMC card.
The following models support only manual configuration:
WD8003S, WD8003E, and WD8013EBT.
.Pp
Other WD/SMC 80x3 interfaces support two types of media on a single card.
All support the AUI media type.
The other media is either BNC or UTP behind a transceiver.
Software cannot differentiate between BNC and UTP cards.
On some models, the AUI port is always active.
.Pp
The SMC Elite Ultra and SMC EtherEZ interfaces support three media
a single card: AUI, BNC, and UTP.
If the transceiver is active, the BNC media is selected.
Otherwise, the AUI and UTP ports are both active.
.Pp
To enable the AUI media, select the
.Em 10base5
or
.Em aui
media type with
.Xr ifconfig 8 Ns 's
.Cm media
directive.
To select the other media (transceiver), select the
.Em 10base2
or
.Em bnc
media type.
.Sh DIAGNOSTICS
.Bl -diag
.It "we0: overriding IRQ <n> to <m>"
The IRQ specified in the kernel configuration file is different from that
found in the card's configuration registers.
The value in the kernel configuration file is being overridden by
the one configured into the card.
.It "we0: can't wildcard IRQ on a <model>"
The IRQ was wildcarded in the kernel configuration file, and the card is
a WD8003S, WD8003E, or WD8013EBT, which do not support software IRQ
configuration.
.It "we0: failed to clear shared memory at offset <off>"
The memory test was unable to clear the interface's shared memory
region.
This often indicates that the card is configured at a conflicting
.Em iomem
address.
.It we0: warning - receiver ring buffer overrun
The DP8390 Ethernet chip used by this board implements a shared-memory
ring-buffer to store incoming packets.
.Pp
The 16bit boards (8013 series) have 16k of memory as well as
fast memory access speed.
Typical memory access speed on these boards is about 4MB/second.
These boards generally have no problems keeping up with full Ethernet
speed and the ring-buffer seldom overfills.
.Pp
However, the 8bit boards (8003) usually have only 8k bytes of shared
memory.
This is only enough room for about 4 full-size (1500 byte) packets.
This can sometimes be a problem, especially on the original WD8003E,
because these boards' shared-memory access speed is quite slow;
typically only about 1MB/second.
The overhead of this slow memory access, and the fact that there
is only room for 4 full-sized packets means that the ring-buffer
will occasionally overrun.
When this happens, the board must be reset to avoid a lockup problem
in early revision 8390's.
Resetting the board causes all of the data in the ring-buffer to
be lost, requiring it to be retransmitted/received, congesting the
board further.
Because of this, maximum throughput on these boards is only about
400-600k per second.
.Pp
This problem is exasperated by NFS because the 8bit boards lack
sufficient memory to support the default 8k byte packets that NFS and
other protocols use as their default.
If these cards must be used with NFS, use the NFS
.Fl r
and
.Fl w
options in
.Pa /etc/fstab
to limit NFS's packet size.
4096 byte packets generally work.
.El
.Sh SEE ALSO
.Xr ifmedia 4 ,
.Xr intro 4 ,
.Xr isa 4 ,
.Xr mca 4 ,
.Xr ifconfig 8