Merge commit 'b31320a79e2054c6739b5229259dbf98f3afc547' into merges

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

'\" te
.\"  Copyright (c) 1995, 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 HME 7D "Sep 5, 1995"
.SH NAME
hme \- SUNW,hme Fast-Ethernet device driver
.SH SYNOPSIS
.LP
.nf
\fB/dev/hme\fR
.fi

.SH DESCRIPTION
.sp
.LP
The  \fBSUNW,hme\fR Fast-Ethernet driver is a multi-threaded, loadable,
clonable, STREAMS hardware driver supporting the connectionless Data Link
Provider Interface, \fBdlpi\fR(7P), over a  \fBSUNW,hme\fR Fast-Ethernet
controller. The motherboard and add-in SBus \fBSUNW,hme\fR controllers of
several varieties are supported. Multiple \fBSUNW,hme\fR controllers installed
within the system are supported by the driver.
.sp
.LP
The \fBhme\fR driver provides basic support for the \fBSUNW,hme\fR hardware. It
is used to handle the  \fBSUNW,hme\fR device. Functions include chip
initialization, frame transit and receive, multicast and promiscuous support,
and error recovery and reporting. \fBSUNW,hme\fR The \fBSUNW,hme\fR device
provides 100Base-TX networking interfaces using SUN's \fBFEPS ASIC\fR and an
Internal Transceiver. The FEPS ASIC provides the Sbus interface and MAC
functions and the Physical layer functions are provided by the Internal
Transceiver which connects to a \fBRJ-45\fR connector. In addition to the RJ-45
connector, an  \fBMII\fR (Media Independent Interface) connector is also
provided on all  \fBSUNW,hme\fR devices except the  \fBSunSwith SBus adapter\fR
board. The MII interface is used to connect to an External Transceiver which
may use any physical media (copper or fiber) specified in the 100Base-TX
standard. When an External Transceiver is connected to the MII, the driver
selects the External Transceiver and disables the Internal Transceiver.
.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 doing "auto-negotiation" with the remote-end of the link (Link
Partner) and receives the capabilities  of the remote end. It selects the
\fBHighest Common Denominator\fR mode of operation based on the priorities. It
also supports  \fBforced-mode\fR of operation where the driver can select the
mode of operation.
.SH APPLICATION PROGRAMMING INTERFACE
.sp
.LP
The cloning character-special device  \fB/dev/hme\fR is used to access all
\fBSUNW,hme\fR controllers installed within the system.
.SS "hme and DLPI"
.sp
.LP
The  \fBhme\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. 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 long\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
<sys/ethernet.h> ).
.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\(mi2\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
No optional quality of service (QOS) support is included at present so the
\fBQOS\fR fields are \fB0\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The provider style is \fBDL_STYLE2.\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
\fBhme\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 "802.3 mode". All frames received from the media having a "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" then 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
if the \fBsap\fR value is \fB0\fR, and if the destination 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 MAC frame header length field.
.sp
.LP
The \fBhme\fR driver \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 \fBhme\fR driver. The
\fBhme\fR driver will route received Ethernet frames up all those 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.
.sp
.LP
In addition to the mandatory connectionless \fBDLPI\fR message set the driver
additionally supports the following primitives.
.SS "hme 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.  Otherwise \fBEPERM\fR
is returned in the \fBDL_ERROR_ACK.\fR This primitive is destructive in that it
affects all other current and future streams attached to this device. An
\fBM_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 "hme DRIVER"
.sp
.LP
By default, the hme driver performs "auto-negotiation" to  select the
\fBmode\fR and  \fBspeed\fR of the link, when the Internal Transceiver is used.
.sp
.LP
When an External Transceiver is connected to the \fBMII\fR interface, the
driver selects the External Transceiver for  networking operations. If the
External Transceiver supports "auto-negotiation", the driver uses the
auto-negotiation procedure to select the link speed and mode. If the External
Transceiver does not support auto-negotiation, it will select the highest
priority mode supported by the transceiver.
.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 link can be in one of the  \fI4\fR following modes:
.sp
.LP
These speeds and modes are described in the 100Base-TX standard.
.sp
.LP
The \fIauto\(minegotiation\fR 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\(minegotiation protocol does the following:
.RS +4
.TP
.ie t \(bu
.el o
Gets all the 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 \fIinternal\fR \fItransceiver\fR is capable of all of the operating speeds
and modes listed above. When the internal transceiver is used, by
\fIdefault\fR, 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
When an \fIexternal\fR \fItransceiver\fR is connected to the  \fBMII\fR
interface, the driver selects the external transceiver for networking
operations. If the external transceiver supports auto-negotiation:
.RS +4
.TP
.ie t \(bu
.el o
The driver uses the auto-negotiation procedure to select the link speed and
mode.
.RE
.sp
.LP
If the external transceiver  \fIdoes\fR \fInot\fR support auto-negotiation
.RS +4
.TP
.ie t \(bu
.el o
The driver selects the highest priority mode supported by the transceiver.
.RE
.sp
.LP
Sometimes, the user may want to select the speed and mode of  the link. The
\fBSUNW,hme\fR device supports programmable \fB"IPG"\fR (Inter-Packet Gap)
parameters \fBipg1\fR and  \fBipg2\fR. By default, the driver sets \fBipg1\fR
to 8  \fBbyte-times\fR and \fBipg2\fR to 4 \fBbyte-times\fR (which are the
standard values). 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 "hme Parameter List"
.sp
.LP
The hme driver provides for setting and getting various parameters for the
\fBSUNW,hme\fR device. The parameter list includes:
.br
.in +2
\fBcurrent transceiver status\fR
.in -2
.br
.in +2
\fBcurrent link status\fR
.in -2
.br
.in +2
\fBinter-packet gap\fR
.in -2
.br
.in +2
\fBlocal transceiver capabilities\fR
.in -2
.br
.in +2
\fBlink partner capabilities\fR
.in -2
.sp
.LP
The local transceiver has two set of capabilities: one set reflects the
capabilities of the \fBhardware\fR, which are  \fBread-only\fR \fB(RO)\fR
parameters and the second set reflects the values chosen by the user and is
used in  \fBspeed selection\fR. There are \fBread/write\fR \fB(RW)\fR
capabilities. At boot time, these two sets of capabilities will be the same.
The Link Partner capabilities are also read only parameters because the current
default value of these parameters can only be read and cannot be modified.
.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/hme\fR\fR
.ad
.RS 24n
\fBhme\fR special character device
.RE

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

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