Add `fe' Ethernet driver man page.

1 files changed, 436 insertions, 0 deletions

diff --git a/share/man/man4/man4.i386/fe.4 b/share/man/man4/man4.i386/fe.4
new file mode 100644
index 000000000000..aa61f9b917c6
--- /dev/null
+++ b/share/man/man4/man4.i386/fe.4
@@ -0,0 +1,436 @@
+.\" 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$
+.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 netintro 4 ,
+.Xr ed 4 ,
+.Xr ifconfig 8 ,
+.Xr netstat 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 8
+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.