Previous section.

Data Link Provider Interface (DLPI), Version 2
Copyright © 2000 The Open Group

DLPI Primitives

The kernel-level interface to the data link layer defines a STREAMS-based message interface between the provider of the data link service (DLS provider) and the consumer of the data link service (DLS user). STREAMS provides the mechanism in which DLPI primitives may be passed between the DLS user and DLS provider.

Before DLPI primitives can be passed between the DLS user and the DLS provider, the DLS user must establish a stream to the DLS provider using open(). The DLS provider must therefore be configured as a STREAMS driver. When interactions between the DLS user and DLS provider have completed, the stream may be closed.

The STREAMS messages used to transport data link service primitives across the interface have one of the following formats:

The information contained in the M_PROTO or M_PCPROTO message blocks must begin on a byte boundary that is appropriate for structure alignment (for example, word-aligned on the AT&T 3B2 Computer). STREAMS will allocate buffers that begin on such a boundary. However, these message blocks may contain information whose representation is described by a length and an offset within the block. An example is the DLSAP address (dl_addr_length and dl_addr_offset) in the DL_BIND_ACK primitive. The offset of such information within the message block is not guaranteed to be properly aligned for casting the appropriate data type (such as an int or a struct). Allowable Sequence of DLPI Primitives defines the sequence in which DLPI primitives can be passed between DLS user and DLS provider, and Precedence of DLPI Primitives summarizes the precedence rules associated with each primitive for ordering the primitives on the DLS provider and DLS user queues.

The following sections describe the format of the primitives that support the services described in the previous chapter. The primitives are grouped into four general categories for presentation:

Three types are used to build the DLPI primitives. The normative definitions of t_scalar_t and t_uscalar_t are to be found in the Networking Services Specification (see the referenced XNS specification), but are repeated here for informational purposes. uint16_t is one of the fixed width types defined in <sys/inttypes.h>.

t_scalar_t and t_uscalar_t are, respectively, a signed and an unsigned opaque integral type of equal length of at least 32 bits1.

Local Management Service Primitives

This section describes the local management service primitives that are common to the connection, connectionless and acknowledged connectionless service modes. These primitives support the Information Reporting, Attach, Bind, Enabling/Disabling of multicast addresses, and Turning On/Off the promiscuous mode. Once a stream has been opened by a DLS user, these primitives initialize the stream, preparing it for use.

PPA Initialization/De-initialization

The PPA associated with each stream must be initialized before the DLS provider can transfer data over the medium. The initialization and de-initialization of the PPA is a network management issue, but DLPI must address the issue because of the impact such actions will have on a DLS user. More specifically, DLPI requires the DLS provider to initialize the PPA associated with a stream at some point before it completes the processing of the DL_BIND_REQ. Guidelines for initialization and de-initialization of a PPA by a DLS provider are presented here.

A DLS provider may initialize a PPA using either of the following methods:

A specific DLS provider may support either of these methods, or possibly some combination of the two, but the method implemented has no impact on the DLS user. From the DLS user's viewpoint, the PPA is guaranteed to be initialized on receipt of a DL_BIND_ACK. For automatic initialization, this implies that the DL_BIND_ACK may not be issued until the initialization has completed.

If pre-initialization has not been performed and/or automatic initialization fails, the DLS provider will fail the DL_BIND_REQ. Two errors, DL_INITFAILED and DL_NOTINIT, may be returned in the DL_ERROR_ACK response to a DL_BIND_REQ if PPAinitialization fails. DL_INITFAILED is returned when a DLS provider supports automatic PPA initialization, but the initialization attempt failed. DL_NOTINIT is returned when the DLS provider requires pre-initialization, but the PPA is not initialized before the DL_BIND_REQ is received.

A DLS provider may handle PPA de-initialization using one of the following methods:

A specific DLS provider may support any of these methods, or possibly some combination of them, but the method implemented has no impact on the DLS user. From the DLS user's viewpoint, the PPA is guaranteed to be initialized and available for transmission until it closes or unbinds the stream associated with the PPA. DLS provider-specific addendum documentation should describe the method chosen for PPA initialization and de-initialization.

List of Local Management Service Primitives

The local management service primitives are listed below and are defined in the following man-pages:

DL_INFO_REQ
DL_INFO_ACK
DL_ATTACH_REQ
DL_DETACH_REQ
DL_BIND_REQ
DL_BIND_ACK
DL_UNBIND_REQ
DL_SUBS_BIND_REQ
DL_SUBS_BIND_ACK
DL_SUBS_UNBIND_REQ
DL_ENABMULTI_REQ
DL_DISABMULTI_REQ
DL_PROMISCON_REQ
DL_PROMISCOFF_REQ
DL_OK_ACK
DL_ERROR_ACK

Connection-mode Service Primitives

Scope

This section describes the service primitives that support the connection-mode service of the data link layer. These primitives support the connection establishment,connection-mode data transfer, and connection release services described earlier.

Multi-threaded Connection Establishment

In the connection establishment model, the calling DLS user initiates a request for a connection, and the called DLS user receives each request and either accepts or rejects it. In the simplest form (single-threaded), the called DLS user is passed a connect indication and the DLS provider holds any subsequent indications until a response for the current outstanding indication is received. At most one connect indication is outstanding at any time.

DLPI also enables a called DLS user to multi-thread connect indications and responses. This capability is desirable, for example, when imposing a priority scheme on all DLS users attempting to establish a connection. The DLS provider will pass all connect indications to the called DLS user (up to some preestablished limit as set by DL_BIND_REQ and DL_BIND_ACK). The called DLS user may then respond to the requests in any order.

To support multi-threading,a correlation value is needed to associate responses with the appropriate connect indication. A correlation value is contained in each DL_CONNECT_IND, and the DLS user must use this value in the DL_CONNECT_RES or DL_DISCONNECT_REQ primitive used to accept or reject the connect request. The DLS user can also receive a DL_DISCONNECT_IND with a correlation value when the calling DLS user or the DLS provider abort a connect request.

Once a connection has been accepted or rejected, the correlation value has no meaning to a DLS user. The DLS provider may reuse the correlation value in another DL_CONNECT_IND. Thus, the lifetime of a correlation value is the duration of the connection establishment phase, and as good programming practice it should not be used for any other purpose by the DLS provider.

The DLS provider assigns the correlation value for each connect indication. Correlation values must be unique among all outstanding connect indications on a given stream. The values may, but need not, be unique across all streams to the DLS provider. The correlation value must be a positive, non-zero value. There is no implied sequencing of connect indications using the correlation value; the values do not have to increase sequentially for each new connect indication.


List of Connection-mode Service Primitives

The connection-mode service primitives are listed below and are defined in the following man-pages:

DL_CONNECT_REQ
DL_CONNECT_IND
DL_CONNECT_RES
DL_CONNECT_CON
DL_TOKEN_REQ
DL_TOKEN_ACK
DL_DATA_REQ
DL_DATA_IND
DL_DISCONNECT_REQ
DL_DISCONNECT_IND
DL_RESET_REQ
DL_RESET_IND
DL_RESET_RES
DL_RESET_CON

Connectionless-mode Service Primitives

Scope

This section describes the primitives that support the connectionless-mode service of the data link layer. These primitives support the connectionless data transfer service described earlier.

List of Connectionless-mode Service Primitives

The connectionless-mode service primitives are listed below and are defined in the following man-pages:

DL_UNITDATA_REQ
DL_UNITDATA_IND
DL_UDERROR_IND
DL_UDQOS_REQ

Primitives to handle XID and TEST operations

Scope

This section describes the service primitives that support the XID and TEST operations. The DLS User can issue these primitives to the DLS Provider requesting the provider to send an XID or a TEST frame. On receipt of an XID or TEST frame from the remote side, the DLS Provider can send the appropriate indication to the User.

List of Primitives Handling XID and TEST operations

The primitives which handle XID and TEST operations are listed below and are defined in the following man-pages:

DL_TEST_REQ
DL_TEST_IND
DL_TEST_RES
DL_TEST_CON
DL_XID_REQ
DL_XID_IND
DL_XID_RES
DL_XID_CON

Acknowledged Connectionless-mode Service Primitives

Scope

This section describes the primitives that support the acknowledged connectionless-mode service of the data link layer. These primitives support the acknowledged connectionless data transfer service described earlier.

List of Acknowledged Connectionless-mode Service Primitives

The acknowledged connectionless-mode service primitives are listed below and are defined in the following man-pages:

DL_DATA_ACK_REQ
DL_DATA_ACK_IND
DL_DATA_ACK_STATUS_IND
DL_REPLY_REQ
DL_REPLY_IND
DL_REPLY_STATUS_IND
DL_REPLY_UPDATE_REQ
DL_REPLY_UPDATE_STATUS_IND


Footnotes

1.
To forestall portability problems, it is recommended that applications should not use values larger than 232 - 1.

Contents Next section Index