DLPI Primitives

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:

• One M_PROTO message block followed by zero or more M_DATA blocks. The M_PROTO message block contains the data link layer service primitive type and all relevant parameters associated with the primitive. The M_DATA block(s) contain any DLS user data that might be associated with the service primitive.

• One M_PCPROTO message block containing the data link layer service primitive type and all relevant parameters associated with the service primitive.

• One or more M_DATA message blocks conveying user data.

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:

• Local Management Service Primitives

• Connection-mode Service Primitives

• Connectionless-mode Service Primitives

• Acknowledged Connectionless-mode Service Primitives

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 bits¹.

Local Management Service Primitives

PPA Initialization/De-initialization

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

• pre-initialized by some network management mechanism before the DL_BIND_REQ is received

• automatic initialization on receipt of a DL_BIND_REQ or DL_ATTACH_REQ.

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:

• automatic de-initialization upon receipt of the final DL_DETACH_REQ (for style 2 providers) or DL_UNBIND_REQ (for style 1 providers), or upon closing of the last stream associated with the PPA

• automatic de-initialization after expiration of a timer following the last DL_DETACH_REQ, DL_UNBIND_REQ, or close as appropriate

• no automatic de-initialization;administrative intervention is required to de-initialize the PPA at some point after it is no longer being accessed.

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

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

Multi-threaded Connection Establishment

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

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

List of Connectionless-mode Service Primitives

DL_UNITDATA_REQ
DL_UNITDATA_IND
DL_UDERROR_IND
DL_UDQOS_REQ

Primitives to handle XID and TEST operations

Scope

List of Primitives Handling XID and TEST operations

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

List of Acknowledged Connectionless-mode Service Primitives

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 2³² - 1.