.\"	$OpenBSD: en.4,v 1.3 1999/05/16 19:57:27 alex Exp $
.\"	$NetBSD: en.4,v 1.3 1996/03/03 17:13:32 thorpej Exp $
.\"
.\" Copyright (c) 1983, 1991 The Regents of the University of California.
.\" 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 the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
.\"
.\"     from: @(#)en.4	6.5 (Berkeley) 3/27/91
.\"
.Dd March 27, 1991
.Dt EN 4 vax
.Os BSD 4.2
.Sh NAME
.Nm en
.Nd Xerox 3 Mb/s Ethernet interface
.Sh SYNOPSIS
.Cd "device en0 at uba0 csr 161000 vector enrint enxint encollide"
.Sh DESCRIPTION
The
.Nm en
interface provides access to a 3 Mb/s Ethernet network.
Due to limitations in the hardware,
.Tn DMA
transfers
to and from the network must take place in the lower 64K bytes
of the
.Tn UNIBUS
address space, and thus this must be among the first
.Tn UNIBUS
devices enabled after boot.
.Pp
Each of the host's network addresses
is specified at boot time with an
.Dv SIOCSIFADDR
.Xr ioctl 2 .
The station address is discovered by probing the on-board Ethernet
address register, and is used to verify the protocol addresses.
No packets will be sent or accepted until 
a network address is supplied.
.Pp
The interface software implements an exponential backoff algorithm
when notified of a collision on the cable.  This algorithm utilizes
a 16-bit mask and the
.Tn VAX-11 Ns 's
interval timer in calculating a series
of random backoff values.  The algorithm is as follows:
.Pp
.Bl -enum -offset indent
.It
Initialize the mask to be all 1's.
.It
If the mask is zero, 16 retries have been made and we give
up.
.It
Shift the mask left one bit and formulate a backoff by
masking the interval timer with the mask (this is actually
the two's complement of the value).
.It
Use the value calculated in step 3 to delay before retransmitting
the packet.
.El
.Pp
The interface handles both Internet and
.Tn NS
protocol families.
It normally tries to use a
.Dq trailer
encapsulation
to minimize copying data on input and output.
The use of trailers is negotiated with
.Tn ARP .
This negotiation may be disabled, on a per-interface basis,
by setting the
.Dv IFF_NOTRAILERS
flag with an
.Dv SIOCSIFFLAGS
.Xr ioctl .
.Sh DIAGNOSTICS
.Bl -diag
.It en%d: output error.
The hardware indicated an error on
the previous transmission.
.Pp
.It en%d: send error.
After 16 retransmissions using the
exponential backoff algorithm described above, the packet
was dropped.
.Pp
.It en%d: input error.
The hardware indicated an error
in reading a packet off the cable.
.Pp
.It en%d: can't handle af%d.
The interface was handed
a message with addresses formatted in an unsuitable address
family; the packet was dropped.
.El
.Sh SEE ALSO
.Xr inet 4 ,
.Xr netintro 4
.Sh HISTORY
The
.Nm
driver appeared in
.Bx 4.2 .
.Sh BUGS
The device has insufficient buffering to handle back to
back packets.  This makes use in a production environment
painful.
.Pp
The hardware does word at a time
.Tn DMA
without byte swapping.
To compensate, byte swapping of user data must either be done 
by the user or by the system.  A kludge to byte swap only
.Tn IP
packets is provided if the
.Dv ENF_SWABIPS
flag is defined in
the driver and set at boot time with an 
.Dv SIOCSIFFLAGS 
.Xr ioctl .