gld(7D) (man pages section 7: Device and Network Interfaces)

man pages section 7: Device and Network Interfaces

gld(7D)

NAME

gld- Generic LAN Driver

SYNOPSIS

#include <sys/stropts.h>

#include <sys/stream.h>

#include <sys/dlpi.h>

#include <sys/gld.h>

DESCRIPTION

GLD is a multi-threaded, clonable, loadable kernel module providing support for Solaris Local Area Network device drivers.

Local Area Network (LAN) device drivers in Solaris are STREAMS-based drivers that use the Data Link Provider Interface (DLPI) to communicate with network protocol stacks. These protocol stacks use the network drivers to send and receive packets on a local area network. A network device driver, therefore, must implement and adhere to the requirements imposed by the DDI/DKI specification, the STREAMS specification, the DLPI interface specification, and the programmatic interface of the device itself.

GLD implements most of the STREAMS functions and DLPI functionality required of a Solaris LAN driver. Several Solaris network drivers are implemented using GLD.

Any Solaris network driver implemented using GLD is divided into two distinct parts: a generic part that deals with STREAMS and DLPI interfaces, and a device-specific part that deals with the particular hardware device. The device-specific module indicates its dependency on the GLD module and registers itself with GLD from within the driver's attach(9E) function. After the driver has been successfully loaded, it is a DLPI-compliant driver. The device-specific part of the driver calls GLD functions when it receives data or needs some service from GLD. GLD makes calls into the GLD entry points of the device-specific driver through pointers provided to GLD by the device-specific driver when it registered itself with GLD.

The GLD facility currently supports devices of type DL_ETHER, DL_TPR, and DL_FDDI. GLD drivers are expected to process fully-formed MAC-layer packets, and should not perform any Logical Link Control (LLC) handling.

In some cases it may be necessary or desirable to implement a full DLPI-compliant driver without using the GLD facility. This will be the case, for example, for devices that are not IEEE 802-style LAN devices, or where a device type or DLPI service not supported by GLD is required.

Type DL_ETHER: Ethernet V2 and 802.3

For devices designated type DL_ETHER, GLD provides support for both Ethernet V2 and IEEE 802.3 / ISO 8802-3 packet processing. Ethernet V2 enables a data link service user to access and use any of a variety of conforming data link service providers without special knowledge of the provider's protocol. A Service Access Point (SAP) is the point through which the user communicates with the service provider.

Streams bound to SAP values in the range [0-255] are treated as equivalent and denote that the user wishes to use 802.3 mode. If the value of the SAP field of the DL_BIND_REQ is within this range, GLD computes the length, not including the 14-byte MAC header, of each subsequent DL_UNITDATA_REQ message on that stream, and transmits 802.3 frames having that length in the MAC frame header type field. Such lengths will never exceed 1500.

Furthermore, all frames received from the media, having a type field in the range [0-1500], are assumed to be 802.3 frames and are routed up all open streams that are in 802.3 mode, i.e. are bound to a SAP value in the [0-255] range. If more than one stream is in 802.3 mode, the incoming frame will be duplicated and routed up each such stream.

Streams bound to SAP values > 1500 receive incoming packets whose Ethernet MAC header type value exactly matches the value of the SAP to which the Stream is bound.

Types DL_TPR and DL_FDDI: SNAP processing

For media types DL_TPR and DL_FDDI GLD implements minimal SNAP processing for any stream bound to a SAP value greater than 255. SAP values in the range [0-255] are LLC SAP values, and are carried naturally by the media packet format. However, SAP values greater than 255 require a SNAP (Sub-Net Access Protocol) header, under the LLC header, to carry the 16-bit Ethernet V2-style SAP value.

SNAP headers are carried under LLC headers with destination SAP 0xAA. For outgoing packets with SAP values greater than 255, GLD creates an LLC+SNAP header that always looks like:

``AA AA 03 00 00 00 XX XX''

where ``XX XX'' represents the 16-bit SAP, corresponding to the Ethernet V2 style ``type''. This is the only class of SNAP header supported - non-zero OUI fields, and LLC control fields other than 03, are considered to be LLC packets with SAP 0xAA. Clients wishing to use SNAP formats other than this one must use LLC and bind to SAP 0xAA.

Incoming packets are examined to ascertain whether they fall into the format specified above. Packets that do will be matched to Streams bound to the packet's 16-bit SNAP type, as well as being considered to match the LLC SNAP SAP 0xAA.

Packets received for any LLC SAP are passed up all Streams that are bound to an LLC SAP, just as described for media type DL_ETHER above.

Type DL_TPR: Source Routing

For type DL_TPR devices, GLD implements minimal support for Source Routing. Source Routing is a mechanism by which a station sending a packet across a bridged medium specifies, in the packet MAC header, Routing Information that determines the route that the packet will take through the bridged network.

Functionally, the Source Routing support provided by GLD learns routes, solicits and responds to requests for information about possible multiple routes, and selects among multiple routes available to it. It adds Routing Information Fields to the MAC headers of outgoing packets, and recognizes such fields in incoming packets.

GLD's Source Routing support does not implement the full Route Determination Entity (RDE) specified in ISO 8802-2 (IEEE 802.2) Section 9. However, it is designed to interoperate with any such implementations that may exist in the same (or a bridged) network.

Style 1 and 2 Providers

GLD implements both Style 1 and Style 2 providers. A Physical Point of Attachment (PPA) is the point at which a system attaches itself to a physical communication medium. All communication on that physical medium funnels through the PPA. The Style 1 provider attaches the stream to a particular PPA based on the major/minor device that has been opened. The Style 2 provider requires the DLS user to explicitly identify the desired PPA using DL_ATTACH_REQ. In this case, open(9E) creates a stream between the user and GLD, and DL_ATTACH_REQ subsequently associates a particular PPA with that stream. Style 2 is denoted by a minor number of zero. If a device node is opened whose minor number is not zero, that denotes Style 1, and the associated PPA is the minor number minus 1. In both Style 1 and Style 2 opens, the device is cloned.

Implemented DLPI Primitives

GLD implements the following DLPI primitives:

The DL_INFO_REQ primitive requests information about the DLPI stream. The message consists of one M_PROTO message block. GLD returns device-dependent values in the DL_INFO_ACK response to this request, based on information the GLD-based driver passed to gld_register( ). However GLD returns the following values on behalf of all GLD-based drivers:

The version is DL_VERSION_2.
The service mode is DL_CLDLS - GLD implements connectionless-mode service.
The provider style is DL_STYLE1 or DL_STYLE2, depending on how the stream was opened.
No optional Quality Of Service (QOS) support is present, so the QOS fields are zero.

The DL_ATTACH_REQ primitive is called to associate a PPA with a stream. This request is needed for Style 2 DLS providers to identify the physical medium over which the communication will transpire. Upon completion, the state changes from DL_UNATTACHED to DL_UNBOUND. The message consists of one M_PROTO message block. This request may not be issued when using the driver in Style 1 mode; streams opened using Style 1 are already attached to a PPA by the time the open completes.

The DL_DETACH_REQ primitive requests to detach the PPA from the stream. This is only allowed if the stream was opened using Style 2.

The DL_BIND_REQ and DL_UNBIND_REQ primitives bind and unbind a DLSAP to the stream. The PPA associated with each stream will have been initialized upon completion of the processing of the DL_BIND_REQ. Multiple streams may be bound to the same SAP; each such stream receives a copy of any packets received for that SAP.

The DL_ENABMULTI_REQ and DL_DISABMULTI_REQ primitives enable and 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. The stream must be attached to a PPA for these primitives to be accepted.

The DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitives enable and disable promiscuous mode on a per-stream basis, either at a physical level or at the SAP level. The DL Provider will route all received messages on the media to the DLS User until either a DL_DETACH_REQ or a DL_PROMISCOFF_REQ is received or the stream is closed. Physical level promiscuous mode may be specified for all packets on the medium, or for multicast packets only. The stream must be attached to a PPA for these primitives to be accepted.

The DL_UNITDATA_REQ primitive is used to send data in a connectionless transfer. Because this is an unacknowledged service, there is no guarantee of delivery. The message consists of one M_PROTO message block followed by one or more M_DATA blocks containing at least one byte of data.

The DL_UNITDATA_IND type is used when a packet is received and is to be passed upstream. The packet is put into an M_PROTO message with the primitive set to DL_UNITDATA_IND.

The DL_PHYS_ADDR_REQ primitive returns the MAC address, currently associated with the PPA attached to the stream, in the DL_PHYS_ADDR_ACK primitive. When using style 2, this primitive is only valid following a successful DL_ATTACH_REQ.

The DL_SET_PHYS_ADDR_REQ primitive changes the MAC address currently associated with the PPA attached to the stream. This primitive affects all other current and future streams attached to this device. Once changed, all streams subsequently opened and attached to this device will obtain this new physical address. The new physical address will remain in effect until this primitive is used to change the physical address again or the driver is reloaded. This primitive will only succeed when no Stream currently attached to the selected device is bound (i.e. using DL_BIND_REQ).

Implemented ioctl Functions

GLD implements the ioctl ioc_cmd function described below.

The DLIOCRAW ioctl function is used by some DLPI applications, most notably the snoop(1M) command. The DLIOCRAW command puts the stream into a raw mode, which, on receive, causes the the full MAC-level packet to be sent upstream in an M_DATA message instead of it being transformed into the DL_UNITDATA_IND form normally used for reporting incoming packets. Packet SAP filtering is still performed on streams that are in raw mode; if a stream user wants to receive all incoming packets it must also select the appropriate promiscuous modes. After successfully selecting raw mode, the application is also allowed to send fully formatted packets to the driver as M_DATA messages for transmission. DLIOCRAW takes no arguments. Once enabled, the stream remains in this mode until closed.

Network Statistics

Solaris network drivers must implement statistics variables. GLD itself tallies some network statistics, but other statistics must be counted by each GLD-based driver. GLD provides support for GLD-based drivers to report a standard set of network driver statistics. Statistics are reported by GLD using the kstat(7D) and kstat(9S) mechanism. All statistics are maintained as unsigned, and all are 32 bits unless otherwise noted.

GLD maintains and reports the following statistics.

rbytes64: Total bytes successfully received on the interface (64 bits).
rbytes: Total bytes successfully received on the interface.
obytes64: Total bytes requested to be transmitted on the interface (64 bits).
obytes: Total bytes requested to be transmitted on the interface.
ipackets64: Total packets successfully received on the interface (64 bits).
ipackets: Total packets successfully received on the interface.
opackets64: Total packets requested to be transmitted on the interface (64 bits).
opackets: Total packets requested to be transmitted on the interface.
multircv: Multicast packets successfully received, including group and functional addresses (long).
multixmt: Multicast packets requested to be transmitted, including group and functional addresses (long).
brdcstrcv: Broadcast packets successfully received (long).
brdcstxmt: Broadcast packets requested to be transmitted (long).
unknowns: Valid received packets not accepted by any stream.
noxmtbuf: Packets discarded on output because transmit buffer was busy, or no buffer could be allocated for transmit.
blocked: Times a received packet could not be put up a stream because the queue was flow controlled.
xmtretry: Times transmit was retried after having been delayed due to lack of resources.
promisc: Current ``promiscuous'' state of the interface.

The device dependent driver may count the following statistics.

ifspeed: Current estimated bandwidth of the interface in bits per second (64 bits).
media: Current media type in use by the device.
intr: Times interrupt handler was called and claimed the interrupt.
norcvbuf: Times a valid incoming packet was known to have been discarded because no buffer could be allocated for receive.
ierrors: Total packets received that couldn't be processed because they contained errors.
oerrors: Total packets that weren't successfully transmitted because of errors.
missed: Packets known to have been dropped by the hardware on receive.
uflo: Times FIFO underflowed on transmit.
oflo: Times receiver overflowed during receive.

The following group of statistics applies to networks of type DL_ETHER; these are maintained by device-specific drivers of that type, as above.

align_errors: Packets received with framing errors (not an integral number of octets).
fcs_errors: Packets received with CRC errors.
duplex: Current duplex mode of the interface.
carrier_errors: Times carrier was lost or never detected on a transmission attempt.
collisions: Ethernet collisions during transmit.
ex_collisions: Frames where excess collisions occurred on transmit, causing transmit failure.
tx_late_collisions: Times a transmit collision occurred late (after 512 bit times).
defer_xmts: Packets without collisions where first transmit attempt was delayed because the medium was busy.
first_collisions: Packets successfully transmitted with exactly one collision.
multi_collisions: Packets successfully transmitted with multiple collisions.
sqe_errors: Times SQE test error was reported.
macxmt_errors: Packets encountering transmit MAC failures, except carrier and collision failures.
macrcv_errors: Packets received with MAC errors, except align, fcs, and toolong errors.
toolong_errors: Packets received larger than the maximum permitted length.
runt_errors: Packets received smaller than the minimum permitted length.

The following group of statistics applies to networks of type DL_TPR; these are maintained by device-specific drivers of that type, as above.

line_errors: Packets received with non-data bits or FCS errors.
burst_errors: Times an absence of transitions for five half-bit timers was detected.
signal_losses: Times loss of signal condition on the ring was detected.
ace_errors: Times an AMP or SMP frame in which A is equal to C is equal to 0, was followed by another such SMP frame without an intervening AMP frame.
internal_errors: Times the station recognized an internal error.
lost_frame_errors: Times the TRR timer expired during transmit.
frame_copied_errors: Times a frame addressed to this station was received with the FS field A bit set to 1.
token_errors: Times the station acting as the active monitor recognized an error condition that needed a token transmitted.
freq_errors: Times the frequency of the incoming signal differed from the expected frequency.

The following group of statistics applies to networks of type DL_FDDI; these are maintained by device-specific drivers of that type, as above.

mac_errors: Frames detected in error by this MAC that had not been detected in error by another MAC.
mac_lost_errors: Frames received with format errors such that the frame was stripped.
mac_tokens: Number of tokens received (total of non-restricted and restricted).
mac_tvx_expired: Number of times that TVX has expired.
mac_late: Number of TRT expirations since this MAC was reset or a token was received.
mac_ring_ops: Number of times the ring has entered the ``Ring_Operational'' state from the ``Ring Not Operational'' state.

FILES

/kernel/misc/gld: loadable kernel module

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

`ATTRIBUTE TYPE`	`ATTRIBUTE VALUE`
Architecture	IA

WARNINGS

Contrary to the DLPI specification, GLD returns the device's correct address length and broadcast address in DL_INFO_ACK even before the stream has been attached to a PPA.

Promiscuous mode may only be entered by Streams that are attached to a PPA.

SunOS 5.8 Last Revised 25 Jan 1999