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, FDDI, 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 M_PROTO and M_PCPROTO 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 DL_NOTIFY_REQ to the provider, which is an M_PROTO mes- sage with the following payload: typedef struct { t_uscalar_t dl_primitive; uint32_t dl_notifications; uint32_t dl_timelimit; } dl_notify_req_t; 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: 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 link address changes */ DL_NOTE_SDU_SIZE /* notify when link mtu changes */ DL_NOTE_SPEED /* notify when link speed changes */ Consumers may find it useful to send a DL_NOTIFY_REQ message with no requested types to check if the DLPI provider supports the extension. Upon receiving the DL_NOTIFY_REQ, the DLPI provider must generate a DL_NOTIFY_ACK, which is an M_PROTO message with the following payload: typedef struct { t_uscalar_t dl_primitive; uint32_t dl_notifications; } dl_notify_ack_t; The dl_primitive field must be set to DL_NOTIFY_ACK. The dl_notifications field must include any requested notif- ications that the driver supports, along with any other unrequested notifications that the driver supports. How- ever, regardless of the notifications the driver sup- ports, it is restricted to sending only DL_NOTIFY_IND messages (see below) that were requested in the DL_NOTIFY_REQ. 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 dl_notifications 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 dl_notifications 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. DLPI consumers may receive a DL_ERROR_ACK message (with dl_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 notifi- cation extension. Otherwise, the DLPI consumer will receive 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: 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; The dl_primitive field must be set to DL_NOTIFY_IND, and the dl_notification field must be set to the event type that has occurred (for example, DL_NOTE_LINK_DOWN). Only a single event type may be set in each DL_NOTIFY_IND. For the DL_NOTE_SPEED event type, dl_data 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, dl_data must be set to the current MTU in bytes. Other- wise, dl_data must be set to zero. For the DL_NOTE_PHYS_ADDR event type, the dl_addr_length field must be set to the length of the address, and the dl_addr_offset field must be set to offset of the first byte of the address, relative to b_rptr (for example, if the address imediately follows the dl_notify_ind struc- ture, dl_addr_offset is set to 'sizeof (dl_notify_ind)'). For all other event types, the dl_addr_length and dl_addr_offset fields must be set to zero by DLPI providers and ignored by DLPI consumers. In addition to generating DL_NOTIFY_IND messages when a requested event has occurred, the DLPI provider must initially generate one or more DL_NOTIFY_IND messages to notify the DLPI consumer of the 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. 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 ini- tializing and is not yet ready to send or receive pack- ets. 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 negotation fails is strongly preferred. This prevents DL_NOTIFY_IND consumers from needlessly triggering network failover operations and logging error messages during network interface initial- ization. The DLPI provider must continue to generate DL_NOTIFY_IND messages until it receives a new DL_NOTIFY_REQ message or the DLPI stream is detached (or closed). Further, a DLPI style 2 driver 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 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), DL_PASSIVE_REQ (a DLPI primitive), must be issued by snoop(1M) and similar applications. The DL_PASSIVE_REQ primitive is an M_PROTO message con- taining the following payload: typedef struct { t_uscalar_t dl_primitive; } dl_passive_req_t; 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 DL_SYSERR/EBUSY when issuing the following DLPI primitives: DL_BIND_REQ DL_ENABMULTI_REQ DL_PROMISCON_REQ DL_AGGR_REQ DL_UNAGGR_REQ DL_CONTROL_REQ DL_SET_PHYS_ADDR_REQ A consumer that has not issued a DL_PASSIVE_REQ 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 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. 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 able to be sent or received. | DLPI consumers that 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 is not intended to | enable transition between dissimilar DLPI mac types, and | as such the new DLPI mac type is guaranteed to be | semantically identical aside from the link-layer format. | In particular, the SAP space and addressing format will | not be affected, and thus the effect of DLIOCNATIVE will | only be visible when in raw mode, though any subsequent | DL_INFO_REQ requests will generate responses with | dl_mac_type set to the native DLPI type. | FILES Files in or under /dev. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_______________________________|___________________________| | Interface Stability (Notifi- | Evolving | | cation support/Passive mode | | | behavior) | | |_______________________________|___________________________| SEE ALSO dladm(1M), snoop(1M), hme(7D), ge(7D), qfe(7D), gld(7D), ip(7P) NOTES Streams drivers for network interface cards (NIC) must meet the following driver name constraints: +o Length - Name cannot exceed 16 characters. Names con- taining three to eight characters are preferred. +o Legal Characters - Legal characters are: alphanumeric (a-z, A-Z, 0-9), and the underscore ('_'). Addition- ally, the first and/or last character of a name cannot be a digit.