'\" 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.\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\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(1M), \fBnetstat\fR(1M), \fBdriver.conf\fR(4), \fBhme\fR(7D), \fBqfe\fR(7d), \fBdlpi\fR(7P)