SunOS man pages : gld (7)
Devices 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 Inter-
face (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 require-
ments 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 func-
tionality 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 per-
form 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.
SunOS 5.8 Last change: 25 Jan 1999 1
Devices gld(7D)
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 pro-
cessing. Ethernet V2 enables a data link service user to
access and use any of a variety of conforming data link ser-
vice 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 for-
mat. 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
SunOS 5.8 Last change: 25 Jan 1999 2
Devices gld(7D)
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 deter-
mines 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 infor-
mation 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 recog-
nizes 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 intero-
perate 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 Physi-
cal 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 particu-
lar PPA based on the major/minor device that has been
opened. The Style 2 provider requires the DLS user to expli-
citly 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.
SunOS 5.8 Last change: 25 Jan 1999 3
Devices gld(7D)
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:
o The version is DL_VERSION_2.
o The service mode is DL_CLDLS - GLD implements
connectionless-mode service.
o The provider style is DL_STYLE1 or DL_STYLE2, depend-
ing on how the stream was opened.
o 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 pro-
viders to identify the physical medium over which the com-
munication will transpire. Upon completion, the state
changes from DL_UNATTACHED to DL_UNBOUND. The message con-
sists 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 prim-
itives. The stream must be attached to a PPA for these prim-
itives to be accepted.
The DL_PROMISCON_REQ and DL_PROMISCOFF_REQ primitives enable
and disable promiscuous mode on a per-stream basis, either
SunOS 5.8 Last change: 25 Jan 1999 4
Devices gld(7D)
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 con-
nectionless transfer. Because this is an unacknowledged ser-
vice, there is no guarantee of delivery. The message con-
sists 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 subse-
quently 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 physi-
cal 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 applica-
tions, 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 promis-
cuous 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
SunOS 5.8 Last change: 25 Jan 1999 5
Devices gld(7D)
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 inter-
face (64 bits).
obytes
Total bytes requested to be transmitted on the inter-
face.
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, includ-
ing group and functional addresses (long).
SunOS 5.8 Last change: 25 Jan 1999 6
Devices gld(7D)
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 statis-
tics.
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
SunOS 5.8 Last change: 25 Jan 1999 7
Devices gld(7D)
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 col-
lision.
multi_collisions
Packets successfully transmitted with multiple colli-
sions.
sqe_errors
Times SQE test error was reported.
macxmt_errors
Packets encountering transmit MAC failures, except
SunOS 5.8 Last change: 25 Jan 1999 8
Devices gld(7D)
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 recog-
nized an error condition that needed a token transmit-
ted.
freq_errors
Times the frequency of the incoming signal differed
from the expected frequency.
SunOS 5.8 Last change: 25 Jan 1999 9
Devices gld(7D)
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 Opera-
tional'' state.
FILES
/kernel/misc/gld
loadable kernel module
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Architecture | IA |
|_____________________________|_____________________________|
SEE ALSO
attributes(5), dlpi(7P), attach(9E), open(9E), kstat(9S),
kstat(7D).
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.
SunOS 5.8 Last change: 25 Jan 1999 10
Devices gld(7D)
Promiscuous mode may only be entered by Streams that are
attached to a PPA.
SunOS 5.8 Last change: 25 Jan 1999 11
|
 |
|
|
