Move everything from /var/adm to /var/log

[unleashed.git] / share / man / man7d / eri.7d

'\" te
.\"  Copyright (c) 2000, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ERI 7D "Mar 1, 2000"
.SH NAME
eri \- eri Fast-Ethernet device driver
.SH SYNOPSIS
.LP
.nf
\fB/dev/eri\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBeri\fR Fast Ethernet driver is a multi-threaded, loadable, clonable,
\fBSTREAMS\fR\(embased hardware driver supporting the connectionless Data Link
Provider Interface \fBdlpi\fR(7P) over an \fBeri\fR Fast-Ethernet controller.
Multiple \fBeri\fR devices installed within the system are supported by the
driver.
.sp
.LP
The \fBeri\fR driver provides basic support for the \fBeri\fR hardware and
handles the \fBeri\fR device. Functions include chip initialization, frame
transit and receive, multicast and promiscuous support, and error recovery and
reporting.
.sp
.LP
The \fBeri\fR device provides 100Base-TX networking interfaces using the SUN
\fBRIO\fR \fBASIC\fR and an internal transceiver. The \fBRIO\fR \fBASIC\fR
provides the \fBPCI\fR interface and \fBMAC\fR functions. The physical layer
functions are provided by the internal transceiver which connects to a RJ-45
connector.
.sp
.LP
The 100Base-TX standard specifies an auto-negotiation protocol to automatically
select the mode and speed of operation. The internal transceiver is capable of
performing auto-negotiation using the remote-end of the link (link partner) and
receives the capabilities  of the remote end. It selects the  highest common
denominator mode of operation based on the priorities. It also supports a
forced-mode of operation under which the driver selects the mode of operation.
.SH APPLICATION PROGRAMMING INTERFACE
.sp
.LP
The cloning character-special device  \fB/dev/eri\fR is used to access all
\fBeri\fR controllers installed within the system.
.SS "eri and DLPI"
.sp
.LP
The  \fBeri\fR driver is a "style 2" Data Link Service provider. All
\fBM_PROTO\fR and \fBM_PCPROTO\fR type messages are interpreted as \fBDLPI\fR
primitives. Valid \fBDLPI\fR primitives are defined in \fB<sys/dlpi.h>.\fR
Refer to \fBdlpi\fR(7P) for more information.
.sp
.LP
An explicit \fBDL_ATTACH_REQ\fR message by the user is required to associate
the opened stream with a particular device (\fBppa\fR). The \fBppa\fR ID is
interpreted as an \fBunsigned integer\fR data type and indicates the
corresponding device instance (unit) number. An error (\fBDL_ERROR_ACK\fR) is
returned by the driver if the \fBppa\fR field value does not correspond to a
valid device instance number for this system. The device is initialized on
first attach and de-initialized (stopped) at last detach.
.sp
.LP
The values returned by the driver in the \fBDL_INFO_ACK\fR primitive in
response to the \fBDL_INFO_REQ\fR from the user are as follows:
.RS +4
.TP
.ie t \(bu
.el o
The maximum \fBSDU\fR is \fB1500\fR (\fBETHERMTU\fR - defined in
\fB<sys/ethernet.h>\fR ).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The minimum \fBSDU\fR is \fB0\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBdlsap\fR address length is \fB8\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBMAC\fR type is \fBDL_ETHER\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBsap\fR length values is \fB-2\fR, meaning the physical address component
is followed immediately  by a 2 byte \fBsap\fR component within the \fBDLSAP\fR
address.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The service mode is \fBDL_CLDLS\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Optional quality of service (\fBQOS\fR) is not currently supported so
\fBQOS\fR fields are \fB0\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The provider style is \fBDL_STYLE\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The version is \fBDL_VERSION_2\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The broadcast address value is Ethernet/IEEE broadcast address
(\fB0xFFFFFF\fR).
.RE
.sp
.LP
Once in the \fBDL_ATTACHED\fR state, the user must send a \fBDL_BIND_REQ\fR to
associate a particular \fBSAP\fR (Service Access Pointer) with the stream. The
\fBeri\fR driver interprets the \fBsap\fR field within the \fBDL_BIND_REQ\fR as
an Ethernet "type," therefore valid values for the \fBsap\fR field are in the
[\fB0\fR-\fB0xFFFF\fR] range.  Only one Ethernet type can be bound to the
stream at any time.
.sp
.LP
If the user selects a \fBsap\fR with a value of \fB0\fR, the receiver will be
in IEEE 802.3 mode. All frames received from the media having a Ethernet type
field in the range [\fB0\fR-\fB1500\fR] are assumed to be 802.3 frames and are
routed up all open Streams which are bound to \fBsap\fR value \fB0\fR. If more
than one Stream is in 802.3 mode, the frame will be duplicated and routed up
multiple Streams as \fBDL_UNITDATA_IND\fR messages.
.sp
.LP
In transmission, the driver checks the \fBsap\fR field of the \fBDL_BIND_REQ\fR
to determine if the value is \fB0\fR or if the Ethernet type field is in the
range [\fB0\fR-\fB1500\fR]. If either is true, the driver computes the length
of the message, not including initial \fBM_PROTO\fR mblk (message block), of
all subsequent \fBDL_UNITDATA_REQ\fR messages, and transmits 802.3 frames that
have this value in the \fBMAC\fR frame header length field.
.sp
.LP
The \fBeri\fR driver's \fBDLSAP\fR address format consists of the 6 byte
physical (Ethernet) address component followed immediately by the 2 byte
\fBsap\fR (type) component, producing an 8 byte \fBDLSAP\fR address.
Applications should \fInot\fR hardcode to this particular
implementation-specific \fBDLSAP\fR address format but use information returned
in the \fBDL_INFO_ACK\fR primitive to compose and decompose \fBDLSAP\fR
addresses. The \fBsap\fR length, full \fBDLSAP\fR length, and
\fBsap\fR/physical ordering are included within the \fBDL_INFO_ACK.\fR The
physical address length can be computed by subtracting the \fBsap\fR length
from the full \fBDLSAP\fR address length or by issuing the
\fBDL_PHYS_ADDR_REQ\fR to obtain the current physical address associated with
the stream.
.sp
.LP
Once in the \fBDL_BOUND\fR state, the user may transmit frames on the Ethernet
by sending \fBDL_UNITDATA_REQ\fR messages to the \fBeri\fR driver. The
\fBeri\fR driver will route received Ethernet frames up all open and bound
streams having a \fBsap\fR which matches the Ethernet type as
\fBDL_UNITDATA_IND\fR messages.  Received Ethernet frames are duplicated and
routed up multiple open streams if necessary. The \fBDLSAP\fR address contained
within the \fBDL_UNITDATA_REQ\fR and \fBDL_UNITDATA_IND\fR messages consists of
both the \fBsap\fR (type) and physical (Ethernet) components.
.SS "eri Primitives"
.sp
.LP
In addition to the mandatory connectionless \fBDLPI\fR message set, the driver
also supports the following primitives:
.sp
.LP
The \fBDL_ENABMULTI_REQ\fR and \fBDL_DISABMULTI_REQ\fR primitives
enable/disable reception of individual multicast group addresses. A set of
multicast addresses may be iteratively created and modified on a per-stream
basis using these primitives. These primitives are accepted by the driver in
any state following \fBDL_ATTACHED\fR.
.sp
.LP
The \fBDL_PROMISCON_REQ\fR and \fBDL_PROMISCOFF_REQ\fR primitives with the
\fBDL_PROMISC_PHYS\fR flag set in the \fBdl_level\fR field enables/disables
reception of all promiscuous mode frames on the media, including frames
generated by the local host. When used with the \fBDL_PROMISC_SAP\fR flag set,
this enables/disables reception of all \fBsap\fR (Ethernet type) values. When
used with the \fBDL_PROMISC_MULTI\fR flag set, this enables/disables reception
of all multicast group addresses. The effect of each is always on a per-stream
basis and independent of the other \fBsap\fR and physical level configurations
on this stream or other streams.
.sp
.LP
The \fBDL_PHYS_ADDR_REQ\fR primitive returns the 6 octet Ethernet address
currently associated (attached) to the stream in the \fBDL_PHYS_ADDR_ACK\fR
primitive.  This primitive is valid only in states following a successful
\fBDL_ATTACH_REQ\fR.
.sp
.LP
The \fBDL_SET_PHYS_ADDR_REQ\fR primitive changes the 6 octet Ethernet address
currently associated (attached) to this stream. The credentials of the process
which originally opened this stream must be superuser, or \fBEPERM\fR is
returned in the \fBDL_ERROR_ACK\fR. This primitive is destructive because it
affects all current and future streams attached to this device. An \fB
M_ERROR\fR is sent up all other streams attached to this device when this
primitive is successful on this stream. Once changed, all streams subsequently
opened and attached to this device will obtain this new physical address.  Once
changed, the physical address will remain until this primitive is used to
change the physical address again or the system is rebooted, whichever comes
first.
.SS "eri DRIVER"
.sp
.LP
By default, the eri driver performs auto-negotiation to  select the mode and
speed of the link, which can be in one of the  following modes, as described in
the 100Base-TX standard:
.RS +4
.TP
.ie t \(bu
.el o
100 Mbps, full-duplex
.RE
.RS +4
.TP
.ie t \(bu
.el o
100 Mbps, half-duplex
.RE
.RS +4
.TP
.ie t \(bu
.el o
10 Mbps, full-duplex
.RE
.RS +4
.TP
.ie t \(bu
.el o
10 Mbps, half-duplex
.RE
.sp
.LP
The auto-negotiation protocol automatically selects:
.RS +4
.TP
.ie t \(bu
.el o
Operation mode (half-duplex or full-duplex)
.RE
.RS +4
.TP
.ie t \(bu
.el o
Speed (100 Mbps or 10 Mbps)
.RE
.sp
.LP
The auto-negotiation protocol does the following:
.RS +4
.TP
.ie t \(bu
.el o
Gets all modes of operation supported by the link partner
.RE
.RS +4
.TP
.ie t \(bu
.el o
Advertises its capabilities to the Link Partner
.RE
.RS +4
.TP
.ie t \(bu
.el o
Selects the highest common denominator mode of operation based on the
priorities
.RE
.sp
.LP
The internal transceiver is capable of all of the operating speeds and modes
listed above. By default, auto-negotiation is used to select the speed and the
mode of the link and the common mode of operation with the link partner.
.sp
.LP
For users who want to select the speed and mode of  the link, the \fBeri\fR
device supports programmable \fBIPG\fR (Inter-Packet Gap) parameters \fBipg1\fR
and  \fBipg2\fR. Sometimes, the user may want to alter these values depending
on whether the driver supports 10 Mbps or 100 Mbps and accordingly, \fBIPG\fR
will be set to 9.6 or 0.96 microseconds.
.SS "eri Parameter List"
.sp
.LP
The \fBeri\fR driver provides for setting and getting various parameters for
the  \fBeri\fR device. The parameter list includes current transceiver status,
current link status, inter-packet gap, local transceiver capabilities and link
partner capabilities.
.sp
.LP
The local transceiver has two set of capabilities: one set reflects  hardware
capabilities, which are  read-only \fB(RO)\fR parameters. The second set
reflects the values chosen by the user and is used in speed selection and
possess read/write \fB(RW)\fR capability. At boot time, these two sets of
capabilities will be the same. Because the current default value of these
parameters can only be read and not modified, the link partner capabilities are
also read only.
.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/eri\fR \fR
.ad
.RS 28n
\fBeri\fR special character device.
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/eri.conf\fR \fR
.ad
.RS 28n
 System wide default device driver properties
.RE

.sp
.ne 2
.na
\fB\fB/kernel/drv/sparcv9/eri\fR \fR
.ad
.RS 28n
 64 bit device driver
.RE

.SH SEE ALSO
.sp
.LP
\fBndd\fR(8), \fBnetstat\fR(8), \fBdriver.conf\fR(4), \fBhme\fR(7D),
\fBqfe\fR(7d), \fBdlpi\fR(7P)