Data Link Provider Interface (DLPI)

DLPI

Section: Data Link Provider Interface (DLPI) (7)
Updated: Thu, 11 Dec 2008 03:18:58 GMT
Index Return to Main Contents

NAME

DLPI - Data Link Provider Interface

SYNOPSIS

#include <sys/dlpi.h>

DESCRIPTION

The data link layer (layer 2 in the OSI Reference Model) is responsible for the transmission and error-free delivery of bits of information over a physical communications medium.

The model of the data link layer is presented here to describe concepts that are used throughout the specification of DLPI. It is described in terms of an interface architecture, as well as addressing concepts needed to identify different components of that architecture. The description of the model assumes familiarity with the OSI Reference Model.

Each layer of the OSI Reference Model has two standards:

*: one that defines the services provided by the layer, and
*: one that defines the protocol through which layer services are provided.

DLPI is an implementation of the first type of standard. It specifies an interface to the services of the data link layer.

The data link interface is the boundary between the network and data link layers of the OSI Reference Model. The network layer entity is the user of the services of the data link interface (DLS user), and the data link layer entity is the provider of those services (DLS provider). This interface consists of a set of primitives that provide access to the data link layer services, plus the rules for using those primitives (state transition rules). A data link interface service primitive might request a particular service or indicate a pending event.

To provide uniformity among the various UNIX system networking products, an effort is underway to develop service interfaces that map to the OSI Reference Model. A set of kernel-level interfaces, based on the STREAMS(4) development environment, constitute a major portion of this effort. The service primitives that make up these interfaces are defined as STREAMS(4) messages that are transferred between the user and provider of the service. DLPI is one such kernel-level interface, and is targeted for STREAMS(4) protocol modules that either use or provide data link services. In addition, user programs that wish to access a STREAMS(4)-based data link provider directly may do so using the putmsg(2) and getmsg(2) system calls. The DLS provider is configured as a STREAMS(4) driver,and the DLS user accesses the provider using open(2) to establish a stream to the DLS provider. The stream acts as a communication endpoint between a DLS user and the DLS provider. After the stream is created, the DLS user and DLS provider communicate via the messages presented later in this specification. DLPI is intended to free data link users from specific knowledge of the characteristics of the data link provider. Specifically, the definition of DLPI hopes to achieve the goal of allowing a DLS user to be implemented independent of a specific communications medium. Any data link provider (supporting any communications medium) that conforms to the DLPI specification may be substituted beneath the DLS user to provide the data link services. Support of a new DLS provider should not require any changes to the implementation of the DLS user.

MODES OF COMMUNICATION

The data link provider interface supports three modes of communication: connection, connectionless and acknowledged connectionless.

The connection mode is circuit-oriented and enables data to be transferred over a pre-established connection in a sequenced manner. Data may be lost or corrupted in this service mode, however, due to provider-initiated resynchronization or connection aborts.

The connectionless mode is message-oriented and supports data transfer in self-contained units with no logical relationship required between units. Because there is no acknowledgment of each data unit transmission, this service mode can be unreliable in the most general case. However, a specific DLS provider can provide assurance that messages will not be lost, duplicated, or reordered.

The acknowledged connectionless mode provides the means by which a data link user can send data and request the return of data at the same time. Although the exchange service is connectionless, in-sequence delivery is guaranteed for data sent by the initiating station. The data unit transfer is point-to-point.

CONNECTION-MODE SERVICE

The connection-mode service is characterized by four phases of communication: local management,connection establishment, data transfer, and connection release.

Local Management: This phase enables a DLS user to initialize a stream for use in communication and establish an identity with the DLS provider.
Connection Establishment: This phase enables two DLS users to establish a data link connection between them to exchange data. One user (the calling DLS user) initiates the connection establishment procedures, while another user (the called DLS user) waits for incoming connect requests. The called DLS user is identified by an address associated with its stream (as will be discussed shortly).
A called DLS user may either accept or deny a request for a data link connection. If the request is accepted, a connection is established between the DLS users and they enter the data transfer phase. For both the calling and called DLS users, only one connection may be established per stream. Thus, the stream is the communication endpoint for a data link connection. The called DLS user may choose to accept a connection on the stream where it received the connect request, or it may open a new stream to the DLS provider and accept the connection on this new, responding stream. By accepting the connection on a separate stream, the initial stream can be designated as a listening stream through which all connect requests will be processed. As each request arrives, a new stream (communication endpoint) can be opened to handle the connection, enabling subsequent requests to be queued on a single stream until they can be processed.
Data Transfer: In this phase, the DLS users are considered peers and may exchange data simultaneously in both directions over an established data link connection. Either DLS user may send data to its peer DLS user at any time. Data sent by a DLS user is guaranteed to be delivered to the remote user in the order in which it was sent.
Connection Release: This phase enables either the DLS user, or the DLS provider, to break an established connection. The release procedure is considered abortive, so any data that has not reached the destination user when the connection is released may be discarded by the DLS provider.

CONNECTIONLESS-MODE SERVICE

The connectionless mode service does not use the connection establishment and release phases of the connection-mode service. The local management phase is still required to initialize a stream. Once initialized, however, the connectionless data transfer phase is immediately entered. Because there is no established connection, however, the connectionless data transfer phase requires the DLS user to identify the destination of each data unit to be transferred. The destination DLS user is identified by the address associated with that user (as will be discussed shortly).

Connectionless data transfer does not guarantee that data units will be delivered to the destination user in the order in which they were sent. Furthermore, it does not guarantee that a given data unit will reach the destination DLS user, although a given DLS provider may provide assurance that data will not be lost.

ACKNOWLEDGED CONNECTIONLESS-MODE SERVICE

The acknowledged connectionless mode service also does not use the connection establishment and release phases of the connection-mode service. The local management phase is still required to initialize a stream. Once initialized, the acknowledged connectionless data transfer phase is immediately entered. Acknowledged connectionless data transfer guarantees that data units will be delivered to the destination user in the order in which they were sent. A data link user entity can send a data unit to the destination DLS User, request a previously prepared data unit from the destination DLS User, or exchange data units.

DLPI ADDRESSING

Each user of DLPI must establish an identity to communicate with other data link users. This identity consists of two pieces. First, the DLS user must somehow identify the physical medium over which it will communicate. This is particularly evident on systems that are attached to multiple physical media. Second, the DLS user must register itself with the DLS provider so that the provider can deliver protocol data units destined for that user.

PHYSICAL ATTACHMENT IDENTIFICATION

The physical point of attachment (PPA) is the point at which a system attaches itself to a physical communications medium. All communication on that physical medium funnels through the PPA.

On systems where a DLS provider supports more than one physical medium, the DLS user must identify which medium it will communicate through. A PPA is identified by a unique PPA identifier. For media that support physical layer multiplexing of multiple channels over a single physical medium (such as the B and D channels of ISDN), the PPA identifier must identify the specific channel over which communication will occur.

Two styles of DLS provider are defined by DLPI, distinguished by the way they enable a DLS user to choose a particular PPA. The style 1 provider assigns a PPA based on the major/minor device the DLS user opened. One possible implementation of a style 1 driver would reserve a major device for each PPA the data link driver would support. This would allow the STREAMS(4) clone open feature to be used for each PPA configured. This style of provider is appropriate when few PPAs will be supported.

If the number of PPAs a DLS provider will support is large, a style 2 provider implementation is more suitable. The style 2 provider requires a DLS user to explicitly identify the desired PPA using a special attach service primitive. For a style 2 driver, the open(2) creates a stream between the DLS user and DLS provider, and the attach primitive then associates a particular PPA with that stream. The format of the PPA identifier is specific to the DLS provider, and should be described in the provider-specific addendum documentation. DLPI provides a mechanism to get and/or modify the physical address. The primitives to handle these functions are described in Appendix A. The physical address value can be modified in a post-attached state. This would modify the value for all streams for that provider for a particular PPA. The physical address cannot be modified if even a single stream for that PPA is in the bound state.

The DLS User uses the supported primitives (DL_ATTACH_REQ(7), DL_BIND_REQ(7), DL_ENABMULTI_REQ(7), DL_PROMISCON_REQ(7)) to define a set of enabled physical and SAP address components on a per Stream basis. It is invalid for a DLS Provider to ever send upstream a data message for which the DLS User on that stream has not requested. The burden is on the provider to enforce by any means that it chooses, the isolation of SAP and physical address space effects on a per-stream basis.

DATA LINK USER IDENTIFICATION

A data link user's identity is established by associating it with a data link service access point (DLSAP),which is the point through which the user will communicate with the data link provider. A DLSAP is identified by a DLSAP address. The DLSAP address identifies a particular data link service access point that is associated with a stream(communication endpoint). A bind service primitive enables a DLS user to either choose a specific DLSAP by specifying its DLSAP address, or to determine the DLSAP associated with a stream by retrieving the bound DLSAP address. This DLSAP address can then be used by other DLS users to access a specific DLS user. The format of the DLSAP address is specific to the DLS provider, and should be described in the provider-specific addendum documentation. However, DLPI provides a mechanism for decomposing the DLSAP address into component pieces. The DL_INFO_ACK(7) primitive returns the length of the SAP component of the DLSAP address, along with the total length of the DLSAP address. Certain DLS Providers require the capability of binding on multiple DLSAP addresses. This can be achieved through subsequent binding of DLSAP addresses. DLPI supports peer and hierarchical binding of DLSAPs. When the User requests peer addressing, the DLSAP specified in a subsequent bind may be used in lieu of the DLSAP bound in the DL_BIND_REQ(7). This will allow for a choice to be made between a number of DLSAPs on a stream when determining traffic based on DLSAP values. An example of this would be to specify various ether_type values as DLSAPs. The DL_BIND_REQ(7), for example, could be issued with ether_type value of IP, and a subsequent bind could be issued with ether type value of ARP. The Provider may now multiplex off of the ether_type field and allow for either IP or ARP traffic to be sent up this stream. When the DLS User requests hierarchical binding, the subsequent bind will specify a DLSAP that will be used in addition to the DLSAP bound using a DL_BIND_REQ(7). This will allow additional information to be specified, that will be used in a header or used for de-multiplexing. An example of this would be to use hierarchical bind to specify the OUI (Organizationally Unique Identifier) to be used by SNAP.

THE CONNECTION MANAGEMENT STREAM

The earlier description of the connection-mode service assumed that a DLS user bound a DLSAP to the stream it would use to receive connect requests. In some instances, however, it is expected that a given service may be accessed through any one of several DLSAPs. To handle this scenario, a separate stream would be required for each possible destination DLSAP, regardless of whether any DLS user actually requested a connection to that DLSAP. Obvious resource problems can result in this scenario. To obviate the need for tying up system resources for all possible destination DLSAPs, a "connection management stream" utility is defined in DLPI. A connection management stream is one that receives any connect requests that are not destined for currently bound DLSAPs capable of receiving connect indications. With this mechanism, a special listener can handle incoming connect requests intended for a set of DLSAPs by opening a connection management stream to the DLS provider that will retrieve all connect requests arriving through a particular PPA. In the model, then, there may be a connection management stream per PPA.

DLPI SERVICES

The various features of the DLPI interface are defined in terms of the services provided by the DLS provider, and the individual primitives that may flow between the DLS user and DLS provider.

The data link provider interface supports three modes of service: connection, connectionless and acknowledged connectionless. The connection mode is circuit-oriented and enables data to be transferred over an established connection in a sequenced manner. The connectionless mode is message-oriented and supports data transfer in self-contained units with no logical relationship required between units. The acknowledged connectionless mode is message-oriented and guarantees that data units will be delivered to the destination user in the order in which they were sent. This specification also defines a set of local management functions that apply to all modes of service. The XID and TEST services that are supported by DLPI are listed below. The DLS User can issue an XID or TEST request to the DLS Provider. The Provider will transmit an XID or TEST frame to the peer DLS Provider. On receiving a response, the DLS Provider sends a confirmation primitive to the DLS User. On receiving an XID or TEST frame from the peer DLS Provider, the local DLS Provider sends up an XID or TEST indication primitive to the DLS User. The User must respond with an XID or TEST response frame to the Provider.

Local Management Services

The local management services apply to the connection, connectionless and acknowledged connectionless modes of transmission. These services, which fall outside the scope of standards specifications, define the method for initializing a stream that is connected to a DLS provider. DLS provider information reporting services are also supported by the local management facilities.

Information Reporting Service

: This service provides information about the DLPI stream to the DLS user. The message DL_INFO_REQ(7) requests the DLS provider to return operating information about the stream. The DLS provider returns the information in a DL_INFO_ACK(7) message.

Attach Service

: The attach service assigns a physical point of attachment (PPA) to a stream. This service is required for style 2 DLS providers (see section 2.3.1, Physical Attachment Identification) to specify the physical medium over which communication will occur. The DLS provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).
A PPA may be disassociated with a stream using the DL_DETACH_REQ(7).

Bind Service

The bind service associates a data link service access point (DLSAP) with a stream. The DLSAP is identified by a DLSAP address. DL_BIND_REQ(7) requests that the DLS provider bind a DLSAP to a stream. It also notifies the DLS provider to make the stream active with respect to the DLSAP for processing connectionless and acknowledged connectionless data transfer and connection establishment requests. Protocol-specifications taken during activation should be described in DLS provider-specific addenda. The DLS provider indicates success with a DL_BIND_ACK(7); failure with a DL_ERROR_ACK(7).

Certain DLS providers require the capability of binding on multiple DLSAP addresses. DL_SUBS_BIND_REQ(7) provides that added capability. The DLS provider indicates success with a DL_SUBS_BIND_ACK(7); failure with a DL_ERROR_ACK(7).

DL_UNBIND_REQ(7) requests the DLS provider to unbind all DLSAP(s) from a stream. The DL_UNBIND_REQ(7) also unbinds all the subsequently bound DLSAPs that have not been unbound. The DLS provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

DL_SUBS_UNBIND_REQ requests the DLS Provider to unbind the subsequently bound DLSAP. The DLS Provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

DL_ENABMULTI_REQ requests the DLS Provider to enable specific multicast addresses on a per stream basis. The Provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

DL_DISABMULTI_REQ requests the DLS Provider to disable specific multicast addresses on a per Stream basis. The Provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

DL_PROMISCON_REQ requests the DLS Provider to enable promiscuous mode on a per Stream basis, either at the physical level or at the SAP level. The Provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

DL_PROMISCOFF_REQ requests the DLS Provider to disable promiscuous mode on a per Stream basis,either at the physical level or at the SAP level. The Provider indicates success with a DL_OK_ACK(7); failure with a DL_ERROR_ACK(7).

Connection-mode Services

The connection-mode services enable a DLS user to establish a data link connection, transfer data over that connection, reset the link, and release the connection when the conversation has terminated.

Connection Establishment Service

The connection establishment service establishes a data link connection between a local DLS user and a remote DLS user for the purpose of sending data. Only one data link connection is allowed on each stream.

Normal Connection Establishment

In the connection establishment model, the calling DLS user initiates connection establishment, while the called DLS user waits for incoming requests. DL_CONNECT_REQ(7) requests that the DLS provider establish a connection. DL_CONNECT_IND(7) informs the called DLS user of the request, which may be accepted using DL_CONNECT_RES(7). DL_CONNECT_CON(7) informs the calling DLS user that the connection has been established.

Once the connection is established, the DLS users may exchange user data using DL_DATA_REQ(7) and DL_DATA_IND(7).

The DLS user may accept an incoming connect request on either the stream where the connect indication arrived or an alternate, responding stream. The responding stream is indicated by a token in the DL_CONNECT_RES(7). This token is a value associated with the responding stream, and is obtained by issuing a DL_TOKEN_REQ(7) on that stream. The DLS provider responds to this request by generating a token for the stream and returning it to the DLS user in a DL_TOKEN_ACK(7).

In the typical connection establishment scenario, the called DLS user processes one connect indication at a time, accepting the connection on another stream. Once the user responds to the current connect indication, the next connect indication (if any) can be processed. DLPI also enables the called DLS user to multi-thread incoming connect indications. The user can receive multiple connect indications before responding to any of them. This enables the DLS user to establish priority schemes on incoming connect requests.

Connection Establishment Rejections

In certain situations, the connection establishment request cannot be completed. The following paragraphs describe the occasions under which DL_DISCONNECT_REQ(7) and DL_DISCONNECT_IND(7) primitives will flow during connection establishment, causing the connect request to be aborted.

Where the DLS provider rejects a connect request for lack of resources or other reason, the DLS provider sends DL_DISCONNECT_IND(7) in response to DL_CONNECT_REQ(7).

Where the calling DLS user chooses to abort a previous connection attempt, the DLS user issues DL_DISCONNECT_REQ(7) at some point following a DL_CONNECT_REQ(7). The resulting sequence of primitives depends on the relative timing of the primitives involved.

Data Transfer Service

: The connection-mode data transfer service provides for the exchange of user data in either direction or inboth directions simultaneously between DLS users. Data is transmitted in logical groups called data link service data units (DLSDUs). The DLS provider preserves both the sequence and boundaries of DLSDUs as they are transmitted.
Normal data transfer is neither acknowledged nor confirmed. It is up to the DLS users, if they so choose,to implement a confirmation protocol. Each DL_DATA_REQ(7) primitive conveys a DLSDU from the local DLS user to the DLS provider. Similarly, each DL_DATA_IND(7) primitive conveys a DLSDU from the DLS provider to the remote DLS user.

Connection Release Service

: The connection release service provides for the DLS users or the DLS provider to initiate the connection release. Connection release is an abortive operation, and any data in transit (has not been delivered to the DLS user) may be discarded. DL_DISCONNECT_REQ(7) requests that a connection be released. DL_DISCONNECT_IND(7) informs the DLS user that a connection has been released. Normally, one DLS user requests disconnection and the DLS provider issues an indication of the ensuing release to the other DLS user.

Reset Service

The reset service may be used by the DLS user to resynchronize the use of a data link connection, or by the DLS provider to report detected loss of data unrecoverable within the data link service.

Invocation of the reset service will unblock the flow of DLSDUs if the data link connection is congested;DLSDUs may be discarded by the DLS provider. The DLS user or users that did not invoke the reset will be notified that a reset has occurred. A reset may require a recovery procedure to be performed by the DLS users.

The interaction between each DLS user and the DLS provider will be one of the following:

---: a DL_RESET_REQ(7) from the DLS user, followed by a DL_RESET_CON(7) from the DLS provider;
---: a DL_RESET_IND(7) from the DLS provider, followed by a DL_RESET_RES(7) from the DLS user. The DL_RESET_REQ(7) acts as a synchronization mark in the stream of DLSDUs that are transmitted by the issuing DLS user;
---: the DL_RESET_IND(7) acts as a synchronization mark in the stream of DLSDUs that are received by the peer DLS user. Similarly, the DL_RESET_RES(7) acts as a synchronization mark in the stream of DLSDUs that are transmitted by the responding DLS user; the DL_RESET_CON(7) acts as a synchronization mark in the stream of DLSDUs that are received by the DLS user which originally issued the reset.

The resynchronizing properties of the reset service are that:

---: No DLSDU transmitted by the DLS user before the synchronization mark in that transmitted stream will be delivered to the other DLS user after the synchronization mark in that received stream.
---: The DLS provider will discard all DLSDUs submitted before the issuing of the DL_RESET_REQ(7) that have not been delivered to the peer DLS user when the DLS provider issues the DL_RESET_IND(7).
---: The DLS provider will discard all DLSDUs submitted before the issuing of the DL_RESET_RES(7) that have not been delivered to the initiator of the DL_RESET_REQ(7) when the DLS provider issues the DL_RESET_CON(7).
---: No DLSDU transmitted by a DLS user after the synchronization mark in that transmitted stream will be delivered to the other DLS user before the synchronization mark in that received stream.

The complete message flow depends on the origin of the reset, which may be the DLS provider or either DLS user.

Connectionless-mode Services

The connectionless-mode services enable a DLS user to transfer units of data to peer DLS users without incurring the overhead of establishing and releasing a connection. The connectionless service does not, however, guarantee reliable delivery of data units between peer DLS users (e.g. lack of flow control may cause buffer resource shortages that result in data being discarded).

Once a stream has been initialized via the local management services, it may be used to send and receive connectionless data units.

Connectionless Data Transfer Service

: The connectionless data transfer service provides for the exchange of user data (DLSDUs) in either direction or in both directions simultaneously without having to establish a data link connection. Data transfer is neither acknowledged nor confirmed, and there is no end-to-end flow control provided. As such, the connectionless data transfer service cannot guarantee reliable delivery of data. However, a specific DLS provider can provide assurance that messages will not be lost, duplicated, or reordered. DL_UNITDATA_REQ(7) conveys one DLSDU to the DLS provider. DL_UNITDATA_IND(7) conveys one DLSDU to the DLS user.

QOS Management Service

: The QOS (Quality of Service) management service enables a DLS user to specify the quality of service it can expect for each invocation of the connectionless data transfer service. The DL_UDQOS_REQ(7) directs the DLS provider to set the QOS parameters to the specified values.

Error Reporting Service

: The connectionless-mode error reporting service may be used to notify a DLS user that a previously sent data unit either produced an error or could not be delivered. This service does not, however, guarantee that an error indication will be issued for every undeliverable data unit.

XID and TEST Service

: The XID and TEST service enables the DLS User to issue an XID or TEST request to the DLS Provider. On receiving a response for the XID or TEST frame transmitted to the peer DLS Provider, the DLS Provider sends up an XID or TEST confirmation primitive to the DLS User. On receiving an XID or TEST frame from the peer DLS Provider, the local DLS Provider sends up an XID or TEST indication respectively to the DLS User. The DLS User must respond with an XID or TEST response primitive. If the DLS User requested automatic handling of the XID or TEST response, at bind time, the DLS Provider will send up an error acknowledgment on receiving an XID or TEST request. Also, no indications will be generated to the DLS User on receiving XID or TEST frames from the remote side.

Acknowledged Connectionless-mode Services

The acknowledged connectionless-mode services are designed for general use for the reliable transfer of informations between peer DLS Users. These services are intended for applications that require acknowledgment of cross-LAN data unit transfer, but wish to avoid the complexity that is viewed as being associated with the connection-mode services. Although the exchange service is connectionless, in sequence delivery is guaranteed for data sent by the initiating station.

Acknowledged Connectionless-mode Data Transfer Services

: The acknowledged connectionless-mode data transfer services provide the means by which the DLS Users can exchange DLSDUs which are acknowledged at the LLC sublayer, without the establishment of a Data Link connection. The services provide a means by which a local DLS User can send a data unit to the peer DLS User, request a previously prepared data unit, or exchange data units with the peer DLS User.

QOS Management Service

: The Quality of Service (QOS) management service enables a DLS User to specify the quality of service it can expect for each invocation of the acknowledged connectionless data transfer service. The DL_UDQOS_REQ(7) directs the DLS provider to set the QOS parameters to the specified values. The normal flow of messages is illustrated in section 3.3.2, (Connectionless mode services).

Error Reporting Service

: The acknowledged connectionless mode error reporting service is the same as the unacknowledged connectionless-mode error reporting service. For the message flow, refer to section 3.3.3.

Local Management

Local management provides the following services:

Information Service

Provides the DLS User with the ability to obtain information concerning the limiting parameters and state associated with the DLS provider and the underlying data link.

DL_INFO_REQ(7) ---: Requests that the DLS provider reply with information concerning the limiting parameters and state associated with the DLS provider and the underlying data link.
DL_INFO_ACK(7) ---: Provides information to the DLS user regarding the limiting parameters and state associated with the DLS provider and the underlying data link.

Token Service

The token service provides the DLS user with the ability to acquire a token that uniquely identifies a DLS provider Stream for the purpose of accepting incoming connection requests on identified Streams.

DL_TOKEN_REQ(7) ---: Requests that the DLS provider identify the Stream upon which the request is initiated with a token uniquely identifying the DLS provider Stream.
DL_TOKEN_ACK(7) ---: Provides the DLS user with a unique token identifying the DLS provider Stream.

Attach Service

Provides the DLS user with the ability to attach a Style 2 DLS provider Stream to an underlying Physical Point of Attachment (PPA) representing a physical interface device.

DL_ATTACH_REQ(7) ---: Requests that the DLS provider attach the DLS provider Stream to a specific Physical Point of Attachment (PPA).

Detach Service

Provides the DLS user with the ability to detach a Style 2 DLS provider Stream from the attached underlying Physical Point of Attachment (PPA).

DL_DETACH_REQ(7) ---: Request that the DLS provider detach the DLS provider Stream from its attached Physical Point of Attachment (PPA).

Bind Service

The Bind Service provides the DLS User with the ability to bind the DLS provider stream to a Service Access Point (SAP) associated with the attached Physical Point of Attachment (PPA).

DL_BIND_REQ(7) ---: Requests that the DLS provider bind the requesting DLS provider Stream to a specific Service Access Point (SAP) associated with the attached Physical Point of Attachment (PPA), and acknowledge the bind with a DL_BIND_ACK(7) primitive.
DL_BIND_ACK(7) ---: Acknowledges to the DLS user that the previously invoked bind request was successful and also provides the complete DLSAP (Data Link Service Access Point) address associated with the bound Service Access Point (SAP).

Unbind Service

The Unbind Service provides the DLS User with the ability to unbund the DLS provider streams from the Service Access Point (SAP) currently associated with the attached Physical Point of Attachment (PPA).

DL_UNBIND_REQ(7) ---: Requests that the DLS provider unbind the requesting DLS provider Stream from all Service Access Points (SAP) to which the Stream is currently bound, and acknowledge the unbinding with a DL_OK_ACK(7) primitive.

Subsequent Bind Service

The Subsequent Bind Service provides the DLS User with the ability to bind to either an additional and equivalent Service Access Point (SAP), DL_PEER_BIND, associated with the Physical Point of Attachment (PPA), or to bind to an additional and subtending Service Access Point (SAP) associated with the currently bound SAP, DL_HIERARCHICAL_BIND.

DL_SUBS_BIND_REQ(7) ---: Requests that the DLS provider bind the requesting DSL provider Stream to a subsequent Service Access Point (SAP), where the requested SAP is either a peer to, DL_PEER_BIND, or hierarchical to, DL_HIERARCHICAL_BIND. the currently bound SAP, and requests that the DLS provider acknowledge the subsequent bind with a DL_SUBS_BIND_ACK(7) primitive.
DL_SUBS_BIND_ACK(7) ---: Acknowledges that the previously requested subsequent bind has completed successfully.

Subsequent Unbind Service

Provides the DLS user with the ability to unbind from a subsequent Service Access Point (SAP).

DL_SUBS_UNBIND_REQ(7) ---: Requests that the DLS provider unbind from the specified subsequent Service Access Point (SAP), and that the DLS provider acknolwege receipt of the primitive with a DL_OK_ACK(7) primitive.

Receipt Acknowledgment Service

Provides the DLS User with the ability to be informed as to the success or failure of a request primitive where the DLS User expects positive or negative acknowledgement.

DL_OK_ACK(7) ---: Provides the DLS user with acknowledgement of successful receipt of a previously issued DLS User primitive.
DL_ERROR_ACK(7) ---: Provides the DLS user with acknowledgement of the unsuccessful receipt of a previously issued DLS User primitive, and the reason for the failure.

Connection Establishment Phase

The connection establishment phase consists of the following services:

Connection Service

Provides the DLS User with the ability to initiate and respond to HDLC or LLC Type 2 connection establishment.

DL_CONNECT_REQ(7) ---: Requests that an HLDC or LLC Type 2 connection be established on an idle data link.
DL_CONNECT_CON(7) ---: Confirms to the DLS User that a previously initiated HDLC or LLC Type 2 connection establishment request has completed successfully and that the data link has transitioned to the data transfer phase.
DL_CONNECT_IND(7) ---: Indicates to the DLS User, as a responder, that the peer DLS User on an idle data link has initiated HDLC or LLC Type 2 connection establishment.
DL_CONNECT_RES(7) ---: Provides the DLS User with the ability to accept an incoming HDLC or LLC Type 2 connection establishment request from the remote DLS User on an otherwise idle data link.

Connection Data Transfer Phase

The connection data transfer phase consists of the following services:

Data Transfer Service

Provides the DLS User with the ability to transfer data toward the peer connected DLS User or to receive data from the peer connected DLS User.

DL_DATA_REQ(7) ---: Transfer data to the peer connected DLS User.
DL_DATA_IND(7) ---: Transfer data from the peer connected DLS User.

Reset Service

Provides the DLS User with the ability to reset a data link connection, or to be informed of the reset of the data link connection by the peer DLS user or DLS provider.

DL_RESET_CON(7) ---: Confirms to the DLS User that the previously initiated reset request has completed.
DL_RESET_IND(7) ---: Indicates to the DLS User that the remote connected DLS User or Provider is resetting the connection, the origin of the reset, and the reason for reset.
DL_RESET_REQ(7) ---: Provides the DLS User with the ability to request that a data link connection be reset.
DL_RESET_RES(7) ---: Provides the DLS User with the ability to accept a remote reset indication to complete the remote provider reset cycle.

Connection Release Phase

The connection release phase consists of the following services:

Release Service

The release service provides the DLS User with the ability to disconnect an HDLC or LLC Type 1 connection-oriented mode data link connection, or to be informed of such a disconnection by the peer DLS user or provider.

DL_DISCONNECT_IND(7) ---: Provides indication that the data link connection was released, the origin of the release, and the reason for release.
DL_DISCONNECT_REQ(7) ---: Requests that a data link connection be released, or that an incoming connection establishment request is to be rejected.

Connectionless Data Transfer Phase

The connectionless data transfer phase consists of the following services:

Data Transfer Service

Provides a service for transferring HDLC or LLC Type 1 connectionless mode data to and from the DLS user.

DL_UNITDATA_REQ(7) ---: Transfers connectionless mode unit data from the DLS User to a peer DLS User.
DL_UNITDATA_IND(7) ---: Transfers connectionless mode unit data from a peer DLS User to the local DLS User.
DL_UDQOS_REQ(7) ---: Establishes the connectionless m ode quality of service to be used in subsequent transfers of HLDC or LLC Type 1 connectionless unit data from the DLS User to peer DLS users.
DL_UDERROR_IND(7) ---: Provides an indicates that there was an error in the transmission of HDLC or LLC Type 1 connectionless mode unit data from the DLS User toward a peer DLS User.

Acknowledged Connectionless Data Transfer Phase

The acknowledged connectionless data transfer phase consists of the following services:

Acknowledged Data Transfer Service

DL_DATA_ACK_REQ(7) ---
DL_DATA_ACK_IND(7) ---
DL_DATA_ACK_STATUS_IND(7) ---

Data Transaction Service

DL_REPLY_IND(7) ---
DL_REPLY_REQ(7) ---
DL_REPLY_STATUS_IND(7) ---
DL_REPLY_UPDATE_REQ(7) ---
DL_REPLY_UPDATE_STATUS_IND(7) ---

XID and Test

The XID and Test functions consist of the following services:

XID Service

A service for passing HDLC or LLC XID messages to and from the DLS user.

DL_XID_CON(7) ---: Passes an HDLC or LLC XID response message to the DLS user.
DL_XID_IND(7) ---: Passes an HDLC or LLC XID command message to the DLS user.
DL_XID_REQ(7) ---: Passes an HDLC or LLC XID command message from the DLS user.
DL_XID_RES(7) ---: Passes an HDLC or LLC XID response message from the DLS user.

TEST Service

A service for passing HDLC or LLC TEST messages to and from the DLS user.

DL_TEST_CON(7) ---: Passes an HDLC or LLC TEST response message to the DLS user.
DL_TEST_IND(7) ---: Passes an HDLC or LLC TEST command message to the DLS user.
DL_TEST_REQ(7) ---: Passes an HDLC or LLC TEST command message from the DLS user.
DL_TEST_RES(7) ---: Passes an HDLC or LLC TEST response message from the DLS user.

Miscellaneous Management

The miscellaneous management functions consist of the following services:

Physical Address Service

The Physical Address Service provides the DLS User with the ability to interrogate and modify the physical address associated with the attached Physical Point of Appearance (PPA).

DL_SET_PHYS_ADDR_REQ(7) ---: Sets the physical address value for all Streams for the DLS provider for a particular PPA.
DL_PHYS_ADDR_REQ(7) ---: This primitive requests the DLS provider to return either the default (factory) or current value of the physical address associated with the Stream depending upon the value of the address type selected in the request.
DL_PHYS_ADDR_ACK(7) ---: This primitive returns the value for the physical address to the DLS user in response to a DL_PHYS_ADDR_REQ(7) primitive.

Promiscuous Monitoring Service

The Promiscuous Monitoring Service provides the DLS User with the ability to request that data associated with all physical addresses for the attached Physical Point of Attachment, for all Service Access Points (SAP) associated with the PPA, or all multicast addresses on the attached PPA, be also delivered to the DLS user.

DL_PROMISCON_REQ(7) ---: Requests that the DLS provider provide promiscuous access to data traversing the Physical Point of Attachment (PPA) for all physical addresses, all Service Access Points (SAP), or all multicast addresses, and that the DLS provider acknowledge the successful receipt of the primitive by issuing a DL_OK_ACK(7) primitive.
DL_PROMISCOFF_REQ(7) ---: Request that the DLS provider cease promiscuous access to data traversing the Physical Point of Attachment (PPA) for all physical addresses, all Service Access Points (SAP), or all multicast addresses, and that the DLS provider acknowledge the successful receipt of the primitive by issuing a DL_OK_ACK(7) primitive.

Multicast Address Service

The Multicast Address Service provides the DLS User with the ability to request that data sent to a bound Service Access Point (SAP) with a specified multicast destination address also be delivered, or cease to be delivered, to the DLS User.

DL_ENABMULTI_REQ(7) ---: Requests that the DLS provider also deliver messages addressed to the specified multicast address, and that the DLS provider acknowledge successful receipt of the primitive by issuing a DL_OK_ACK(7) primitive.
DL_DISABMULTI_REQ(7) ---: Requests that the DLS provider cease delivering messages addressed to the specified multicast address, and that the DLS provider acknowledge successful receipt of the primitive by issuing a DL_OK_ACK(7) primitive.

Statistics Service

The Statistics Service provides a mechanism whereby the DLS User may acquire information concerning collected statistics for a Physical Point of Attachment (PPA), Service Access Point (SAP), or Data Link Connection (DLC), associated with a given DLS provider Stream.

DL_GET_STATISTICS_REQ(7) ---: Requests that the DLS provider collect statistics associated with the DLS Provider Stream and acknolwedge successful receipt of the primitive and the collected statistics by issuing a DL_GET_STATISTICS_ACK(7) primitive.
DL_GET_STATISTICS_ACK(7) ---: Acknowledges to the DLS User the successful receipt of a previously issued DL_GET_STATISTICS_REQ(7) primitive and the collected statistics.

HP-UX DLPI EXTENSIONS

The following HP extensions to the DLPI specification are documented in the HP DLPI Programmer's Guide[1].

General Extensions

The following general extensions apply to all DLS providers:

DL_HP_PPA_REQ(7) ---: Requests a list of all the valid PPAs currently installed in the system.
DL_HP_PPA_ACK(7) ---: Response to a request for all the valid PPAs currently installed in the system.
DL_HP_MULTICAST_LIST_REQ(7) ---: Requests that the DLS provider return a list of all the currently enabled multicast addresses on a specific LAN interface corresponding to the Stream on which the primitive is issued.
DL_HP_MULTICAST_LIST_ACK(7) ---: Response to a DL_HP_MULTICAST_LIST_REQ(7) with a complete list of the multicast addresses for a specific LAN interface corresponding to the Stream on which the primitive is issued.
DL_HP_RAWDATA_REQ(7) ---: Requests that the DLS provider sends one completely formated DLSDU to a peer DLS user. The DLSDU is assumed to have a complete link and MAC level header included.
DL_HP_RAWDATA_IND(7) ---: Indicates one completely formatted DLSDU from the DLS provider to the DLS user. The DLSDU contains the complete link and MAC level headers.
DL_HP_RESET_STATS_REQ(7) ---: Requests of the DLS provider that the statistics being collected associated with the DLS User Stream be reset to zero values, and that the DLS provider acknowledge successful receipt of the primitive with a DL_OK_ACK(7) primitive.
DL_HP_GET_64BIT_STATS_REQ(7) ---: Requests that the DLS User retrieve and provide 64-bit statistics instead of 32-bit statistics, and that the DLS Provider acknowledge successful receipt of the primitive and the retrieved 64-bit statistics by issuing a DL_HP_GET_64BIT_STATS_ACK(7) primitive.
DL_HP_GET_64BIT_STATS_ACK(7) ---: Acknowledges the successful receipt of a DL_HP_GET_64BIT_STATS_REQ(7) primitive and provides the 64-bit statistics collected. DL_HP_GET_64BIT_STATS_REQ(7) primitive and delivers the retrieved 64-bit statistics to the DLS User.
DL_HP_NOTIFY_EVENT_REQ(7) ---: Requests that the DLS provider provide, or cease providing, event indications upon the occurence of specified DLS provider or underlying data link events, using the DL_HP_LINK_UP_IND(7) and DL_HP_LINK_DOWN_IND(7) primitives, and that the DLS provider acknowledge receipt of the primitive with a DL_OK_ACK(7) primitive.
DL_HP_LINK_DOWN_IND(7) ---: Provides indication to the DLS User that the data link associated with the PPA attached to the Stream upon which the indiciation is issued, has entered a down state.
DL_HP_LINK_UP_IND(7) ---: Provides indication to the DLS User that the data link associated with the PPA attached to the Stream upon which the indiciation is issued, has entered a up state.
DL_HP_HW_RESET_REQ(7) ---: Requests that the DLS Provider reset the hardware associated with the underlying data link for the Physical Point of Attachment attached to the issuing DLS User Stream.

Connection-Mode Extensions

The following extensions apply to DLS providers operating in the connection-mode (DL_CLDLS).

DL_HP_INFO_REQ(7) ---: Requests that the DLS provider provide the state of the connection on a DLPI Stream.
DL_HP_INFO_ACK(7) ---: This primitive is issued by the DLS provider response to a DL_HP_INFO_REQ(7) primitive and conveys the state of the connection on a DLPI Stream.
DL_HP_SET_ACK_TO_REQ(7) ---: Requests that the DLS provider set the ACK timeout to the specified value.
DL_HP_SET_P_TO_REQ(7) ---: Requests that the DLS provider set the P timeout to the specified value.
DL_HP_SET_REJ_TO_REQ(7) ---: Requests that the DLS provider set the REJ timeout to the specified value.
DL_HP_SET_BUSY_TO_REQ(7) ---: Requests that the DLS provider set the BUSY timeout to the specified value.
DL_HP_SET_SEND_ACK_TO_REQ(7) ---: Requests that the DLS provider set the SEND_ACK timeout to the specified value.
DL_HP_SET_MAX_RETRIES_REQ(7) ---: Requests that the DLS provider set the maximum number of retries to the specified value.
DL_HP_SET_ACK_THRESHOLD_REQ(7) ---: Requests that the DLS provider set the acknowledgement threshold to the specified value.
DL_HP_SET_LOCAL_WIN_REQ(7) ---: Requests that the DLS provider set the local window size to the specified value.
DL_HP_SET_REMOTE_WIN_REQ(7) ---: Requests that the DLS provider set the remote window size to the specified value.
DL_HP_CLEAR_STATS_REQ(7) ---: Requests that the DLS provider zero the statistics that are reported in the DL_HP_INFO_ACK(7) primitive.
DL_HP_SET_LOCAL_BUSY_REQ(7) ---: Requests that the DLS provider inform the remote system that the local system is busy and cannot accept new data packets.
DL_HP_CLEAR_LOCAL_BUSY_REQ(7) ---: Requests that the DLS provider inform the remote system that the local system is no longer busy and is again able to accept new data packets.

SOLARIS EXTENSIONS

The following extensions are documented in the Sun Solaris DLPI documentation[2].

Notification Extensions

The Notification Service extension provides the DLS User with the ability to request that it be notified when specific DLS provider events occur and indication of such notification.

DL_NOTIFY_REQ(7) ---: Requests that the DLS provider acknowledge receipt of the primitive with a DL_NOTIFY_ACK(7) primitive, acknowledging the support and activation of notifications for specified DLS provider events.
DL_NOTIFY_ACK(7) ---: Acknowledges the receive of a previously issued DLS user DL_NOTIFY_REQ(7) primitive requesting the support and activation or detactivation of specified notifications.
DL_NOTIFY_IND(7) ---: Provides notification to the DLS user that a specified DLS provider event has occurred, as well a notifying the DLS user of the initial state of an event when notifications are first requested.

Capability and Control Extensions

The capability and control extensions provide a mechanism whereby a DLS user may obtain information concerning the support and current state of an DLS provider's underlying device driver implementation. A DLS user may also control, configure, enable or disable the supported underlying capabilities.

DL_CAPABILITY_REQ(7) ---: control capabilties of underlying driver. Requests that the DLS provider report, enable or disable the underlying control capabilities of its underlying device driver.
DL_CAPABILITY_ACK(7) ---: acknowledges control capablities of underlying driver. Acknowledges to the DLS user the retrieval, enabling or disabling of the underlying control capabilities of the DLS provider's underlying device driver.
DL_CONTROL_REQ(7) ---: control underlying driver. Requests that the DLS provider control (add, delete, flush, update, get or set) data elements associated with an underlying device driver implementation capability.
DL_CONTROL_ACK(7) ---: acknowledge control of the underlying driver. Acknowledges the addition, deletion, flushing, update, retrieval or setting of data elements associated with an underlying device driver implementation capability.
DL_INTR_MODE_REQ(7) ---

Aggregation Extensions

The Aggrevation Service extensions provide the DLS user with the ability to add individual data links to an aggregate data link, to remove individual data links from an aggregate, and to access individual data links that form an aggregate.

DL_AGGR_REQ(7) ---: Requests that the DLS provider add the data link associated with the requesting DLS provider Stream to a specified aggregrate and acknowledge receipt of the successful reception of the primitive with a DL_OK_ACK(7) primitive.
DL_AGGR_IND(7) ---: Indicates to the DLS user that the indicating DLS provider Stream has successfully completed being added to the specified aggregate.
DL_UNAGGR_REQ(7) ---: Requests that the DLS provider remote the data link associated with the requesting DLS provider Stream from the specified aggregate and acknolwege successful receipt of the primitive with a DL_OK_ACK(7) primitive.
DL_PASSIVE_REQ(7) ---: Requests that the requesting DLS provider Stream be permitted access to individual data links that are part of an aggregate, and that the DLS provider acknowledge successful receipt of the primitive with a DL_OK_ACK(7) primitive.

NOTICES

HP extension primitives are HP-UX®-specific; it may be necessary to define _HPUX_SOURCE before including <sys/dlpi.h> to expose the definitions and declarations associated with HP extension primitives. It may also be necessary to include the <sys/dlpi_ext.h> header file to expose the definitions and declarations associated with HP extension primitives.

Sun extension primitives are Solaris®-specific; it may be necessary to define _SUN_SOURCE before including <sys/dlpi.h> to expose the definitions and declarations associated with Sun extension primitives.

COMPATIBILITY

This interface is compatible with DLPI Revision 2[3], and implementations based on DLPI, including Solaris®[2], HP-UX®[1], and AIX®[4], with the following portability considerations:

---
---

See also the individual DLPI standard and extension primitives, dlpi_ioctl(4), and STREAMS(9).

CONFORMANCE

This interface conforms to DLPI Revision 2[3].

HISTORY

The Data Link Provider Interface first appeared in SVR 4[5].

REFERENCES

[1]: HP-UX DLPI, HP DLPI Programmer's Guide -- HP-UX 11i v3, February 2007, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. [Part No: 5991-7498] <http://docs.hp.com/>
[2]: Solaris® 11, Solaris 11 Docmentation, 2008, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[3]: DLPI, Data Link Provider Interface (DLPI) Specification, Revision 2.0.0, Draft 2, August 20, 1991, (Parsippany, New Jersey), UNIX. International,Inc., UNIX International Press. <http://www.openss7.org/doc/dlpi.pdf>
[4]: AIX Version 6.1, AIX Version 6.1 Technical Reference: Communications, Volume 1, First Edition, November 2007, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. [SC23-6610-00] <http://publib.boulder.ibm.com/>
[5]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[6]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[7]: Advanced Programming in the UNIX®Environment, 15th edition, December 1997, (Reading, Massachusetts), W. R. Stevens, Addison Wesley. [ISBN 0-201-56317-7]