1dlpi(7P) Protocols dlpi(7P)
2
6 dlpi - Data Link Provider Interface
7
9 #include <sys/dlpi.h>
10
13 SunOS STREAMS-based device drivers wishing to support the STREAMS
14 TCP/IP and other STREAMS-based networking protocol suite implementa‐
15 tions support Version 2 of the Data Link Provider Interface (DLPI).
16 DLPI V2 enables a data link service user to access and use any of a
17 variety of conforming data link service providers without special
18 knowledge of the provider's protocol. Specifically, the interface is
19 intended to support Ethernet, X.25 LAPB, SDLC, ISDN LAPD, CSMA/CD,
20 FDDI, token ring, token bus, Bisync, and other datalink-level proto‐
21 cols.
22 The interface specifies access to the data link service provider in the
25 form of M_PROTO and M_PCPROTO type STREAMS messages and does not define
26 a specific protocol implementation. The interface defines the syntax
27 and semantics of primitives exchanged between the data link user and
28 the data link provider to attach a physical device with physical-level
29 address to a stream, bind a datalink-level address to the stream, get
30 implementation-specific information from the data link provider,
31 exchange data with a peer data link user in one of three communication
32 modes (connection, connectionless, acknowledged connectionless),
33 enable/disable multicast group and promiscuous mode reception of
34 datalink frames, get and set the physical address associated with a
35 stream, and several other operations.
36 Solaris conforms to The Open Group Technical Standard for DLPI, Version
39 2. For free access to this specification, point your browser to
40 www.opengroup.org/pubs/catalog/c811.htm. Solaris also provides exten‐
41 sions to the DLPI standard, as detailed in this man page.
42
44 Notification Support
45 Enables DLPI consumers to register for notification when events of
47 interest occur at the DLPI provider. The negotiation can be per‐
48 formed on any attached DLPI stream, and begins with the DLPI con‐
49 sumer, sending a DL_NOTIFY_REQ to the provider, which is an M_PROTO
50 message with the following payload:
51 typedef struct {
53 t_uscalar_t dl_primitive;
54 uint32_t dl_notifications;
55 uint32_t dl_timelimit;
56 } dl_notify_req_t;
57 The dl_primitive field must be set to DL_NOTIFY_REQ; the dl_time‐
59 limit field is reserved for future use and must be set to zero. The
60 dl_notifications field is a bitmask containing the event types the
61 consumer is interested in receiving, and must be zero or more of:
62 DL_NOTE_LINK_DOWN Notify when link has gone down
64 DL_NOTE_LINK_UP Notify when link has come up
65 DL_NOTE_PHYS_ADDR Notify when address changes
66 DL_NOTE_SDU_SIZE Notify when MTU changes
67 DL_NOTE_SPEED Notify when speed changes
68 DL_NOTE_PROMISC_ON_PHYS Notify when DL_PROMISC_PHYS is set
69 DL_NOTE_PROMISC_OFF_PHYS Notify when DL_PROMISC_PHYS is cleared
70 Consumers might find it useful to send a DL_NOTIFY_REQ message with
72 no requested types to check if the DLPI provider supports the
73 extension.
74 Upon receiving the DL_NOTIFY_REQ, the DLPI provider must generate a
76 DL_NOTIFY_ACK, which is an M_PROTO message with the following pay‐
77 load:
78 typedef struct {
80 t_uscalar_t dl_primitive;
81 uint32_t dl_notifications;
82 } dl_notify_ack_t;
83 The dl_primitive field must be set to DL_NOTIFY_ACK. The dl_notifi‐
85 cations field must include any notifications that the provider sup‐
86 ports, along with any other unrequested notifications that the
87 provider supports. However, regardless of the notifications the
88 provider supports, it is restricted to sending only DL_NOTIFY_IND
89 messages (see below) that were requested in the DL_NOTIFY_REQ.
90 Since there are additional notification types which are not yet
92 available for public use, DLPI consumers and providers must take
93 care when inspecting and setting the dl_notifications field.
94 Specifically, consumers must be careful to only request the above
95 notification types, and providers must be careful to not include
96 any unrecognized notification types in the dl_notifications field
97 when constructing the DL_NOTIFY_ACK. In addition, DL_NOTIFY_IND's
98 that are received with undocumented dl_notification or dl_data val‐
99 ues must be ignored.
100 DLPI consumers might receive a DL_ERROR_ACK message (with
102 dl_error_primitive set to DL_NOTIFY_REQ) in response to the initial
103 DL_NOTIFY_REQ message. This message indicates that the DLPI
104 provider does not support the DLPI notification extension. Other‐
105 wise, the DLPI consumer receives a DL_NOTIFY_ACK and should expect
106 to receive DL_NOTIFY_IND messages for any types that it requested
107 that were still set in it. The DL_NOTIFY_IND is an M_PROTO message
108 with the following payload:
109 typedef struct {
111 t_uscalar_t dl_primitive;
112 uint32_t dl_notification;
113 uint32_t dl_data;
114 t_uscalar_t dl_addr_length;
115 t_uscalar_t dl_addr_offset;
116 } dl_notify_ind_t;
117 The dl_primitive field must be set to DL_NOTIFY_IND, and the
119 dl_notification field must be set to the event type that has
120 occurred (for example, DL_NOTE_LINK_DOWN). Only a single event type
121 can be set in each DL_NOTIFY_IND.
122 For the DL_NOTE_SPEED event type, dl_data must be set to the cur‐
124 rent interface speed in kilobits per second. For the
125 DL_NOTE_PHYS_ADDR event type, dl_data must be set to
126 DL_CURR_PHYS_ADDR. For the DL_NOTE_SDU_SIZE event type, dl_data
127 must be set to the current MTU in bytes. Otherwise, dl_data must be
128 set to zero.
129 For the DL_NOTE_PHYS_ADDR event type, the dl_addr_length field must
131 be set to the length of the address, and the dl_addr_offset field
132 must be set to offset of the first byte of the address, relative to
133 b_rptr (for example, if the address immediately follows the
134 dl_notify_ind structure, dl_addr_offset is set to 'sizeof
135 (dl_notify_ind)'). For all other event types, the dl_addr_length
136 and dl_addr_offset fields must be set to zero by DLPI providers and
137 ignored by DLPI consumers.
138 In addition to generating DL_NOTIFY_IND messages when a requested
140 event has occurred, the DLPI provider must initially generate one
141 or more DL_NOTIFY_IND messages to notify the DLPI consumer of the
142 the current state of the interface. For instance, if the consumer
143 has requested DL_NOTE_LINK_UP | DL_NOTE_LINK_DOWN, the provider
144 must send a DL_NOTIFY_IND containing the current state of the link
145 (either DL_NOTE_LINK_UP or DL_NOTE_LINK_DOWN) after sending the
146 DL_NOTIFY_ACK.
147 For the initial DL_NOTIFY_IND message, the DLPI provider is
149 strongly recommended against sending DL_NOTE_LINK_DOWN, even if the
150 interface is still initializing and is not yet ready to send or
151 receive packets. Instead, either delaying the DL_NOTIFY_IND message
152 until the interface is ready or optimistically reporting
153 DL_NOTIFY_LINK_UP and subsequently reporting DL_NOTE_LINK_DOWN if
154 the negotation fails is strongly preferred. This prevents
155 DL_NOTIFY_IND consumers from needlessly triggering network failover
156 operations and logging error messages during network interface ini‐
157 tialization.
158 The DLPI provider must continue to generate DL_NOTIFY_IND messages
160 until it receives a new DL_NOTIFY_REQ message or the DLPI stream is
161 detached (or closed). Further, a DLPI style 2 provider must keep
162 track of the requested events after a DL_DETACH_REQ operation, and
163 if a subsequent DL_ATTACH_REQ is received, it must send gratuitous
164 DL_NOTIFY_IND messages to notify the consumer of the current
165 state of the device, since the state might have changed while
166 detached (or the consumer might have simply discarded its previous
167 state).
168 Passive Consumers of Aggregated Links
171 Solaris link aggregations as configured by dladm(1M) export DLPI
173 nodes for both the link aggregation, and individual links that com‐
174 prises the aggregation, to allow observability of the aggregated
175 links. To allow applications such as snoop(1M) to open those indi‐
176 vidual aggregated links while disallowing other consumers such as
177 ip(7P), DL_PASSIVE_REQ (a DLPI primitive), must be issued by
178 snoop(1M) and similar applications.
179 The DL_PASSIVE_REQ primitive is an M_PROTO message containing the
181 following payload:
182 typedef struct {
184 t_uscalar_t dl_primitive;
185 } dl_passive_req_t;
186 Issuing this primitive allows the consumer of a DLPI link to coex‐
188 ist with a link aggregation that also uses the link. Such a con‐
189 sumer is considered passive.
190 Consumers that don't use this primitive while an aggregation is
192 using the link receive DL_SYSERR/EBUSY when issuing the following
193 DLPI primitives:
194 DL_BIND_REQ
196 DL_ENABMULTI_REQ
197 DL_PROMISCON_REQ
198 DL_AGGR_REQ
199 DL_UNAGGR_REQ
200 DL_CONTROL_REQ
201 DL_SET_PHYS_ADDR_REQ
202 A consumer that has not issued a DL_PASSIVE_REQ and has success‐
204 fully issued one of the above primitives is considered active.
205 The creation of a link aggregation using dladm(1M) fails if one of
207 the links included in the aggregation has an active consumer, but
208 succeeds if the links do not have any DLPI consumers or only pas‐
209 sive consumers.
210 Raw Mode
213 The DLIOCRAW ioctl function is used by some DLPI applications, most
215 notably the snoop(1M) command. The DLIOCRAW command puts the stream
216 into a raw mode, which, upon receive, causes the the full MAC-level
217 packet to be sent upstream in an M_DATA message instead of it being
218 transformed into the DL_UNITDATA_IND form normally used for report‐
219 ing incoming packets. Packet SAP filtering is still performed on
220 streams that are in raw mode. If a stream user wants to receive all
221 incoming packets it must also select the appropriate promiscuous
222 modes. After successfully selecting raw mode, the application is
223 also allowed to send fully formatted packets to the provider as
224 M_DATA messages for transmission. DLIOCRAW takes no arguments. Once
225 enabled, the stream remains in this mode until closed.
226 Native Mode
229 Some DLPI providers are able to represent their link layer using
231 more than one link-layer format. In this case, the default link-
232 layer format can minimize impact to applications, but might not
233 allow truly native link-layer headers to be sent or received. DLPI
234 consumers who wish to use the native link-layer format can use
235 DLIOCNATIVE to transition the stream. DLIOCNATIVE takes no argu‐
236 ments and returns the DLPI mac type associated with the new link-
237 layer format upon success. Once enabled, the stream
238 remains in this mode until closed. Note that DLIOCNATIVE does not
239 enable transition between dissimilar DLPI mac types and (aside from
240 the link-layer format), the new DLPI mac type is guaranteed to be
241 semantically identical. In particular, the SAP space and addressing
242 format are not affected and the effect of DLIOCNATIVE is only visi‐
243 ble when in raw mode, though any subsequent DL_INFO_REQ requests
244 generate responses with dl_mac_type set to the native DLPI type.
245 Margin
248 While a DLPI provider provides its maximum SDU via dl_max_sdu in
250 DL_INFO_ACK messages, this value typically represents a standard
251 maximum SDU for the provider's media (1500 for Ethernet for exam‐
252 ple), and not necessarily the absolute maximum amount of data that
253 the provider is able to transmit in a given data unit. The margin
254 "is the extra amount of data in bytes that the provider can trans‐
255 mit beyond its advertised maximum SDU. For example, if a DL_ETHER
256 provider can handle packets whose payload section is no greater
257 than 1522 bytes and its dl_max_sdu is set to 1500 (as is typical
258 for Ethernet), then the margin would be 22. If a provider supports
259 a non-zero margin, it implements the DLIOCMARGININFO ioctl, whose
260 data is a t_uscalar_t representing the margin size.
261
264 VLAN Support
265 Traditional VLAN Access
266 Some DL_ETHER DLPI providers support IEEE 802.1Q Virtual LANs (VLAN).
267 For these providers, traffic for a particular VLAN can be accessed by
268 opening a VLAN data-link.
269 Unless raw mode is enabled, a DLPI stream bound to a VLAN data-link
272 behaves no differently than a traditional DLPI stream. As with non-
273 VLAN data-link access, data must be sent to a DLPI provider without
274 link-layer headers (which are added by the provider) and received data
275 is passed to interested DLPI consumers without link-layer headers. As
276 a result, DLPI consumers not require special-case logic to implement
277 VLAN access.
278 SAP-Based VLAN Access
280 As per IEEE 802.1Q, all VLAN traffic is sent using Ether- Type 0x8100,
281 meaning that in addition to directly opening a VLAN data-link, all
282 VLAN traffic for a given underline data-link can also be accessed by
283 opening the underlying data-link and binding to SAP 0x8100. Accord‐
284 ingly, all VLAN traffic (regardless of VLAN ID) can be sent and
285 received by the DLPI consumer. However, even when raw mode is dis‐
286 abled, packets are received starting with their VLAN headers and must
287 be sent to the DLPI provider with their VLAN headers already pre-
288 pended (but without Ethernet headers). Because adhering to these
289 semantics requires each DLPI consumer to have specialized knowledge of
290 VLANs, VLANs should only be accessed in this way when the traditional
291 VLAN access method is insufficient (for example, because access to all
292 VLAN traffic, regardless of VLAN ID, is needed).
293 Because all VLAN traffic is sent with SAP 0x8100, VLAN traffic not fil‐
296 tered at the physical (DL_PROMISC_PHYS) level is also visible if a DLPI
297 consumer enables promiscuous mode of a stream at the DL_PROMISC_SAP
298 level. As mentioned earlier, these packets are received starting with
299 their VLAN headers if raw mode is not enabled.
300 QoS Support
302 The IEEE 802.1Q standard defines eight classes of priority values used
303 by QoS traffic control of Ethernet packets. Although the priority val‐
304 ues are encoded in the 802.1Q tags, they can be used independently from
305 VLANs. In particular, a special priority tagged packet (with VLAN ID
306 zero but priority bits non-zero) does not belong to any VLAN.
307 The priority value can be set on either a per-stream or per-packet
310 basis. DLPI consumers can specify the per-stream priority using the
311 DL_UDQOS_REQ request (the priority value remains unchanged until the
312 next DL_UDQOS_REQ) and also specify the per-packet priority value using
313 the b_band field of a M_DATA message or the dl_priority field of a
314 DL_UNITDATA_REQ.
315 Raw Mode
317 SAP-Based VLAN Access
318 When raw mode is enabled, the complete, unmodified MAC- level packet
319 (including Ethernet and VLAN headers) is passed to interested DLPI
320 consumers. Similarly, the entire MAC-level packet (including Ethernet
321 and VLAN headers) must be sent to the DLPI provider for transmission.
322 Note that the priority value specified in the b_band field can be over‐
323 ridden by encoding the priority value (if any) into the VLAN header.
324 Traditional VLAN Access
326 When raw mode is enabled, only packets with the correct VLAN ID are
327 passed up to interested DLPI consumers. With the exception of priority-
328 tagged packets, DLPI providers must strip off the VLAN headers (while
329 retaining the preceding Ethernet headers) before sending up the pack‐
330 ets. For priority-tagged packets, DLPI providers must use the reserved
331 tag 0 to encode the VLAN TCI and send up the packets.
332 On the transmit-side, DLPI consumers must send the packets down to the
335 DLPI providers without the VLAN headers (but with the Ethernet head‐
336 ers) unless certain QoS support is required. If QoS support is needed,
337 the packet can have the VLAN header to indicate the priority value,
338 however its VLAN ID must be zero. The DLPI providers then insert the
339 VLAN tags or encode the VLAN tags using the priority value specified in
340 the VLAN headers and send the packets.
341
343 Files in or under /dev.
344
346 See attributes(5) for descriptions of the following attributes:
347 ┌────────────────────────────────────────────────────────┬─────────────────┐
352 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
353 ├────────────────────────────────────────────────────────┼─────────────────┤
354 │Interface Stability (Notification support/Passive mode │ Committed │
355 │behavior) │ │
356 └────────────────────────────────────────────────────────┴─────────────────┘
357
359 dladm(1M), snoop(1M), libdlpi(3LIB), gld(7D), ip(7P)
360
362 A Solaris DLPI link name consists of a DLPI provider name followed by a
363 numeric PPA (physical point of attachment).
364 The DLPI provider name must be between 1 and 16 characters in length,
367 though names between 3 and 8 characters are preferred. The DLPI
368 provider name can consist of any alphanumeric character (a-z, A-Z,
369 0-9), and the underscore (_). The first and last character of the DLPI
370 provider name cannot be a digit.
371 The PPA must be a number between 0 and 4294967294 inclusive. Leading
374 zeroes are not permitted.
375SunOS 5.11 7 Sep 2009 dlpi(7P)