.\" All Rights Reserved, Copyright (C) Fujitsu Limited 1995
.\"
.\" This document may be used, modified, copied, distributed, and sold, in
.\" both source and printed form provided that the above copyright, these
.\" terms and the following disclaimer are retained.  The name of the author
.\" and/or the contributor may not be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" THIS DOCUMENT IS PROVIDED BY THE AUTHOR AND THE CONTRIBUTOR ``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 AUTHOR OR THE CONTRIBUTOR 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 DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" Contributed by M.S. <seki@sysrap.cs.fujitsu.co.jp>
.\" for fe driver version 0.8
.\"
.\"	$Id: fe.4,v 1.2 1996/02/11 22:37:34 mpp Exp $
.Dd April 23, 1995
.Dt FE 4
.Sh NAME
.Nm fe
.Nd Fujitsu MB86960A/MB86965A based Ethernet adapters
.Sh SYNOPSIS
.Cm "device fe0 at isa? port ? net irq ? vector feintr"
.Sh DESCRIPTION
The
.Nm fe
is a network device driver
for Fujitsu MB86960A/MB86965A based Ethernet adapters.
.Pp
Performance decline to support multicast is kept minimum
by the assistance of multicast address filter hardware
built in the chip.
The driver also supports duplex operation.
.Pp
The driver provides automatic I/O port address configuration and
automatic IRQ configuration,
when used with suitable adapter hardware.
.Pp
The driver works with program I/O data transfer technique.
It gives a fair performance.
Shared memory is never used, even if the adapter has one.
.Pp
It currently works with Fujitsu FMV-180 series for ISA,
and Allied-Telesis AT1700 series and RE2000 series for ISA.
.Ss Parameters
On the kernel configuration file, two parameters,
.Ar port
and
.Ar irq ,
must be specified to reflect adapter hardware settings.
Another parameter
.Ar flags
can be specified to provide additional configuration as an option.
Other parameters of the device statement
must appear as described on the synopsis.
.Pp
The
.Ar port
parameter specifies a base I/O port address of the adapter.
It must match with the hardware setting of the adapter.
The
.Ar port
may be a left unspecified as
.Dq Li \&? .
In that case, the driver tries to detect the hardware setting
of the I/O address automatically.
This feature may not work with some adapter hardware.
.Pp
The
.Ar irq
parameter specifies an IRQ number used by the adapter.
It must match the hardware setting of the adapter.
.Ar Irq
may be left unspecified as
.Dq Li \&? ;
in that case, the driver tries to detect
the hardware setting of the IRQ automatically.
This feature may not work on some adapters.
.Pp
The
.Ar flags
is a numeric value which consists of a combination of various device settings.
The following flags are defined in the current version.
To specify two or more settings for a device,
use a numeric sum of each flag value.
Flag bits not specified below are reserved and must be set to 0.
Actually, each bit is either just ignored by the driver,
or tested and used to control undocumented features of the driver.
Consult the source program for undocumented features.
.Bl -tag -width "99999999"
.It Li 0x007F
These flag bits are used
to initialize DLCR6 register of MB86960A/MB86965A chip,
when the
.Li 0x0080
bit of the
.Ar flags
is set.
See below for more about DLCR6 override feature.
The
.Li 0x007F
flag bits must be 0 unless the
.Li 0x0080
bit is set,
to maintain the compatibility with future versions of the driver.
.It Li 0x0080
This flag overrides the default setting to the DLCR6 register
of MB86960A/MB86965A chip by a user supplied value,
which is taken from the lower 7 bits of the flag value.
This is a troubleshooting flag and should not be used
without understanding of the adapter hardware.
Consult the Fujitsu manual for more information
on DLCR6 settings.
.El
.Sh OPTIONS
The
.Nm fe
driver has some private options,
which can be specified with an
.Dq option
statement in the kernel configuration file.
The following lists the private options.
The driver also accepts some other undocumented options,
all of whose names start with a fixed prefix
.Dv "FE_" .
Consult the source program for undocumented options.
.Bl -tag -width "FE_"
.It Dv "FE_DEBUG=" Ns Ar level
This option takes a numeric value
.Ar level
which controls the debugging level for the device and/or the driver.
Setting the
.Dv "FE_DEBUG"
option to a value which is not listed here
may cause undocumented behavior.
The default setting of this option varies from version to version.
For version 0.8, the default is 1.
.Bl -bullet
.It
Setting
.Dv "FE_DEBUG=0"
makes most of debugging codes,
including sanity check,
be excluded from the object code of the driver.
It generates fastest and smallest object code.
Some emergency messages are logged even under this setting, though.
.It
Setting
.Dv "FE_DEBUG=1"
makes minimum debugging codes be included,
setting the amount of logged messages minimum.
Only fatal error messages are logged under this setting.
.It
Setting
.Dv "FE_DEBUG=2"
makes standard debugging codes be included,
setting the amount of logged messages middle.
Messages on lair events and/or questionable conditions
are logged under this setting.
.It
Setting
.Dv "FE_DEBUG=3"
makes all debugging codes be included,
and set the amount of legged messages maximum.
Redundant messages such as those reporting usual actions
or dumping register values
are logged under this setting.
.El
.El
.Sh HARDWARE DEPENDENCY
The
.Nm fe
driver has some features and limitations which depend on adapter hardwares.
The following is a summary of such dependency.
.Ss Fujitsu FMV-180 series adapters
Both automatic IRQ detection and automatic I/O port address detection
is available with these adapters.
.Pp
Automatic I/O port address detection feature works
even if there are two or more FMV-180 cards in a system.
It is recomended to use
.Nm port ?
always.
.Pp
The hardware setting of IRQ is always taken from the configuration EEPROM
on the adapter.
The user-specified IRQ is never used if the
.Nm fe
driver is configured for FMV-180.
.Ss Allied-Telesis AT1700 series and RE2000 series adapters
Automatic I/O port address detection
is available with these adapters.
Automatic IRQ detection is also available with a limitation.
.Pp
Automatic I/O port address detection feature works
even if there are two or more AT1700 and/or RE2000 cards in a system.
It is recomended to use
.Nm port ?
always.
.Pp
The
.Nm fe
driver
tries to get IRQ setting from the configuration EEPROM on the board,
if
.Dq irq \&?
is specified in the configuration file.
Unfortunately,
AT1700 series and RE2000 series seems to have two types of models;
One type allows IRQ selection from 3/4/5/9,
while the other from 10/11/12/15.
Identification of the models are not well known.
Hence, automatic IRQ detection with Allied-Telesis adapters
may not be reliable.
Specify exact IRQ number if any troubles are encoutered.
.Pp
All of AT1700/RE2000 type adapters are reported as just
.Sq AT1700
by the driver.
Differences between AT1700 series and RE2000 series
or minor models in those series are not recognized.
.Pp
Support of this hardware is still under development.
It may or may not work.
.Sh DIAGNOSTICS
.Ss Level 0 messages
The following messages will be reported when
.Dv "FE_DEBUG"
option is set to 0.
.Bl -diag
.It "address %s, type %s"
The message shows an Ethernet station address and an adapter type.
This is a normal message.
.El
.Ss Level 1 messages
The following messages, as well as level 0 messages,
will be reported when
.Dv "FE_DEBUG"
option is set to 1.
.Bl -diag
.It "transmission timeout (%d+%d)"
The driver had passed one or more out-going packets to the MB86960A/MB86965A
to transmit,
but the chip did not respond in an appropriate time limit.
This may be an indication of an inappropriate hardware installation,
e.g., wrong IRQ setting.
.It "transmission timeout (%d+%d) when down"
The kernel informed
.Nm fe
a transmittion timeout condition,
when the device was not working.
This may be an indication of a serious bug.
.It "init() without any address"
The driver has been started,
but no valid network address has been set.
.It "invalid station address (%s)"
The driver found its own Ehternet station address is invalid,
i.e., it was either broadcast address, multicast address, or
of null-vendor.
This may be a result of an attempt to set such address through
some
.Fn ioctl
calls.
.It "cannot empty receive buffer"
When starting up,
.Nm fe
tries to clean out everything in the packet receive buffer memory.
This message indicates a failure to do so.
This can only be caused by a driver bug and/or a broken hardware.
.It "inconsistent txb variables (%d, %d)"
The driver found some internal buffer management variables in
contradicting states.
This is an indication of a driver bug.
.It "transmitter idle with %d buffered packets"
The driver found that the transmitter part of the MB86960A/MB86965A
was not working,
while one or more outgoing packets were queued.
This message suggests a bug in the
.Nm fe
driver, or a bug in the other part of the kernel,
such as another device driver,
breaking work space of the
.Nm fe
driver.
It may be better to reboot the system as soon as possible,
if the message is reported.
.It "got a partial packet (%u bytes) to send"
An upper layer program passed a very short
(shorter than an Ethernet header)
packet to the device.
It must be a bug in kernel network program.
.It "got a big packet (%u bytes) to send"
An upper layer program passed a packet
longer than what allowed in Etherenet specification to send.
It must be a bug in kernel network program.
.El
.Ss Level 2 messages
The following messages, as well as level 0 and 1 messages,
will be reported when
.Li "FE_DEBUG"
option is set to 2.
.Bl -diag
.It "if_fe.c ver. 0.8 / if_fereg.h ver. 0.8"
It shows versions of the driver source files.
This message is normal.  Just ignore it.
.It "strange TXBSIZ config; fixing"
The TXBSIZ (transmission buffer size) of the DLCR6 setting was not
appropriate for the
.Nm fe
driver.
The driver will automatically adjust the setting and keep working
even after the message is reported.
Double buffering is essential for
.Nm fe
driver to work properly,
so it must be either
.Li 01 , 10 , No or Li 11 .
This message is reported only when
.Sq Nm flags Li 0x0080
is set.
.It "excessive collision (%d/%d)"
An excessive collision error was detected on the Ethernet.
It is normal that the message is reported when the network is overloaded.
If the message appears frequently,
it may be an indication of the physical problem on the network cable.
(The two numbers appended to the end of the message
are only for debugging and should be ignored.)
.It "received a big packet? (%u bytes)"
The MB86960A/MB86965A reported a receiving of a big packet.
(A packet longer than the Ethernet limit.)
This may be a bug in the driver,
because these packets are usually thrown out by the chip.
.It "received a partial packet? (%u bytes)"
The MB86960A/MB86965A reported a receiving of a very short packet.
(A packet shorter than the Ethernet header.)
This may be a bug in the driver,
because these packets are usually ignored by the chip.
.It "received a short packet? (%u bytes)"
The MB86960A/MB86965A reported a receiving of a short packet.
.Po
A packet shorter than the Ethernet minimum, also known as a
.Dq runt .
.Pc
This may be a bug in the driver,
because these packets are usually ignored by the chip.
.It "no enough mbuf; a packet (%u bytes) dropped"
A kernel memory space called
.Sq mbuf
was exhausted,
and a received packet could not be processed.
It is normal that the message is reported when the system is overloaded.
If this message appears frequently,
it may be an indication of a bug in the driver,
or an inappropriate configuration of the kernel.
.It "packet length mismatch? (%d/%d)"
The driver got a packet to send, enclosed in an mbuf,
whose length information in the mbuf header
and actual length of the packet data disagreed.
This may be a bug in a kernel network program.
.El
.Ss Level 3 messages
More messages, as well as level 0, 1 and 2 messages,
will be reported when
.Dv "FE_DEBUG"
option is set to 3.
They are not documented, since they are for debugging purposes.
See the driver source program for level 3 messages.
.Sh SEE ALSO
.Xr netstat 1 ,
.Xr netintro 4 ,
.Xr ed 4 ,
.Xr ifconfig 8
.Sh BUGS
Following are major known bugs.
.Pp
Statistics on the number of collisions maintained by the
.Nm fe
driver may no be accurate:
the
.Fi i
option of
.Xr netstat 1
sometimes shows slightly less value than true number of collisions.
.Pp
More mbuf clusters are consumed than expected.
The packet receive routine has an intended violation
against the mbuf cluster allocation policy.
The unnecessarily allocated clusters are freed within short lifetime,
and it will not affect long term kernel memory usage.
.Sh AUTHOR, COPYRIGHT AND DISCLAIMER
.Pp
The
.Nm fe
driver is written and contributed by M.S.
.Li "<seki@sysrap.cs.fujitsu.co.jp>" ,
following the
.Nm ed
driver written by David Greenman.
This manual page is written by M.S.
.Pp
.Em "All Rights Reserved, Copyright (C) Fujitsu Limited 1995"
.Pp
This document and the assosicated software may be used, modified,
copied, distributed, and sold, in both source and binary form provided
that the above copyright, these terms and the following disclaimer are
retained.  The name of the author and/or the contributor may not be
used to endorse or promote products derived from this document and the
associated software without specific prior written permission.
.Pp
THIS DOCUMENT AND THE ASSOCIATED SOFTWARE IS PROVIDED BY THE AUTHOR
AND THE CONTRIBUTOR
.Dq 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 AUTHOR OR THE
CONTRIBUTOR 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
DOCUMENT AND THE ASSOCIATED SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Sh HISTORY
The
.Nm
driver appeared in
.Tn FreeBSD
2.1.