Protocols dlpi(7P)
NAME
dlpi - Data Link Provider Interface
SYNOPSIS
#include
DESCRIPTION
SunOS STREAMS-based device drivers wishing to support the
STREAMS TCP/IP and other STREAMS-based networking protocol
suite implementations support Version 2 of the Data Link
Provider Interface (DLPI). DLPI V2 enables a data link ser-
vice user to access and use any of a variety of conforming
data link service providers without special knowledge of the
provider's protocol. Specifically, the interface is intended
to support Ethernet, X.25 LAPB, SDLC, ISDN LAPD, CSMA/CD,
FDI, token ring, token bus, Bisync, and other datalink-
level protocols.
The interface specifies access to the data link service pro-
vider in the form of MPROTO and MPCPROTO type STREAMS
messages and does not define a specific protocol implementa-
tion. The interface defines the syntax and semantics of
primitives exchanged between the data link user and the data
link provider to attach a physical device with physical-
level address to a stream, bind a datalink-level address to
the stream, get implementation-specific information from the
data link provider, exchange data with a peer data link user
in one of three communication modes (connection, connection-
less, acknowledged connectionless), enable/disable multicast
group and promiscuous mode reception of datalink frames, get
and set the physical address associated with a stream, and
several other operations.
Solaris conforms to The Open Group Technical Standard for
DLPI, Version 2. For free access to this specification,
point your browser to
www.opengroup.org/pubs/catalog/c811.htm. Solaris also pro-
vides extensions to the DLPI standard, as detailed in this
man page.
SOLARIS-SPECIFIC DLPI EXTENSIONS
Notification Support
Enables DLPI consumers to register for notification when
events of interest occur at the DLPI provider. The nego-
tiation may be performed on any attached DLPI stream,
and begins with the DLPI consumer, sending a
DLNOTIFYREQ to the provider, which is an MPROTO mes-
sage with the following payload:
SunOS 5.11 Last change: 29 Jul 2008 1
Protocols dlpi(7P)
typedef struct {
tuscalart dlprimitive;
uint32t dlnotifications;
uint32t dltimelimit;
} dlnotifyreqt;
The dlprimitive field must be set to DLNOTIFYREQ; the
dltimelimit field is reserved for future use and must
be set to zero. The dlnotifications field is a bitmask
containing the event types the consumer is interested in
receiving, and must be zero or more of:
DLNOTELINKDOWN Notify when link has gone down
DLNOTELINKUP Notify when link has come up
DLNOTEPHYSADR Notify when address changes
DLNOTESDUSIZE Notify when MTU changes
DLNOTESPED Notify when speed changes
DLNOTEPROMISCONPHYS Notify when DLPROMISCPHYS is set
DLNOTEPROMISCOFPHYS Notify when DLPROMISCPHYS is cleared
Consumers may find it useful to send a DLNOTIFYREQ
message with no requested types to check if the DLPI
provider supports the extension.
Upon receiving the DLNOTIFYREQ, the DLPI provider must
generate a DLNOTIFYACK, which is an MPROTO message
with the following payload:
typedef struct {
tuscalart dlprimitive;
uint32t dlnotifications;
} dlnotifyackt;
The dlprimitive field must be set to DLNOTIFYACK. The
dlnotifications field must include any notifications
that the provider supports, along with any other unre-
quested notifications that the provider supports. How-
ever, regardless of the notifications the provider sup-
ports, it is restricted to sending only DLNOTIFYIND
messages (see below) that were requested in the
DLNOTIFYREQ.
Since there are additional notification types which are
not yet available for public use, DLPI consumers and
providers must take care when inspecting and setting the
dlnotifications field. Specifically, consumers must be
careful to only request the above notification types,
and providers must be careful to not include any
unrecognized notification types in the dlnotifications
field when constructing the DLNOTIFYACK. In addition,
DLNOTIFYIND's that are received with undocumented
dlnotification or dldata values must be ignored.
SunOS 5.11 Last change: 29 Jul 2008 2
Protocols dlpi(7P)
DLPI consumers may receive a DLERORACK message (with
dlerrorprimitive set to DLNOTIFYREQ) in response to
the initial DLNOTIFYREQ message. This message indi-
cates that the DLPI provider does not support the DLPI
notification extension. Otherwise, the DLPI consumer
will receive a DLNOTIFYACK and should expect to
receive DLNOTIFYIND messages for any types that it
requested that were still set in it. The DLNOTIFYIND
is an MPROTO message with the following payload:
typedef struct {
tuscalart dlprimitive;
uint32t dlnotification;
uint32t dldata;
tuscalart dladdrlength;
tuscalart dladdroffset;
} dlnotifyindt;
The dlprimitive field must be set to DLNOTIFYIND, and
the dlnotification field must be set to the event type
that has occurred (for example, DLNOTELINKDOWN). Only
a single event type may be set in each DLNOTIFYIND.
For the DLNOTESPED event type, dldata must be set to
the current interface speed in kilobits per second. For
the DLNOTEPHYSADR event type, dldata must be set to
DLCURPHYSADR. For the DLNOTESDUSIZE event type,
dldata must be set to the current MTU in bytes. Other-
wise, dldata must be set to zero.
For the DLNOTEPHYSADR event type, the dladdrlength
field must be set to the length of the address, and the
dladdroffset field must be set to offset of the first
byte of the address, relative to brptr (for example, if
the address immediately follows the dlnotifyind struc-
ture, dladdroffset is set to 'sizeof
(dlnotifyind)'). For all other event types, the
dladdrlength and dladdroffset fields must be set to
zero by DLPI providers and ignored by DLPI consumers.
In addition to generating DLNOTIFYIND messages when a
requested event has occurred, the DLPI provider must
initially generate one or more DLNOTIFYIND messages to
notify the DLPI consumer of the the current state of the
interface. For instance, if the consumer has requested
DLNOTELINKUP DLNOTELINKDOWN, the provider must
send a DLNOTIFYIND containing the current state of the
link (either DLNOTELINKUP or DLNOTELINKDOWN) after
sending the DLNOTIFYACK.
For the initial DLNOTIFYIND message, the DLPI provider
is strongly recommended against sending
SunOS 5.11 Last change: 29 Jul 2008 3
Protocols dlpi(7P)
DLNOTELINKDOWN, even if the interface is still ini-
tializing and is not yet ready to send or receive pack-
ets. Instead, either delaying the DLNOTIFYIND message
until the interface is ready or optimistically reporting
DLNOTIFYLINKUP and subsequently reporting
DLNOTELINKDOWN if the negotation fails is strongly
preferred. This prevents DLNOTIFYIND consumers from
needlessly triggering network failover operations and
logging error messages during network interface initial-
ization.
The DLPI provider must continue to generate
DLNOTIFYIND messages until it receives a new
DLNOTIFYREQ message or the DLPI stream is detached (or
closed). Further, a DLPI style 2 provider must keep
track of the requested events after a DLDETACHREQ
operation, and if a subsequent DLATACHREQ is
received, it must send gratuitous DLNOTIFYIND mes-
sages to notify the consumer of the current state of
the device, since the state may have changed while
detached (or the consumer may have simply discarded its
previous state).
Passive Consumers of Aggregated Links
Solaris link aggregations as configured by dladm(1M)
export DLPI nodes for both the link aggregation, and
individual links that comprises the aggregation, to
allow observability of the aggregated links. To allow
applications such as snoop(1M) to open those individual
aggregated links while disallowing other consumers such
as ip(7P), DLPASIVEREQ (a DLPI primitive), must be
issued by snoop(1M) and similar applications.
The DLPASIVEREQ primitive is an MPROTO message con-
taining the following payload:
typedef struct {
tuscalart dlprimitive;
} dlpassivereqt;
Issuing this primitive allows the consumer of a DLPI
link to coexist with a link aggregation that also uses
the link. Such a consumer is considered "passive."
Consumers that don't use this primitive while an aggre-
gation is using the link receive DLSYSER/EBUSY when
issuing the following DLPI primitives:
DLBINDREQ
DLENABMULTIREQ
SunOS 5.11 Last change: 29 Jul 2008 4
Protocols dlpi(7P)
DLPROMISCONREQ
DLAGREQ
DLUNAGREQ
DLCONTROLREQ
DLSETPHYSADREQ
A consumer that has not issued a DLPASIVEREQ and has
successfully issued one of the above primitives is con-
sidered "active."
The creation of a link aggregation using dladm(1M) fails
if one of the links included in the aggregation has an
"active" consumer, but succeeds if the links do not have
any DLPI consumers or only "passive" consumers.
Raw Mode
The DLIOCRAW ioctl function is used by some DLPI appli-
cations, most notably the snoop(1M) command. The
DLIOCRAW command puts the stream into a raw mode, which,
upon receive, causes the the full MAC-level packet to be
sent upstream in an MDATA message instead of it being
transformed into the DLUNITDATAIND 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
provider as MDATA messages for transmission. DLIOCRAW
takes no arguments. Once enabled, the stream remains in
this mode until closed.
Native Mode
Some DLPI providers may be able to represent their link
layer using more than one link-layer format. In this
case, the default link-layer format may minimize impact
to applications, but may not allow truly "native" link-
layer headers to be sent or received. DLPI consumers who
wish to use the native link-layer format can use DLIOC-
NATIVE to transition the stream. DLIOCNATIVE takes no
arguments and returns the DLPI mac type associated with
the new link-layer format upon success. Once
enabled, the stream remains in this mode until closed.
Note that DLIOCNATIVE does not enable transition
between dissimilar DLPI mac types and (aside from the
link-layer format), the new DLPI mac type is
guaranteed to be semantically identical. In particular,
the SAP space and addressing format are not affected and
SunOS 5.11 Last change: 29 Jul 2008 5
Protocols dlpi(7P)
the effect of DLIOCNATIVE is only visible when in raw
mode, though any subsequent DLINFOREQ requests gen-
erate responses with dlmactype set to the native DLPI
type.
Margin
While a DLPI provider provides its maximum SDU via
dlmaxsdu in DLINFOACK messages, this value typically
represents a standard maximum SDU for the provider's
media (1500 for Ethernet for example), and not neces-
sarily the absolute maximum amount of data that the pro-
vider is able to transmit in a given data unit. The
"margin" is the extra amount of data in bytes that the
provider can transmit beyond its advertised maximum SDU.
For example, if a DLETHER provider can handle packets
whose payload section is no greater than 1522 bytes and
its dlmaxsdu is set to 1500 (as is typical for Ether-
net), then the margin would be 22. If a provider sup-
ports a non-zero margin, it implements the DLIOCMAR-
GININFO ioctl, whose data is a tuscalart representing
the margin size.
DLETHER-SPECIFIC DLPI SEMANTICS
VLAN Support
VLAN PA Access
Some DLETHER DLPI providers support IE 802.1Q Virtual
LANs (VLAN). For these providers, traffic for a particular
VLAN can be accessed by attaching to (or opening) a special
VLAN PA that is calculated from the VLAN ID and the actual
hardware PA of the device. This VLAN PA is calculated by
multiplying the VLAN ID by 1000 and adding the hardware PA.
For example, VLAN PA 2001 provides access to VLAN ID 2 on
hardware PA 1. As with hardware PA's, a DLPI provider
may provide access to either DLSTYLE1 or DLSTYLE2, or
access to both, for a given VLAN PA. Note that portable
DLPI consumers must try both DLPI styles before concluding
that a DLETHER DLPI provider does not offer VLAN support.
Unless raw mode is enabled, a DLPI stream bound to a VLAN
PA behaves no differently than a traditional DLPI stream.
As with hardware PAs, data must be sent to a DLPI provider
without link-layer headers (which are added by the provider)
and received data is passed to interested DLPI consumers
without link-layer headers. As a result, DLPI consumers do
not require special-case logic to implement VLAN PAs.
Hardware PA Access
SunOS 5.11 Last change: 29 Jul 2008 6
Protocols dlpi(7P)
As per IE 802.1Q, all VLAN traffic is sent using Ether-
Type 0x8100, meaning that in addition to attaching to the
VLAN PA, all VLAN traffic for a given hardware PA can also
be accessed by attaching to the hardware PA and binding to
SAP 0x8100. Accordingly, all VLAN traffic (regardless of
VLAN ID) can be sent and received by the DLPI consumer.
However, even when raw mode is disabled, packets are
received starting with their VLAN headers and must be sent
to the DLPI provider with their VLAN headers already pre-
pended (but without Ethernet headers). Because adhering to
these semantics requires each DLPI consumer to have special-
ized knowledge of VLANs, VLANs should only be accessed in
this way when the VLAN PA access method is insufficient
(for example, because access to all VLAN traffic, regardless
of VLAN ID, is needed).
Because all VLAN traffic is sent with SAP 0x8100, VLAN
traffic not filtered at the physical (DLPROMISCPHYS) level
is also visible if a DLPI consumer enables promiscuous mode
of a stream at the DLPROMISCSAP level. As mentioned ear-
lier, these packets are received starting with their VLAN
headers if raw mode is not enabled.
QoS Support
The IE 802.1Q standard defines eight classes of priority
values used by QoS traffic control of Ethernet packets.
Although the priority values are encoded in the 802.1Q tags,
they can be used independently from VLANs. In particular, a
special priority tagged packet (with VLAN ID zero but prior-
ity bits non-zero) does not belong to any VLAN.
The priority value can be set on either a per-stream or
per-packet basis. DLPI consumers can specify the per-stream
priority using the DLUDQOSREQ request (the priority value
remains unchanged until the next DLUDQOSREQ) and also
specify the per-packet priority value using the bband field
of a MDATA message or the dlpriority field of a
DLUNITDATAREQ.
Raw Mode
Hardware PA Access
When raw mode is enabled, the complete, unmodified MAC-
level packet (including Ethernet and VLAN headers) is
passed to interested DLPI consumers. Similarly, the entire
MAC-level packet (including Ethernet and VLAN headers) must
be sent to the DLPI provider for transmission. Note that
the priority value specified in the bband field can be
overridden by encoding the priority value (if any) into the
VLAN header.
SunOS 5.11 Last change: 29 Jul 2008 7
Protocols dlpi(7P)
VLAN PA Access
When raw mode is enabled, only packets with the correct VLAN
ID are passed up to interested DLPI consumers. With the
exception of priority-tagged packets, DLPI providers must
strip off the VLAN headers (while retaining the preceding
Ethernet headers) before sending up the packets. For
priority-tagged packets, DLPI providers must use the
reserved tag 0 to encode the VLAN TCI and send up the pack-
ets.
On the transmit-side, DLPI consumers must send the packets
down to the DLPI providers without the VLAN headers (but
with the Ethernet headers) unless certain QoS support is
required. If QoS support is needed, the packet can have the
VLAN header to indicate the priority value, however its
VLAN ID must be zero. The DLPI providers then insert the
VLAN tags or encode the VLAN tags using the priority value
specified in the VLAN headers and send the packets.
FILES
Files in or under /dev.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability (Notification support/Passive mode Evolving
behavior)
SEE ALSO
dladm(1M), snoop(1M), libdlpi(3LIB), gld(7D), ip(7P)
NOTES
A Solaris DLPI link name consists of a DLPI provider name
followed by a numeric PA (physical point of attachment).
The DLPI provider name must be between 1 and 16 characters
in length, though names between 3 and 8 characters are pre-
ferred. The DLPI provider name may consist of any
alphanumeric character (a-z, A-Z, 0-9), and the underscore
(). The first and last character of the DLPI provider name
cannot be a digit.
SunOS 5.11 Last change: 29 Jul 2008 8
Protocols dlpi(7P)
The PA must be between 1 and 16 digits in length. Leading
zeroes are not permitted.
SunOS 5.11 Last change: 29 Jul 2008 9
|
