8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man7p / dlpi.7p

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.
.\" 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 DLPI 7P "April 9, 2016"
.SH NAME
dlpi \- Data Link Provider Interface
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/dlpi.h>\fR
.fi

.SH DESCRIPTION
.LP
SunOS STREAMS-based device drivers wishing to support the STREAMS \fB TCP/IP\fR
and other STREAMS-based networking protocol suite implementations support
Version 2 of the Data Link Provider Interface (\fBDLPI\fR). \fBDLPI V2\fR
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. Specifically, the interface is intended to support
Ethernet, \fBX.25 LAPB,\fR \fBSDLC,\fR \fBISDN LAPD,\fR \fBCSMA/CD,\fR
\fBFDDI,\fR token ring, token bus, Bisync, and other datalink-level protocols.
.sp
.LP
The interface specifies access to the data link service provider in the form of
\fBM_PROTO\fR and \fBM_PCPROTO\fR type STREAMS messages and does not define a
specific protocol implementation. 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, connectionless,
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.
.sp
.LP
Solaris conforms to The Open Group Technical Standard for \fIDLPI, Version
2\fR. For free access to this specification, point your browser to
\fIwww.opengroup.org/pubs/catalog/c811.htm\fR. Solaris also provides extensions
to the DLPI standard, as detailed in this man page.
.SH SOLARIS-SPECIFIC DLPI EXTENSIONS
.ne 2
.na
\fBNotification Support\fR
.ad
.sp .6
.RS 4n
Enables \fBDLPI\fR consumers to register for notification when events of
interest occur at the \fBDLPI\fR provider. The negotiation can be performed on
any attached DLPI stream, and begins with the \fBDLPI\fR consumer, sending a
DL_NOTIFY_REQ to the provider, which is an M_PROTO message with the following
payload:
.sp
.in +2
.nf
      typedef struct {
              t_uscalar_t     dl_primitive;
              uint32_t        dl_notifications;
              uint32_t        dl_timelimit;
      } dl_notify_req_t;
.fi
.in -2

The dl_primitive field must be set to DL_NOTIFY_REQ; the dl_timelimit field is
reserved for future use and must be set to zero. The dl_notifications field is
a bitmask containing the event types the consumer is interested in receiving,
and must be zero or more of:
.sp
.in +2
.nf
DL_NOTE_LINK_DOWN         Notify when link has gone down
DL_NOTE_LINK_UP           Notify when link has come up
DL_NOTE_PHYS_ADDR         Notify when address changes
DL_NOTE_SDU_SIZE          Notify when MTU changes
DL_NOTE_SPEED             Notify when speed changes
DL_NOTE_PROMISC_ON_PHYS   Notify when DL_PROMISC_PHYS is set
DL_NOTE_PROMISC_OFF_PHYS  Notify when DL_PROMISC_PHYS is cleared
.fi
.in -2

Consumers might find it useful to send a DL_NOTIFY_REQ message with no
requested types to check if the \fBDLPI\fR provider supports the extension.
.sp
Upon receiving the DL_NOTIFY_REQ, the \fBDLPI\fR provider must generate a
DL_NOTIFY_ACK, which is an M_PROTO message with the following payload:
.sp
.in +2
.nf
      typedef struct {
              t_uscalar_t     dl_primitive;
              uint32_t        dl_notifications;
      } dl_notify_ack_t;
.fi
.in -2

The \fBdl_primitive\fR field must be set to DL_NOTIFY_ACK. The
\fBdl_notifications\fR field must include any notifications that the provider
supports, along with any other unrequested notifications that the provider
supports. However, regardless of the notifications the provider supports, it is
restricted to sending only DL_NOTIFY_IND messages  (see below) that were
requested in the DL_NOTIFY_REQ.
.sp
Since there are additional notification types which are not yet available for
public use, \fBDLPI\fR consumers and providers must take care when inspecting
and setting the \fBdl_notifications\fR 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
\fBdl_notifications\fR field when constructing the DL_NOTIFY_ACK. In addition,
DL_NOTIFY_IND's that are received with undocumented dl_notification or dl_data
values must be ignored.
.sp
DLPI consumers might receive a DL_ERROR_ACK message (with dl_error_primitive
set to DL_NOTIFY_REQ) in response to the initial DL_NOTIFY_REQ message. This
message indicates that the DLPI provider does not support the DLPI notification
extension. Otherwise, the DLPI consumer receives a DL_NOTIFY_ACK and should
expect to receive DL_NOTIFY_IND messages for any types that it requested that
were still set in it. The DL_NOTIFY_IND is an M_PROTO message with the
following payload:
.sp
.in +2
.nf
     typedef struct {
             t_uscalar_t     dl_primitive;
             uint32_t        dl_notification;
             uint32_t        dl_data;
             t_uscalar_t     dl_addr_length;
             t_uscalar_t     dl_addr_offset;
     } dl_notify_ind_t;
.fi
.in -2

The \fBdl_primitive\fR field must be set to DL_NOTIFY_IND, and the
\fBdl_notification\fR field must be set to the event type that has occurred
(for example, DL_NOTE_LINK_DOWN). Only a single event type can be set in each
DL_NOTIFY_IND.
.sp
For the DL_NOTE_SPEED event type, \fBdl_data\fR must be set to the current
interface speed in kilobits per second. For the DL_NOTE_PHYS_ADDR event type,
dl_data must be set to DL_CURR_PHYS_ADDR. For the DL_NOTE_SDU_SIZE event type,
\fBdl_data\fR must be set to the current MTU in bytes. Otherwise, \fBdl_data\fR
must be set to zero.
.sp
For the DL_NOTE_PHYS_ADDR event type, the \fBdl_addr_length\fR field must be
set to the length of the address, and the \fBdl_addr_offset\fR field must be
set to offset of the first byte of the address, relative to b_rptr (for
example, if the address immediately follows the \fBdl_notify_ind\fR structure,
\fBdl_addr_offset\fR is set to 'sizeof (\fBdl_notify_ind\fR)'). For all other
event types, the \fBdl_addr_length\fR and \fBdl_addr_offset\fR fields must be
set to zero by DLPI providers and ignored by DLPI consumers.
.sp
In addition to generating DL_NOTIFY_IND messages when a requested event has
occurred, the \fBDLPI\fR provider must initially generate one or more
DL_NOTIFY_IND messages to notify the \fBDLPI\fR consumer of the current
state of the interface. For instance, if the consumer has requested
DL_NOTE_LINK_UP | DL_NOTE_LINK_DOWN, the provider must send a DL_NOTIFY_IND
containing the current state of the link (either DL_NOTE_LINK_UP or
DL_NOTE_LINK_DOWN) after sending the DL_NOTIFY_ACK.
.sp
For the initial DL_NOTIFY_IND message, the DLPI provider is strongly
recommended against sending DL_NOTE_LINK_DOWN, even if the interface is still
initializing and is not yet ready to send or receive packets. Instead, either
delaying the DL_NOTIFY_IND message until the interface is ready or
optimistically reporting DL_NOTIFY_LINK_UP and subsequently   reporting
DL_NOTE_LINK_DOWN if the negotiation fails is strongly   preferred. This
prevents DL_NOTIFY_IND consumers from needlessly triggering network failover
operations and logging error messages during network interface initialization.
.sp
The DLPI provider must continue to generate DL_NOTIFY_IND messages until it
receives a new DL_NOTIFY_REQ message or the \fBDLPI\fR stream is detached (or
closed). Further, a DLPI style  2 provider must keep track of the requested
events after a DL_DETACH_REQ operation, and if a subsequent DL_ATTACH_REQ is
received, it must send gratuitous DL_NOTIFY_IND  messages to notify the
consumer of the  current state of  the device, since the state might have
changed while  detached (or the consumer might have simply discarded its
previous state).
.RE

.sp
.ne 2
.na
\fBPassive Consumers of Aggregated Links\fR
.ad
.sp .6
.RS 4n
Solaris link aggregations as configured by \fBdladm\fR(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  \fBsnoop\fR(1M) to open those individual aggregated links
while disallowing other consumers such as \fBip\fR(7P), DL_PASSIVE_REQ (a DLPI
primitive), must be issued by \fBsnoop\fR(1M) and similar applications.
.sp
The DL_PASSIVE_REQ primitive is an M_PROTO message containing the following
payload:
.sp
.in +2
.nf
typedef struct {
        t_uscalar_t     dl_primitive;
} dl_passive_req_t;
.fi
.in -2

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
\fBpassive\fR.
.sp
Consumers that don't use this primitive while an aggregation is using the link
receive DL_SYSERR/EBUSY when issuing the following DLPI primitives:
.sp
.in +2
.nf
DL_BIND_REQ
DL_ENABMULTI_REQ
DL_PROMISCON_REQ
DL_AGGR_REQ
DL_UNAGGR_REQ
DL_CONTROL_REQ
DL_SET_PHYS_ADDR_REQ
.fi
.in -2

A consumer that has not issued a DL_PASSIVE_REQ and has successfully issued one
of the above primitives is considered \fBactive\fR.
.sp
The creation of a link aggregation using \fBdladm\fR(1M) fails if one of the
links included in the aggregation has an \fBactive\fR consumer, but succeeds if
the links do not have any DLPI consumers or only \fBpassive\fR consumers.
.RE

.sp
.ne 2
.na
\fBRaw Mode\fR
.ad
.sp .6
.RS 4n
The \fBDLIOCRAW\fR ioctl function is used by some DLPI applications, most
notably the \fBsnoop\fR(1M) command. The \fBDLIOCRAW\fR command puts the stream
into a raw mode, which, upon receive, causes the full MAC-level packet to
be sent upstream in an \fBM_DATA\fR message instead of it being transformed
into the \fBDL_UNITDATA_IND\fR form normally used for reporting incoming
packets. Packet \fBSAP\fR 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 \fBM_DATA\fR messages for transmission. \fBDLIOCRAW\fR takes no
arguments. Once enabled, the stream remains in this mode until closed.
.RE

.sp
.ne 2
.na
\fBNative Mode\fR
.ad
.sp .6
.RS 4n
Some DLPI providers are able to represent their link layer using more than one
link-layer  format. In this case, the  default link-layer format can minimize
impact to applications, but might not allow truly \fBnative\fR link-layer
headers to be sent or received. DLPI consumers who wish to use the native
link-layer format can use DLIOCNATIVE 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 the effect of
DLIOCNATIVE is only visible when in raw mode, though any subsequent DL_INFO_REQ
requests generate responses with dl_mac_type set to the native DLPI type.
.RE

.sp
.ne 2
.na
\fBMargin\fR
.ad
.sp .6
.RS 4n
While a DLPI provider provides its maximum SDU via dl_max_sdu in DL_INFO_ACK
messages, this value typically represents a standard maximum SDU for the
provider's media (1500 for Ethernet for example), and not necessarily the
absolute maximum amount of data that the provider is able to transmit in a
given data unit.  The \fBmargin\fR "is the extra amount of data in bytes that
the provider can transmit beyond its advertised maximum SDU. For example, if a
DL_ETHER provider can handle packets whose payload section is no greater than
1522 bytes and its dl_max_sdu is set to 1500 (as is typical for Ethernet), then
the margin would be 22. If a provider supports a non-zero margin, it implements
the DLIOCMARGININFO ioctl, whose data is a t_uscalar_t representing the margin
size.
.RE

.SH DL_ETHER-SPECIFIC DLPI SEMANTICS
.SS "VLAN Support"
.SS "Traditional VLAN Access"
.LP
Some \fBDL_ETHER DLPI\fR providers support \fIIEEE 802.1Q\fR Virtual LANs
(VLAN). For these providers, traffic for a particular VLAN can be accessed by
opening a VLAN data-link.
.sp
.LP
Unless raw mode is enabled, a DLPI stream bound to a VLAN data-link  behaves
no differently than a traditional DLPI stream. As with non-VLAN data-link
access, 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 not require
special-case logic to implement VLAN access.
.SS "SAP-Based VLAN Access"
.LP
As per \fIIEEE 802.1Q\fR, all VLAN traffic is sent using Ether- Type  0x8100,
meaning  that in addition to directly opening a VLAN data-link, all VLAN
traffic for a given underline data-link can also be accessed by opening the
underlying data-link 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 specialized knowledge of
VLANs, VLANs should only be accessed in this way when the traditional VLAN
access  method is insufficient (for example, because access to all VLAN
traffic, regardless of  VLAN ID, is needed).
.sp
.LP
Because all VLAN traffic is sent with SAP 0x8100, VLAN traffic not filtered at
the physical (\fBDL_PROMISC_PHYS\fR) level is also visible if a DLPI consumer
enables promiscuous mode of a stream at the \fBDL_PROMISC_SAP\fR level. As
mentioned earlier, these packets are received starting with their VLAN headers
if raw mode is not enabled.
.SS "QoS Support"
.LP
The \fIIEEE 802.1Q\fR standard defines eight classes of priority values used by
QoS traffic control of Ethernet packets. Although the priority values are
encoded in the\fI 802.1Q\fR tags, they can be used independently from VLANs.
In particular, a  special priority tagged packet (with VLAN ID zero but
priority bits non-zero) does not belong to any VLAN.
.sp
.LP
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 \fBDL_UDQOS_REQ\fR
request (the priority value remains unchanged until the next DL_UDQOS_REQ) and
also specify the per-packet priority value using the b_band field of a M_DATA
message or the \fBdl_priority\fR field of a \fBDL_UNITDATA_REQ\fR.
.SS "Raw Mode"
.SS "SAP-Based VLAN Access"
.LP
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 b_band field can be overridden by encoding the priority value (if any)
into the VLAN header.
.SS "Traditional VLAN Access"
.LP
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 packets.
.sp
.LP
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.
.SH FILES
.LP
Files in or under \fB/dev\fR.
.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
T{
Interface Stability (Notification support/Passive mode behavior)
T}      Committed
.TE

.SH SEE ALSO
.LP
\fBdladm\fR(1M), \fBsnoop\fR(1M), \fBlibdlpi\fR(3LIB), \fBgld\fR(7D),
\fBip\fR(7P)
.SH NOTES
.LP
A Solaris DLPI link name consists of a \fBDLPI provider name\fR followed by a
numeric \fBPPA\fR (physical point of attachment).
.sp
.LP
The DLPI provider name must be between 1 and 16 characters in length, though
names between 3 and 8 characters are preferred. The DLPI provider name can
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.
.sp
.LP
The PPA must be a number between \fB0\fR and \fB4294967294\fR inclusive.
Leading zeroes are not permitted.