Data Link Provider Interface

Data Link Provider Interface

1 Introduction

This document specifies a STREAMS kernel-level instantiation of the ISO Data Link Service Definition DIS 8886¹ and Logical Link Control DIS 8802/2 (LLC)². Where the two standards do not conform, DIS 8886 prevails.

The Data Link Provider Interface (DLPI) enables a data link service 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 X.25 LAPB, BX.25 level 2, SDLC, ISDN LAPD, Ethernet(TM), CSMA/CD, FDDI, token ring, token bus, and Bisync. Among the expected data link service users are implementations of the OSI network layer and SNA path control.

The interface specifies access to data link service providers, and does not define a specific protocol implementation. Thus, issues of network management, protocol performance, and performance analysis tools are beyond the scope of this document and should be addressed by specific implementations of a data link provider. However, accompanying each provider implementation should be information that describes the protocol-specific behavior of that provider. Currently, there are plans to come up with a set of implementor's agreements/guidelines for common data link providers. These agreements will address issues such as DLSAP address space, subsequent addresses, PPA access and control, QoS, supported services, etc.

This specification assumes the reader is familiar with OSI Reference Model[4] terminology, OSI Data Link Services, and STREAMS.

1.1 Document Organization

This specification is organized as follows:

• Model of the Data Link Layer, presents background on the structure of the data link layer of the OSI Reference Model, and explains the intended architecture in the STREAMS environment. Data link addressing concepts are also presented.
• DLPI Services, presents an overview of the services provided by DLPI.
• DLPI Primitives, describes the detailed syntax and semantics of each DLPI primitive that crosses the data link interface.
• Quality of Data Link Service, describes the quality-of-service parameters supported by DLPI and the rules for negotiating/selecting the values of those parameters.
• Optional Primitives to perform Essential Management Functions, optional primitives to perform certain essential management functions.
• Allowable Sequence of DLPI Primitives, describes the allowable sequence of DLPI primitives that may be issued across the interface.
• Precedence of DLPI Primitives, presents a summary of the precedence of DLPI primitives as they are queued by the DLS provider and/or DLS user.
• Glossary of DLPI Terms and Acronyms, presents a Glossary of DLPI Terms and Acronyms.
• Guidelines for Protocol Independent DLS Users, summarizes guidelines a DLS user implementation must follow to be fully protocol-independent.
• Required Information for DLS Provider-Specific Addenda, presents the information that should be documented for each DLS provider implementation.
• DLPI Header File, presents the header file containing DLPI structure and constant definitions needed by a DLS user or provider implemented to use the interface.

2 Model of the Data Link Layer

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.

2.1 Model of the Service Interface

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 following figure depicts the abstract view of DLPI.

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 development environment, constitute a major portion of this effort. The service primitives that make up these interfaces are defined as STREAMS messages that are transferred between the user and provider of the service. DLPI is one such kernel-level interface, and is targeted for STREAMS protocol modules that either use or provide data link services. In addition, user programs that wish to access a STREAMS-based data link provider directly may do so using the putmsg(2) and getmsg(2) system calls.

Referring to the abstract view of DLPI (Figure 1), the DLS provider is configured as a STREAMS 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.

2.2 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.

2.2.1 Connection-mode Service

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

2.2.1.1 Local Management

This phase enables a DLS user to initialize a stream for use in communication and establish an identity with the DLS provider.

2.2.1.2 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.

2.2.1.3 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.

2.2.1.4 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.

2.2.2 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.

2.2.3 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.

2.3 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. The following figure illustrates the components of this identification approach, which are explained below.

2.3.1 Physical Attachment Identification

The physical point of attachment (PPA in Figure 2) 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 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 Optional Primitives to perform Essential Management Functions. 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, DL_BIND_REQ, DL_ENABMULTI_REQ, DL_PROMISCON_REQ) 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.

2.3.2 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 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. 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, 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. 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.

If a DLS Provider supports peer subsequent bind operations, the first SAP that is bound is used as the source SAP when there is ambiguity.

DLPI supports the ability to associate several streams with a single DLSAP, where each stream may be a unique data link connection endpoint. However, not all DLS providers can support such configurations because some DLS providers may have no mechanism beyond the DLSAP address for distinguishing multiple connections. In such cases, the provider will restrict the DLS user to one stream per DLSAP.

2.4 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 utility is defined in DLPI. A 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.

3 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.

The services are tabulated below and described more fully in the remainder of this section.

3.1 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.

3.1.1 Information Reporting Service

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

3.1.2 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 Physical Attachment Identification) to specify the physical medium over which communication will occur. The DLS provider indicates success with a DL_OK_ACK; failure with a DL_ERROR_ACK. The normal message sequence is illustrated in the following figure.

A PPA may be disassociated with a stream using the DL_DETACH_REQ. The normal message sequence is illustrated in the following figure.

3.1.3 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 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-specific actions taken during activation should be described in DLS provider-specific addenda.

The DLS provider indicates success with a DL_BIND_ACK; failure with a DL_ERROR_ACK.

Certain DLS providers require the capability of binding on multiple DLSAP addresses. DL_SUBS_BIND_REQ provides that added capability. The DLS provider indicates success with a DL_SUBS_BIND_ACK; failure with a DL_ERROR_ACK. The normal flow of messages is illustrated in the following figure.

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

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

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; failure with a DL_ERROR_ACK.

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; failure with a DL_ERROR_ACK.

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; failure with a DL_ERROR_ACK.

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; failure with a DL_ERROR_ACK.

3.2 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.

3.2.1 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.

3.2.1.1 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 requests that the DLS provider establish a connection. DL_CONNECT_IND informs the called DLS user of the request, which may be accepted using DL_CONNECT_RES. DL_CONNECT_CON informs the calling DLS user that the connection has been established.

The normal sequence of messages is illustrated in the following figure.

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

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. This token is a value associated with the responding stream, and is obtained by issuing a DL_TOKEN_REQ 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. The normal sequence of messages for obtaining a token is illustrated in the following figure.

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.

3.2.1.2 Connection Establishment Rejections

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

The following figure illustrates the situation where the called DLS user chooses to reject the connect request by issuing DL_DISCONNECT_REQ instead of

The following figure illustrates the situation where the DLS provider rejects a connect request for lack of resources or other reason. The DLS provider sends DL_DISCONNECT_IND in response to DL_CONNECT_REQ.

The following figures illustrate the situation where the calling DLS user chooses to abort a previous connection attempt. The DLS user issues DL_DISCONNECT_REQ at some point following a DL_CONNECT_REQ. The resulting sequence of primitives depends on the relative timing of the primitives involved, as defined in the following time sequence diagrams.

3.2.2 Data Transfer Service

The connection-mode data transfer service provides for the exchange of user data in either direction or in both 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 primitive conveys a DLSDU from the local DLS user to the DLS provider. Similarly, each DL_DATA_IND primitive conveys a DLSDU from the DLS provider to the remote DLS user. The normal flow of messages is illustrated in the figure below.

3.2.3 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 requests that a connection be released. DL_DISCONNECT_IND 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, as illustrated by the message flow in the following figure.

The next figure illustrates that when two DLS users independently invoke the connection release service, neither receives a DL_DISCONNECT_IND.

The next figure illustrates that when the DLS provider initiates the connection release service, each DLS user receives a DL_DISCONNECT_IND.

The next figure illustrates that when the DLS provider and the local DLS user simultaneously invoke the connection release service, the remote DLS user receives a DL_DISCONNECT_IND.

3.2.4 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 from the DLS user, followed by a DL_RESET_CON from the DLS provider;
• a DL_RESET_IND from the DLS provider, followed by a DL_RESET_RES from the DLS user.

The DL_RESET_REQ acts as a synchronization mark in the stream of DLSDUs that are transmitted by the issuing DLS user; the DL_RESET_IND acts as a synchronization mark in the stream of DLSDUs that are received by the peer DLS user. Similarly, the DL_RESET_RES acts as a synchronization mark in the stream of DLSDUs that are transmitted by the responding DLS user; the DL_RESET_CON 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 that have not been delivered to the peer DLS user when the DLS provider issues the DL_RESET_IND.
• The DLS provider will discard all DLSDUs submitted before the issuing of the DL_RESET_RES that have not been delivered to the initiator of the DL_RESET_REQ when the DLS provider issues the DL_RESET_CON.
• 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. The following figure illustrates the message flow for a reset invoked by one DLS user.

The following figure illustrates the message flow for a reset invoked by both DLS users simultaneously.

The following figure illustrates the message flow for a reset invoked by the DLS provider.

The following figure illustrates the message flow for a reset invoked simultaneously by one DLS user and the DLS provider.

3.3 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.

3.3.1 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 conveys one DLSDU to the DLS provider. DL_UNITDATA_IND conveys one DLSDU to the DLS user. The normal flow of messages is illustrated in the figure below.

3.3.2 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 directs the DLS provider to set the QoS parameters to the specified values. The normal flow of messages is illustrated in the figure below.

3.3.3 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.

3.3.4 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.

The normal flow of messages is illustrated in the figure below.

3.4 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.

3.4.1 Acknowledged Connectionless-mode Data Transfer Services

The acknowledged connectionless-mode data transfer services provide the means by which the DLS User scan 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.

The next figure illustrates the acknowledged connectionless-mode data unit exchange service.

The next figure illustrates the Reply Data Unit Preparation service.

3.4.2 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 directs the DLS provider to set the QoS parameters to the specified values. The normal flow of messages is illustrated in Connectionless-mode Services.

3.4.3 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 Error Reporting Service (1).

3.5 An Example

To bring it all together, the following example illustrates the primitives that flow during a complete, connection-mode sequence between stream open and stream close.

4 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(2). 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 (e.g. 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 structure).

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 section. 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

4.1 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.

4.1.1 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 the following methods:

• pre-initialized by some network management mechanism before the DL_BIND_REQ is received; or
• 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 PPA initialization 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 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; or
• 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.

4.1.2 Message DL_INFO_REQ (dl_info_req_t)

Requests information of the DLS provider about the DLPI stream. This information includes a set of provider-specific parameters, as well as the current state of the interface.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
     } dl_info_req_t;
     

Parameters

dl_primitive

conveys DL_INFO_REQ.

State

The message is valid in any state in which a local acknowledgment is not pending, as described in Allowable Sequence of DLPI Primitives.

New State

The resulting state is unchanged.

Response

The DLS provider responds to the information request with a DL_INFO_ACK.

4.1.3 Message DL_INFO_ACK (dl_info_ack_t)

This message is sent in response to DL_INFO_REQ; it conveys information about the DLPI stream to the DLS user.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_max_sdu;
             ulong dl_min_sdu;
             ulong dl_addr_length;
             ulong dl_mac_type;
             ulong dl_reserved;
             ulong dl_current_state;
             long dl_sap_length;
             ulong dl_service_mode;
             ulong dl_qos_length;
             ulong dl_qos_offset;
             ulong dl_qos_range_length;
             ulong dl_qos_range_offset;
             ulong dl_provider_style;
             ulong dl_addr_offset;
             ulong dl_version;
             ulong dl_brdcst_addr_length;
             ulong dl_brdcst_addr_offset;
             ulong dl_growth;
     } dl_info_ack_t;
     

Parameters

dl_primitive

conveys DL_INFO_ACK.

dl_max_sdu

conveys the maximum number of bytes that may be transmitted in a DLSDU. This value must be a positive integer that is greater than or equal to the value of dl_min_sdu.

dl_min_sdu

conveys the minimum number of bytes that may be transmitted in a DLSDU. The value is never less than one.

dl_addr_length

conveys the length, in bytes, of the provider's DLSAP address. In the case of a hierarchical subsequent bind, the length returned is the total length i.e. Physical address + SAP + subsequent address length.

dl_mac_type

conveys the type of medium supported by this DLPI stream. Possible values include:

DL_CSMACD

The medium is Carrier Sense Multiple Access with Collision Detection (ISO8802/3).

DL_TPB

The medium is Token-Passing Bus (ISO 8802/4).

DL_TPR

The medium is Token-Passing Ring (ISO 8802/5).

DL_METRO

The medium is Metro Net (ISO 8802/6).

DL_ETHER

The medium is Ethernet Bus.

DL_HDLC

The medium is a bit synchronous communication line.

DL_CHAR

The medium is a character synchronous communication line (e.g. BISYNC).

DL_CTCA

The medium is a channel-to-channel adapter.

DL_FDDI

The medium is a Fiber Distributed Data Interface.

DL_OTHER

Any other medium not listed above.

dl_reserved

is a reserved field whose value must be set to zero.

dl_current_state

conveys the state of the DLPI interface for the stream when the DLS provider issued this acknowledgment. See Allowable Sequence of DLPI Primitives, for a list of DLPI states and an explanation of each.

dl_sap_length

indicates the current length of the SAP component of the DLSAP address. It may have a negative, zero or positive value. A positive value indicates the ordering of the SAP and PHYSICAL component within the DLSAP address as SAP component followed by PHYSICAL component. A negative value indicates PHYSICAL followed by the SAP. A zero value indicates that no SAP has yet been bound. The absolute value of the dl_sap_length provides the length of the SAP component within the DLSAP address.

dl_service_mode

if returned before the DL_BIND_REQ is processed, this conveys which service modes (connection-mode, connectionless-mode or acknowledged connectionless-mode, or any combination of these modes) the DLS provider can support. It contains a bit-mask specifying one or more than one of the following values:

DL_CODLS

connection-oriented data link service;

DL_CLDLS

connectionless data link service;

DL_ACLDLS

acknowledged connectionless data link service;

Once a specific service mode has been bound to the stream, this field returns that specific service mode.

dl_qos_length

conveys the length, in bytes, of the negotiated/selected values of the quality of service (QoS) parameters. Quality of Data Link Service, describes quality of service and its associated parameters completely. For connection-mode service, the returned values are those agreed during negotiation. For connectionless-mode service, the values are those currently selected by the DLS user. If quality of service has not yet been negotiated, default values will be returned; these values correspond to those that will be applied by the DLS provider on a connect request in connection-mode service, or those that will be applied to each data unit transmission in connectionless-mode service. If the DLS provider supports both connection-mode and connectionless-mode services but the DLS user has not yet bound a specific service mode, the DLS provider may return either connection-mode or connectionless-mode QoS parameter values.

The QoS values are conveyed in the structures defined in QOS Data Structures. For any parameter the DLS provider does not support or cannot determine, the corresponding entry will be set to DL_UNKNOWN. If the DLS provider does not support any QoS parameters, this length field will be set to zero.

dl_qos_offset

conveys the offset from the beginning of the M_PCPROTO block where the current quality of service parameters begin.

dl_qos_range_length

conveys the length, in bytes, of the available range of QoS parameter values supported by the DLS provider. For connection-mode service, this is the range available to the calling DLS user in a connect request. For connectionless-mode, this is the range available for each data unit transmission. If the DLS provider supports both connection-mode and connectionless-mode services but the DLS user has not yet bound a specific service mode, the DLS provider may return either connection-mode or connectionless-mode QoS parameter values. The range of available QoS values is conveyed in the structures defined in QOS Data Structures. For any parameter the DLS provider does not support or cannot determine, the corresponding entry will be set to DL_UNKNOWN. If the DLS provider does not support any QoS parameters, this length field will be set to zero.

dl_qos_range_offset

conveys the offset from the beginning of the M_PCPROTO block where the available range of quality of service parameters begins.

dl_provider_style

conveys the style of DLS provider associated with the DLPI stream (see Physical Attachment Identification). The following provider classes are defined:

DL_STYLE1

The PPA is implicitly attached to the DLPI stream by opening the appropriate major/minor device number.

DL_STYLE2

The DLS user must explicitly attach a PPA to the DLPI stream using DL_ATTACH_REQ.

DLS users implemented in a protocol-independent manner must access this parameter to determine whether the DLS attach service must be invoked explicitly.

dl_addr_offset

conveys the offset of the address that is bound to the associated stream. If the DLS user issues a DL_INFO_REQ prior to binding a DLSAP, the value of dl_addr_len will be 0 and consequently indicate that there has been no address bound.

dl_version

indicates the current version of the DLPI that's supported.

dl_brdcst_addr_length

indicates the length of the physical broadcast address.

dl_brdcst_addr_offset

indicates the offset of the physical broadcast address from the beginning of the M_PCPROTO block.

dl_growth

conveys a growth field for future use. The value of this field will be zero.

State

The message is valid in any state in response to a DL_INFO_REQ.

New State

The resulting state is unchanged.

4.1.4 Message DL_ATTACH_REQ (dl_attach_req_t)

Requests the DLS provider associate a physical point of attachment (PPA) with a stream. DL_ATTACH_REQ is needed for style 2 DLS providers to identify the physical medium over which communication will transpire. The request may not be issued to a style 1 DLS provider; doing so may cause errors.

The DLS provider may initialize the physical line on receipt of this primitive or the DL_BIND_REQ. Otherwise, the line must be initialized through some management mechanism before this request is issued by the DLS user. Either way, the physical link must be initialized and ready for use on successful completion of the DL_BIND_REQ.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_ppa;
     } dl_attach_req_t;
     

Parameters

dl_primitive

conveys DL_ATTACH_REQ.

dl_ppa

conveys the identifier of the physical point of attachment to be associated with the stream. The format of the identifier is provider-specific, and it must contain sufficient information to distinguish the desired PPA from all possible PPAs on a system.

At a minimum, this must include identification of the physical medium over which communication will transpire. For media that multiplex multiple channels over a single physical medium, this identifier should also specify a specific channel to be used for communication(where each channel on a physical medium is associated with a separate PPA).

Because of the provider-specific nature of this value, DLS user software that is to be protocol independent should avoid hard-coding the PPA identifier. The DLS user should retrieve the necessary PPA identifier from some other entity (such as a management entity) and insert it without inspection into the DL_ATTACH_REQ.

State

The message is valid in state DL_UNATTACHED.

New State

The resulting state is DL_ATTACH_PENDING.

Response

If the attach request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNBOUND.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_BADPPA

The specified PPA is invalid.

DL_ACCESS

The DLS user did not have proper permission to use the requested PPA.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.1.5 Message DL_DETACH_REQ (dl_detach_req_t)

For style 2 DLS providers, this requests the DLS provider detach a physical point of attachment (PPA) from a stream. The request may not be issued to a style 1 DLS provider; doing so may cause errors.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
     } dl_detach_req_t;
     

Parameters

dl_primitive

conveys DL_DETACH_REQ.

State

The message is valid in state DL_UNBOUND.

New State

The resulting state is DL_DETACH_PENDING.

Response

If the detach request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNATTACHED.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.1.6 Message DL_BIND_REQ (dl_bind_req_t)

Requests the DLS provider bind a DLSAP to the stream. The DLS user must identify the address of the DLSAP to be bound to the stream. For connection-mode service, the DLS user also indicates whether it will accept incoming connection requests on the stream. Finally, the request directs the DLS provider to activate the stream associated with the DLSAP.

A stream is viewed as active when the DLS provider may transmit and receive protocol data units destined to or originating from the stream. The PPA associated with each stream must be initialized upon completion of the processing of the DL_BIND_REQ (see PPA Initialization / De-initialization). More specifically, the DLS user is ensured that the PPA is initialized when the DL_BIND_ACK is received. If the PPA cannot be initialized, the DL_BIND_REQ will fail.

A stream may be bound as a "connection management" stream, such that it will receive all connect requests that arrive through a given PPA (see The Connection Management Stream). In this case, the dl_sap will be ignored.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_sap;
             ulong dl_max_conind;
             ushort dl_service_mode;
             ushort dl_conn_mgmt;
             ulong dl_xidtest_flg;
     } dl_bind_req_t;
     

Parameters

dl_primitive

conveys DL_BIND_REQ.

dl_sap

conveys sufficient information to identify the DLSAP that will be bound to the DLPI stream (see DLPI Addressing, for a description of DLSAP addresses). The format of this information is specific to a given DLS provider, and may contain the full DLSAP address or some portion of that address sufficient to uniquely identify the DLSAP in question. The full address of the bound DLSAP will be returned in the DL_BIND_ACK.

The following rules are used by the DLS provider when binding a DLSAP address.

• The DLS provider must define and manage its DLSAP address space.
• DLPI allows the same DLSAP to be bound to multiple streams, but a given DLS provider may need to restrict its address space to allow one stream per DLSAP.
• The DLS provider may not be able to bind the specified DLSAP address for the following reasons:
  1. the DLS provider may statically associate a specific DLSAP with each stream; or
  2. the DLS provider may only support one stream per DLSAP and the DLS user attempted to bind a DLSAP that was already bound to another stream.

  In case (1), the value of dl_sap is ignored by the DLS provider and the DL_BIND_ACK returns the DLSAP address that is already associated with the stream. In case (2), if the DLS provider cannot bind the given DLSAP to the stream, it may attempt to choose an alternate DLSAP and return that on the DL_BIND_ACK. If an alternate DLSAP cannot be chosen, the DLS provider will return a DL_ERROR_ACK and set dl_errno to DL_NOADDR.

Because of the provider-specific nature of the DLSAP address, DLS user software that is to be protocol independent should avoid hard-coding this value. The DLS user should retrieve the necessary DLSAP address from some other entity (such as a management entity or higher layer protocol entity) and insert it without inspection into the DL_BIND_REQ.

dl_max_conind

conveys the maximum number of outstanding DL_CONNECT_IND messages allowed on the DLPI stream. If the value is zero, the stream cannot accept any DL_CONNECT_IND messages. If greater than zero, the DLS user will accept DL_CONNECT_IND messages up to the given value before having to respond with a DL_CONNECT_RES or a DL_DISCONNECT_REQ (see Multi-threaded Connection Establishment, for details on how this value is used to support multi-threaded connect processing). The DLS provider may not be able to support the value supplied in dl_max_conind, as specified by the following rules.

• If the provider cannot support the specified number of outstanding connect indications, it should set the value down to a number it can support.
• Only one stream that is bound to the indicated DLSAP may have an allowed number of maximum outstanding connect indications greater than zero. If a DL_BIND_REQ specifies a value greater than zero, but another stream has already bound itself to the DLSAP with a value greater than zero, the DLS provider will fail the request, setting dl_errno to DL_BOUND on the DL_ERROR_ACK.
• If a stream with dl_max_conind greater than zero is used to accept a connection, the stream will be found busy during the duration of the connection, and no other streams may be bound to the same DLSAP with a value of dl_max_conind greater than zero. This restriction prevents more than one stream bound to the same DLSAP from receiving connect indications and accepting connections. Accepting a connection on such a stream is only allowed if there is just a single outstanding connect indication being processed.
• A DLS user should always be able to request a dl_max_conind value of zero, since this indicates to the DLS provider that the stream will only be used to originate connect requests.
• A stream with a negotiated value of dl_max_conind that is greater than zero may not originate connect requests.

This field is ignored in connectionless-mode service.

dl_service_mode

conveys the desired mode of service for this stream, and may contain one of the following:

DL_CODLS

connection-oriented data link service;

DL_CLDLS

connectionless data link service.

DL_ACLDLS

acknowledged connectionless data link service.

If the DLS provider does not support the requested service mode, a DL_ERROR_ACK will be generated, specifying DL_UNSUPPORTED.

dl_conn_mgmt

if non-zero, indicates that the stream is the "connection management" stream for the PPA to which the stream is attached. When an incoming connect request arrives, the DLS provider will first look for a stream bound with dl_max_conind greater than zero that is associated with the destination DLSAP. If such a stream is found, the connect indication will be issued on that stream. Otherwise, the DLS provider will issue the connect indication on the "connection management" stream for that PPA, if one exists. Only one "connection management" stream is allowed per PPA, so an attempt to bind a second "connection management" stream on a PPA will fail with the DLPI error set to DL_BOUND. When dl_conn_mgmt is non-zero, the value of dl_sap will be ignored. In connectionless-mode service, dl_conn_mgmt is ignored by the DLS provider.

dl_xidtest_flg

indicates to the DLS Provider that XID and/or TEST responses for this stream are to be automatically generated by the DLS Provider. The DLS Provider will not generate DL_XID_IND and/or DL_TEST_IND, and will error a DL_XID_REQ and/or DL_TEST_REQ. If the DLS Provider does not support automatic handling of XID and/or TEST responses, a DL_ERROR_ACK will be generated, specifying DL_NOAUTO, DL_NOXIDAUTO or DL_NOTESTAUTO. If the Provider receives an XID or TEST request from the DLS User, a DL_ERROR_ACK will be generated specifying DL_XIDAUTO or DL_TESTAUTO respectively.

The dl_xidtest_flg contains a bit-mask specifying zero or more of the following values:

DL_AUTO_XID

Automatically respond to XID commands.

DL_AUTO_TEST

Automatically respond to TEST commands.

State

The message is valid in state DL_UNBOUND.

New State

The resulting state is DL_BIND_PENDING.

Response

If the bind request is successful, DL_BIND_ACK is sent to the DLS user resulting in state DL_IDLE.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_BADADDR

The DLSAP address information was invalid or was in an incorrect format.

DL_INITFAILED

Automatic initialization of the PPA failed.

DL_NOTINIT

The PPA had not been initialized prior to this request.

DL_ACCESS

The DLS user did not have proper permission to use the requested DLSAP address.

DL_BOUND

The DLS user attempted to bind a second stream to a DLSAP with dl_max_conindgreater than zero, or the DLS user attempted to bind a second "connection management" stream to a PPA.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_NOADDR

The DLS provider could not allocate a DLSAP address for this stream.

DL_UNSUPPORTED

The DLS provider does not support requested service mode on this stream.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

DL_NOAUTO

Automatic handling of XID and TEST responses not supported.

DL_NOXIDAUTO

Automatic handling of XID response not supported.

DL_NOTESTAUTO

Automatic handling of TEST response not supported.

4.1.7 Message DL_BIND_ACK (dl_bind_ack_t)

Reports the successful bind of a DLSAP to a stream, and returns the bound DLSAP address to the DLS user. This primitive is generated in response to a DL_BIND_REQ.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_sap;
             ulong dl_addr_length;
             ulong dl_addr_offset;
             ulong dl_max_conind;
             ulong dl_xidtest_flg;
     } dl_bind_ack_t;
     

Parameters

dl_primitive

conveys DL_BIND_ACK.

dl_sap

conveys the DLSAP address information associated with the bound DLSAP. It corresponds to the dl_sap field of the associated DL_BIND_REQ, which contains either part or all of the DLSAP address. For that portion of the DLSAP address conveyed in the DL_BIND_REQ, this field contains the corresponding portion of the address for the DLSAP that was actually bound.

dl_addr_length

conveys the length of the complete DLSAP address that was bound to the DLPI stream (see DLPI Addressing, for a description of DLSAP addresses). The bound DLSAP is chosen according to the guidelines presented under the description of DL_BIND_REQ.

dl_addr_offset

conveys the offset from the beginning of the M_PCPROTO block where the DLSAP address begins.

dl_max_conind

conveys the allowed, maximum number of outstanding DL_CONNECT_IND messages to be supported on the DLPI stream. If the value is zero, the stream cannot accept any DL_CONNECT_IND messages. If greater than zero, the DLS user will accept DL_CONNECT_IND messages up to the given value before having to respond with a DL_CONNECT_RES or a DL_DISCONNECT_REQ. The rules for negotiating this value are presented under the description of DL_BIND_REQ.

dl_xidtest_flg

conveys the XID and TEST responses supported by the provider.

DL_AUTO_XID

XID response handled automatically.

DL_AUTO_TEST

TEST response handled automatically.

If no value is specified in dl_xidtest_flg, it indicates that automatic handling of XID and TEST responses is not supported by the Provider.

State

The message is valid in state DL_BIND_PENDING.

New State

The resulting state is DL_IDLE.

4.1.8 Message DL_UNBIND_REQ (dl_unbind_req_t)

Requests the DLS provider to unbind the DLSAP that had been bound by a previous DL_BIND_REQ from this stream. If one or more DLSAPs were bound to the stream using a DL_SUBS_BIND_REQ, and have not been unbound using a DL_SUBS_UNBIND_REQ, the DL_UNBIND_REQ will unbind all the subsequent DLSAPs for that stream along with the DLSAP bound using the previous DL_BIND_REQ.

At the successful completion of the request, the DLS user may issue a new DL_BIND_REQ for a potentially new DLSAP.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
     } dl_unbind_req_t;
     

Parameters

dl_primitive

conveys DL_UNBIND_REQ.

State

The message is valid in state DL_IDLE.

New State

The resulting state is DL_UNBIND_PENDING.

Response

If the unbind request is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_UNBOUND.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.1.9 Message DL_SUBS_BIND_REQ (dl_subs_bind_req_t)

Requests the DLS provider bind a subsequent DLSAP to the stream. The DLS user must identify the address of the subsequent DLSAP to be bound to the stream.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_subs_sap_offset;
             ulong dl_subs_sap_length;
             ulong dl_subs_bind_class;
     } dl_subs_bind_req_t;
     

Parameters

dl_primitive

conveys DL_SUBS_BIND_REQ.

dl_subs_sap_offset

conveys the offset of the DLSAP from the beginning of the M_PROTO block.

dl_subs_sap_length

conveys the length of the specified DLSAP.

dl_subs_bind_class

Specifies either peer or hierarchical addressing

DL_PEER_BIND

specifies peer addressing. The DLSAP specified is used in lieu of the DLSAP bound in the BIND request.

DL_HIERARCHICAL_BIND

specifies hierarchical addressing. The DLSAP specified is used in addition to the DLSAP specified using the BIND request.

State

The message is valid in state DL_IDLE.

New State

The resulting state is DL_SUBS_BIND_PND.

Response

If the subsequent bind request is successful, DL_SUBS_BIND_ACK is sent to the DLS user resulting instate DL_IDLE.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_BADADDR

The DLSAP address information was invalid or was in an incorrect format.

DL_ACCESS

The DLS user did not have proper permission to use the requested DLSAP address.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A System error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

DL_UNSUPPORTED

Requested addressing class not supported.

DL_TOOMANY

Limit exceeded on the maximum number of DLSAPs per stream.

4.1.10 Message DL_SUBS_BIND_ACK (dl_subs_bind_ack_t)

Reports the successful bind of a subsequent DLSAP to a stream, and returns the bound DLSAP address to the DLS user. This primitive is generated in response to a DL_SUBS_BIND_REQ.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_subs_sap_offset;
             ulong dl_subs_sap_length;
     } dl_subs_bind_ack_t;
     

Parameters

dl_primitive

conveys DL_SUBS_BIND_ACK.

dl_subs_sap_offset

conveys the offset of the DLSAP from the beginning of the M_PCPROTO block.

dl_subs_sap_length

conveys the length of the specified DLSAP.

State

The message is valid in state DL_SUBS_BIND_PND

New State

The resulting state is DL_IDLE.

4.1.11 Message DL_SUBS_UNBIND_REQ (dl_subs_unbind_req_t)

Requests the DLS Provider to unbind the DLSAP that had been bound by a previous DL_SUBS_BIND_REQ from this stream.

Message Format

The message consists of one M_PROTO message block, which contains the following structure:

     typedef struct {
             ulong dl_primitive;
             ulong dl_subs_sap_offset;
             ulong dl_subs_sap_length;
     } dl_subs_unbind_req_t;
     

Parameters

dl_primitive

conveys DL_SUBS_UNBIND_REQ.

dl_subs_sap_offset

conveys the offset of the DLSAP from the beginning of the M_PROTO block.

dl_subs_sap_length

conveys the length of the specified DLSAP.

State

The message is valid in state DL_IDLE.

New State

The resulting state is DL_SUBS_UNBIND_PND.

Response

If the unbind request is successful, a DL_OK_ACK is sent to the DLS User. The resulting state is DL_IDLE.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for failure

DL_OUTSTATE

The primitive was issued from an invalid state

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

DL_BADADDR

The DLSAP address information was invalid or was in an incorrect format.

4.1.12 Message DL_ENABMULTI_REQ (dl_enabmulti_req_t)

Requests the DLS Provider to enable specific multicast addresses on a per Stream basis. It is invalid for a DLS Provider to pass upstream messages that are destined for any address other than those explicitly enabled on that Stream by the DLS User.

Message Format

The message consists of one M_PROTO message block, which contains the following structure:

     typedef struct {
             ulong dl_primitive;
             ulong dl_addr_length;
             ulong dl_addr_offset;
     } dl_enabmulti_req_t;
     

Parameters

dl_primitive

conveys DL_ENABMULTI_REQ

dl_addr_length

conveys the length of the multicast address

dl_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the multicast address begins

State

This message is valid in any state in which a local acknowledgment is not pending with the exception of DL_UNATTACHED.

New State

The resulting state is unchanged.

Response

If the enable request is successful, a DL_OK_ACK is sent to the DLS user.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for failure

DL_BADADDR

Address information was invalid or was in an incorrect format.

DL_TOOMANY

Too many multicast address enable attempts. Limit exceeded.

DL_OUTSTATE

The primitive was issued from an invalid state

DL_NOTSUPPORTED

The primitive is known, but not supported by the DLS Provider.

4.1.13 Message DL_DISABMULTI_REQ (dl_disabmulti_req_t)

Requests the DLS Provider to disable specific multicast addresses on a per Stream basis.

Message Format

The message consists of one M_PROTO message block, which contains the following structure:

     typedef struct {
             ulong dl_primitive;
             ulong dl_addr_length;
             ulong dl_addr_offset;
     } dl_disabmulti_req_t;
     

Parameters

dl_primitive

conveys DL_DISABMULTI_REQ

dl_addr_length

conveys the length of the physical address

dl_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the multicast address begins

State

This message is valid in any state in which a local acknowledgment is not pending with the exception of DL_UNATTACHED.

New State

The resulting state is unchanged.

Response

If the disable request is successful, a DL_OK_ACK is sent to the DLS user.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for failure

DL_BADADDR

Address information was invalid or in an incorrect format.

DL_NOTENAB

Address specified is not enabled.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_NOTSUPPORTED

Primitive is known, but not supported by the DLS Provider.

4.1.14 Message DL_PROMISCON_REQ (dl_promiscon_req_t)

This primitive requests the DLS Provider to enable promiscuous mode on a per Stream basis, either at the physical level or at the SAP level.

The DL Provider will route all received messages on the media to the DLS User until either a DL_DETACH_REQ or a DL_PROMISCOFF_REQ is received or the Stream is closed.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_level;
     } dl_promiscon_req_t;
     

Parameters

dl_primitive

conveys DL_PROMISCON_REQ

dl_level

indicates promiscuous mode at the physical or SAP level

DL_PROMISC_PHYS

indicates promiscuous mode at the physical level

DL_PROMISC_SAP

indicates promiscuous mode at the SAP level

DL_PROMISC_MULTI

indicates promiscuous mode for all multicast addresses

State

The message is valid in any state when there is no pending acknowledgment.

New State

The resulting state is unchanged.

Response

If enabling of promiscuous mode is successful, a DL_OK_ACK is returned. Otherwise, a DL_ERROR_ACK is returned.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state

DL_SYSERR

A System error has occurred and the UNIX System error is indicated in the DL_ERROR_ACK.

DL_NOTSUPPORTED

Primitive is known but not supported by the DLS Provider

DL_UNSUPPORTED

Requested service is not supplied by the provider.

4.1.15 Message DL_PROMISCOFF_REQ (dl_promiscoff_req_t)

This primitive requests the DLS Provider to disable promiscuous mode on a per Stream basis, either at the physical level or at the SAP level.

Message Format

The message consists of one M_PROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_level;
     } dl_promiscoff_req_t;
     

Parameters

dl_primitive

conveys DL_PROMISCOFF_REQ

dl_level

indicates promiscuous mode at the physical or SAP level

DL_PROMISC_PHYS

indicates promiscuous mode at the physical level

DL_PROMISC_SAP

indicates promiscuous mode at the SAP level

DL_PROMISC_MULTI

indicates promiscuous mode for all multicast addresses

State

The message is valid in any state in which the promiscuous mode is enabled and there is no pending acknowledgment.

New State

The resulting state is unchanged.

Response

If the promiscuous mode disabling is successful, a DL_OK_ACK is returned. Otherwise, a DL_ERROR_ACK is returned.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state

DL_SYSERR

A System error has occurred and the UNIX System error is indicated in the DL_ERROR_ACK.

DL_NOTSUPPORTED

Primitive is known but not supported by the DLS Provider

DL_NOTENAB Mode not enabled.

4.1.16 Message DL_OK_ACK (dl_ok_ack_t)

Acknowledges to the DLS user that a previously issued request primitive was received successfully. It is only initiated for those primitives that require a positive acknowledgment.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correct_primitive;
     } dl_ok_ack_t;
     

Parameters

dl_primitive

conveys DL_OK_ACK.

dl_correct_primitive

identifies the successfully received primitive that is being acknowledged.

State

The message is valid in response to a DL_ATTACH_REQ, DL_DETACH_REQ, DL_UNBIND_REQ, DL_CONNECT_RES, DL_RESET_RES, DL_DISCONNECT_REQ, DL_SUBS_UNBIND_REQ, DL_PROMISCON_REQ, DL_ENABMULTI_REQ, DL_DISABMULTI_REQ or DL_PROMISCOFF_REQ from any of several states as defined in Allowable Sequence of DLPI Primitives.

New State

The resulting state depends on the current state and is defined fully in Allowable Sequence of DLPI Primitives.

4.1.17 Message DL_ERROR_ACK (dl_error_ack_t)

Informs the DLS user that a previously issued request or response was invalid. It conveys the identity of the primitive in error, a DLPI error code, and if appropriate, a UNIX system error code.

Whenever this primitive is generated, it indicates that the DLPI state is identical to what it was before the erroneous request or response.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_error_primitive;
             ulong dl_errno;
             ulong dl_unix_errno;
     } dl_error_ack_t;
     

Parameters

dl_primitive

conveys DL_ERROR_ACK.

dl_error_prim

identifies the primitive in error.

dl_errno

conveys the DLPI error code associated with the failure. See the individual request or response for the error codes that are applicable. In addition to those errors:

• DL_BADPRIM error is returned if an unrecognized primitive is issued by the DLS user.
• DL_NOTSUPPORTED error is returned if an unsupported primitive is issued by the DLS user.

dl_unix_errno

conveys the UNIX system error code associated with the failure. This value should be non-zero only when dl_errno is set to DL_SYSERR. It is used to report UNIX system failures that prevent the processing of a given request or response.

State

The message is valid in every state where an acknowledgment or confirmation of a previous request or response is pending.

New State

The resulting state is that from which the acknowledged request or response was generated.

4.2 Connection-mode Service Primitives

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.

4.2.1 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 pre-established 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.

4.2.2 Message DL_CONNECT_REQ (dl_connect_req_t)

Requests the DLS provider establish a data link connection with a remote DLS user. The request contains the DLSAP address of the remote (called) DLS user and quality of service parameters to be negotiated during connection establishment.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_qos_length;
             ulong dl_qos_offset;
             ulong dl_growth;
     } dl_connect_req_t;
     

Parameters

dl_primitive

conveys DL_CONNECT_REQ.

dl_dest_addr_length

conveys the length of the DLSAP address that identifies the DLS user with whom a connection is to be established. If the called user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_qos_length

conveys the length of the quality of service (QoS) parameter values desired by the DLS user initiating a connection. The desired QoS values are conveyed in the appropriate structure defined in QOS Data Structures. A full specification of these QoS parameters and rules for negotiating their values is presented in Quality of Data Link Service.

If the DLS user does not wish to specify a particular QoS value, the value DL_QOS_DONT_CARE may be specified. If the DLS user does not care to specify any QoS parameter values, this field may be set to zero.

dl_qos_offset

conveys the offset from the beginning of the M_PROTO message block where the quality of service parameters begin.

dl_growth

defines a growth field for future enhancements to this primitive. Its value must be set to zero.

State

The message is valid in state DL_IDLE.

New State

The resulting state is DL_OUTCON_PENDING.

Response

There is no immediate response to the connect request. However, if the connect request is accepted by the called DLS user, DL_CONNECT_CON is sent to the calling DLS user, resulting in state DL_DATAXFER.

If the connect request is rejected by the called DLS user, the called DLS user cannot be reached, or the DLS provider and/or called DLS user do not agree on the specified quality of service, a DL_DISCONNECT_IND is sent to the calling DLS user, resulting in state DL_IDLE.

If the request is erroneous, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_BADADDR

The destination DLSAP address was in an incorrect format or contained invalid information.

DL_BADQOSPARAM

The quality of service parameters contained invalid values.

DL_BADQOSTYPE

The quality of service structure type was not supported by the DLS provider.

DL_ACCESS

The DLS user did not have proper permission to use the requested DLSAP address.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.2.3 Message DL_CONNECT_IND (dl_connect_ind_t)

Conveys to the local DLS user that a remote (calling) DLS user wishes to establish a data link connection. The indication contains the DLSAP address of the calling and called DLS user, and the quality of service parameters as specified by the calling DLS user and negotiated by the DLS provider.

The DL_CONNECT_IND also contains a number that allows the DLS user to correlate a subsequent DL_CONNECT_RES, DL_DISCONNECT_REQ, or DL_DISCONNECT_IND with the indication (see Multi-threaded Connection Establishment).

The number of outstanding DL_CONNECT_IND primitives issued by the DLS provider must not exceed the value of dl_max_conind as returned on the DL_BIND_ACK. If this limit is reached and an additional connect request arrives, the DLS provider must not pass the corresponding connect indication to the DLS user until a response is received for an already outstanding indication.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correlation;
             ulong dl_called_addr_length;
             ulong dl_called_addr_offset;
             ulong dl_calling_addr_length;
             ulong dl_calling_addr_offset;
             ulong dl_qos_length;
             ulong dl_qos_offset;
             ulong dl_growth;
     } dl_connect_ind_t;
     

Parameters

dl_primitive

conveys DL_CONNECT_IND.

dl_correlation

conveys the correlation number to be used by the DLS user to associate this message with the DL_CONNECT_RES, DL_DISCONNECT_REQ, or DL_DISCONNECT_IND that is to follow. This value, then, enables the DLS user to multi-thread connect indications and responses. All outstanding connect indications must have a distinct, non-zero correlation value set by the DLS provider.

dl_called_addr_length

conveys the length of the address of the DLSAP for which this DL_CONNECT_IND primitive is intended. This address is the full DLSAP address specified by the calling DLS user and is typically the value returned on the DL_BIND_ACK associated with the given stream.

dl_called_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the called DLSAP address begins.

dl_calling_addr_length

conveys the length of the address of the DLSAP from which the DL_CONNECT_REQ primitive was sent.

dl_calling_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the calling DLSAP address begins.

dl_qos_length

conveys the range of quality of service parameter values desired by the calling DLS user and negotiated by the DLS provider. The range of QoS values is conveyed in the appropriate structure defined in QOS Data Structures. A full specification of these QoS parameters and rules for negotiating their values is presented in Quality of Data Link Service.

For any parameter the DLS provider does not support or cannot determine, the corresponding parameter values will be set to DL_UNKNOWN. If the DLS provider does not support any QoS parameters, this length field will be set to zero.

dl_qos_offset

conveys the offset from the beginning of the M_PROTO message block where the quality of service parameters begin.

dl_growth

defines a growth field for future enhancements to this primitive. Its value will be set to zero.

State

The message is valid in state DL_IDLE, or state DL_INCON_PENDING when the maximum number of outstanding DL_CONNECT_IND primitives has not been reached on this stream.

New State

The resulting state is DL_INCON_PENDING, regardless of the current state.

Response

The DLS user must eventually send either DL_CONNECT_RES to accept the connect request or DL_DISCONNECT_REQ to reject the connect request. In either case, the responding message must convey the correlation number received in the DL_CONNECT_IND. The DLS provider will use the correlation number to identify the connect request to which the DLS user is responding.

4.2.4 Message DL_CONNECT_RES (dl_connect_res_t)

Directs the DLS provider to accept a connect request from a remote (calling) DLS user on a designated stream. The DLS user may accept the connection on the same stream where the connect indication arrived, or on a different stream that has been previously bound. The response contains the correlation number from the corresponding DL_CONNECT_IND, selected quality of service parameters, and an indication of the stream on which to accept the connection.

After issuing this primitive, the DLS user may immediately begin transferring data using the DL_DATA_REQ primitive. If the DLS provider receives one or more DL_DATA_REQ primitives from the local DLS user before it has completed connection establishment, however, it must queue the data transfer requests internally until the connection is successfully established.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correlation;
             ulong dl_resp_token;
             ulong dl_qos_length;
             ulong dl_qos_offset;
             ulong dl_growth;
     } dl_connect_res_t;
     

Parameters

dl_primitive

conveys DL_CONNECT_RES.

dl_correlation

conveys the correlation number that was received with the DL_CONNECT_IND associated with the connection request. The DLS provider will use the correlation number to identify the connect indication to which the DLS user is responding.

dl_resp_token

if non-zero, conveys the token associated with the responding stream on which the DLS provider is to establish the connection; this stream must be in the state DL_IDLE. The token value for a stream can be obtained by issuing a DL_TOKEN_REQ on that stream. If the DLS user is accepting the connection on the stream where the connect indication arrived, this value must be zero. See Multi-threaded Connection Establishment, for a description of the connection response model.

dl_qos_length

conveys the length of the quality of service parameter values selected by the called DLS user. The selected QoS values are conveyed in the appropriate structure as defined in QOS Data Structures. A full specification of these QoS parameters and rules for negotiating their values is presented in Quality of Data Link Service.

If the DLS user does not care which value is selected for a particular QoS parameter, the value DL_QOS_DONT_CARE may be specified. If the DLS user does not care which values are selected for all QoS parameters, this field may be set to zero.

dl_qos_offset

conveys the offset from the beginning of the M_PROTO message block where the quality of service parameters begin.

dl_growth

defines a growth field for future enhancements to this primitive. Its value must be set to zero.

State

The primitive is valid in state DL_INCON_PENDING.

New State

The resulting state is DL_CONN_RES_PENDING.

Response

If the connect response is successful, DL_OK_ACK is sent to the DLS user. If no outstanding connect indications remain, the resulting state for the current stream is DL_IDLE; otherwise it remains DL_INCON_PENDING. For the responding stream (designated by the parameter dl_resp_token), the resulting state is DL_DATAXFER. If the current stream and responding stream are the same, the resulting state of that stream is DL_DATAXFER. These streams may only be the same when the response corresponds to the only outstanding connect indication.

If the request fails, DL_ERROR_ACK is returned on the stream where the DL_CONNECT_RES primitive was received, and the resulting state of that stream and the responding stream is unchanged.

Reasons for Failure

DL_BADTOKEN

The token for the responding stream was not associated with a currently open stream. The quality of service parameters contained invalid values.

DL_BADQOSTYPE

The quality of service structure type was not supported by the DLS provider.

DL_BADCORR

The correlation number specified in this primitive did not correspond to a pending connect indication.

DL_ACCESS

The DLS user did not have proper permission to use the responding stream.

DL_OUTSTATE

The primitive was issued from an invalid state, or the responding stream was not in a valid state for establishing a connection.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

DL_PENDING

Current stream and responding stream is the same and there is more than one outstanding connect indication.

4.2.5 Message DL_CONNECT_CON (dl_connec t_con_t)

Informs the local DLS user that the requested data link connection has been established. The primitive contains the DLSAP address of the responding DLS user and the quality of service parameters as selected by the responding DLS user.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_resp_addr_length;
             ulong dl_resp_addr_offset;
             ulong dl_qos_length;
             ulong dl_qos_offset;
             ulong dl_growth;
     } dl_connect_con_t;
     

Parameters

dl_primitive

conveys DL_CONNECT_CON.

dl_resp_addr_length

conveys the length of the address of the responding DLSAP associated with the newly established data link connection.

dl_resp_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the responding DLSAP address begins.

dl_qos_length

conveys the length of the quality of service parameter values selected by the responding DLS user. The selected QoS values are conveyed in the appropriate structure defined in QOS Data Structures. A full specification of these QoS parameters and rules for negotiating their values is presented in Quality of Data Link Service.

For any parameter the DLS provider does not support or cannot determine, the corresponding parameter value will be set to DL_UNKNOWN. If the DLS provider does not support any QoS parameters, this length field will be set to zero.

dl_qos_offset

conveys the offset from the beginning of the M_PROTO message block where the quality of service parameters begin.

dl_growth

defines a growth field for future enhancements to this primitive. Its value will be set to zero.

State

The message is valid in state DL_OUTCON_PENDING.

New State

The resulting state is DL_DATAXFER.

4.2.6 Message DL_TOKEN_REQ (dl_token_req_t)

Requests that a connection response token be assigned to the stream and returned to the DLS user. This token can be supplied in the DL_CONNECT_RES primitive to indicate the stream on which a connection will be established. Message Format The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
     } dl_token_req_t;
     

Parameters

dl_primitive

conveys DL_TOKEN_REQ.

State

The message is valid in any state in which a local acknowledgment is not pending, as described in Allowable Sequence of DLPI Primitives.

New State

The resulting state is unchanged.

Response

The DLS provider responds to the information request with a DL_TOKEN_ACK.

4.2.7 Message DL_TOKEN_ACK (dl_token_ack_t)

This message is sent in response to DL_TOKEN_REQ; it conveys the connection response token assigned to the stream.

Message Format

The message consists of one M_PCPROTO message block, which contains the following structure.

     typedef struct {
             ulong dl_primitive;
             ulong dl_token;
     } dl_token_ack_t;
     

Parameters

dl_primitive

conveys DL_TOKEN_ACK.

dl_token

conveys the connection response token associated with the stream. This value must be a non-zero value. The DLS provider will generate a token value for each stream upon receipt of the first DL_TOKEN_REQ primitive issued on that stream. The same token value will be returned in response to all subsequent DL_TOKEN_REQ primitives issued on a stream.

State

The message is valid in any state in response to a DL_TOKEN_REQ.

New State

The resulting state is unchanged.

4.2.8 Message DL_DATA_REQ

Conveys a complete DLSDU from the DLS user to the DLS provider for transmission over the data link connection.

The DLS provider guarantees to deliver each DLSDU to the remote DLS user in the same order as received from the local DLS user. If the DLS provider detects unrecoverable data loss during data transfer, this may be indicated to the DLS user by a DL_RESET_IND, or by a DL_DISCONNECT_IND (if the connection is lost).

Message Format

The message consists of one or more M_DATA message blocks containing at least one byte of data.

To simplify support of a read(2)/write(2) interface to the data link layer, the DLS provider must recognize and process messages that consist of one or more M_DATA message blocks with no preceding M_PROTO message block. This message type may originate from the write(2) system call.³

State

The message is valid in state DL_DATAXFER. If it is received in state DL_IDLE or DL_PROV_RESET_PENDING, it should be discarded without generating an error.

New State

The resulting state is unchanged.

Response

If the request is valid, no response is generated.

If the request is erroneous, a STREAMS M_ERROR message should be issued to the DLS user specifying an errno value of EPROTO. This action should be interpreted as a fatal, unrecoverable, protocol error. A request is considered erroneous under the following conditions.

• The primitive was issued from an invalid state. If the request is issued in state DL_IDLE or DL_PROV_RESET_PENDING, however, it is silently discarded with no fatal error generated.
• The amount of data in the current DLSDU is not within the DLS provider's acceptable bounds as specified by dl_min_sdu and dl_max_sdu in the DL_INFO_ACK.

Note (Support of Direct User-Level Access)

A STREAMS module would implement "more" field processing itself to support direct user-level access. This module could collect messages and send them in one larger message to the DLS provider, or break large DLSDUs passed to the DLS user into smaller messages. The module would only be pushed if the DLS user was a user-level process.

4.2.9 Message DL_DATA_IND

Conveys a DLSDU from the DLS provider to the DLS user. The DLS provider guarantees to deliver each DLSDU to the local DLS user in the same order as received from the remote DLS user. If the DLS provider detects unrecoverable data loss during data transfer, this may be indicated to the DLS user by a DL_RESET_IND, or by a DL_DISCONNECT_IND (if the connection is lost).

Message Format

The message consists of one or more M_DATA blocks containing at least one byte of data.

State

The message is valid in state DL_DATAXFER.

New State

The resulting state is unchanged.

4.2.10 Message DL_DISCONNECT_REQ (dl_disconnect_req_t)

Requests the DLS provider to disconnect an active data link connection or one that was in the process of activation, either outgoing or incoming, as a result of an earlier DL_CONNECT_IND or DL_CONNECT_REQ. If an incoming DL_CONNECT_IND is being refused, the correlation number associated with that connect indication must be supplied. The message indicates the reason for the disconnect.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_reason;
             ulong dl_correlation;
     } dl_disconnect_req_t;
     

Parameters

dl_primitive

conveys DL_DISCONNECT_REQ.

dl_reason

conveys the reason for the disconnect.

Reasons for Disconnect

DL_DISC_NORMAL_CONDITION

normal release of a data link connection

DL_DISC_ABNORMAL_CONDITION

abnormal release of a data link connection

DL_CONREJ_PERMANENT_COND

a permanent condition caused the rejection of a connect request

DL_CONREJ_TRANSIENT_COND

a transient condition caused the rejection of a connect request

DL_DISC_UNSPECIFIED

reason unspecified

dl_correlation

if non-zero, conveys the correlation number that was contained in the DL_CONNECT_IND being rejected (see Multi-threaded Connection Establishment). This value permits the DLS provider to associate the primitive with the proper DL_CONNECT_IND when rejecting an incoming connection. If the disconnect request is releasing a connection that is already established, or is aborting a previously sent DL_CONNECT_REQ, the value of dl_correlation should be zero.

State

The message is valid in any of the states: DL_DATAXFER, DL_INCON_PENDING, DL_OUTCON_PENDING, DL_PROV_RESET_PENDING, DL_USER_RESET_PENDING.

New State

The resulting state is one of the disconnect pending states, as defined in Allowable Sequence of DLPI Primitives.

Response

If the disconnect is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_IDLE.

If the request fails, message DL_ERROR_ACK is returned, and the resulting state is unchanged.

Reasons for Failure

DL_BADCORR

The correlation number specified in this primitive did not correspond to a pending connect indication.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.2.11 Message DL_DISCONNECT_IND (dl_disc onnect_ind_t)

Informs the DLS user that the data link connection on this stream has been disconnected, or that a pending connection (either DL_CONNECT_REQ or DL_CONNECT_IND) has been aborted.

The primitive indicates the origin and the cause of the disconnect.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_originator;
             ulong dl_reason;
             ulong dl_correlation;
     } dl_disconnect_ind_t;
     

Parameters

dl_primitive

conveys DL_DISCONNECT_IND.

dl_originator

conveys whether the disconnect was DLS user or DLS provider originated (DL_USER or DL_PROVIDER, respectively).

dl_reason

conveys the reason for the disconnect.

Reasons for Disconnect

DL_DISC_PERMANENT_CONDITION

connection released due to permanent condition

DL_DISC_TRANSIENT_CONDITION

connection released due to transient condition

DL_CONREJ_DEST_UNKNOWN

unknown destination for connect request

DL_CONREJ_DEST_UNREACH_PERMANENT

could not reach destination for connect request - permanent condition

DL_CONREJ_DEST_UNREACH_TRANSIENT

could not reach destination for connect request - transient condition

DL_CONREJ_QOS_UNAVAIL_PERMANENT

requested quality of service parameters permanently unavailable during connection establishment

DL_CONREJ_QOS_UNAVAIL_TRANSIENT

requested quality of service parameters temporarily unavailable during connection establishment

DL_DISC_UNSPECIFIED

reason unspecified

dl_correlation

if non-zero, conveys the correlation number that was contained in the DL_CONNECT_IND that is being aborted (see Multi-threaded Connection Establishment). This value permits the DLS user to associate the message with the proper DL_CONNECT_IND. If the disconnect indication is indicating the release of a connection that is already established, or is indicating the rejection of a previously sent DL_CONNECT_REQ, the value of dl_correlation will be zero.

State

The message is valid in any of the states: DL_DATAXFER, DL_INCON_PENDING, DL_OUTCON_PENDING, DL_PROV_RESET_PENDING, DL_USER_RESET_PENDING.

New State

The resulting state is DL_IDLE.

4.2.12 Message DL_RESET_REQ (dl_reset_req_t)

Requests that the DLS provider initiate the resynchronization of a data link connection. This service is abortive, so no guarantee of delivery can be assumed about data that is in transit when the reset request is initiated.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
     } dl_reset_req_t;
     

Parameters

dl_primitive

conveys DL_RESET_REQ.

State

The message is valid in state DL_DATAXFER.

New State

The resulting state is DL_USER_RESET_PENDING.

Response

There is no immediate response to the reset request. However, as resynchronization completes, DL_RESET_CON is sent to the initiating DLS user, resulting in state DL_DATAXFER.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.2.13 Message DL_RESET_IND (dl_reset_ind_t)

Informs the DLS user that either the remote DLS user is resynchronizing the data link connection, or the DLS provider is reporting loss of data for which it can not recover. The indication conveys the reason for the reset.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_originator;
             ulong dl_reason;
     } dl_reset_ind_t;
     

Parameters

dl_primitive

conveys DL_RESET_IND.

dl_originator

conveys whether the reset was originated by the DLS user or DLS provider (DL_USER or DL_PROVIDER, respectively).

dl_reason

conveys the reason for the reset.

Reasons for Reset

DL_RESET_FLOW_CONTROL

indicates flow control congestion

DL_RESET_LINK_ERROR

indicates a data link error situation

DL_RESET_RESYNCH

indicates a request for resynchronization of a data link connection.

State

The message is valid in state DL_DATAXFER.

New State

The resulting state is DL_PROV_RESET_PENDING.

Response

The DLS user should issue a DL_RESET_RES primitive to continue the resynchronization procedure.

4.2.14 Message DL_RESET_RES (dl_reset_res_t)

Directs the DLS provider to complete resynchronizing the data link connection.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
     } dl_reset_res_t;
     

Parameters

dl_primitive

conveys DL_RESET_RES.

State

The primitive is valid in state DL_PROV_RESET_PENDING.

New State

The resulting state is DL_RESET_RES_PENDING.

Response

If the reset response is successful, DL_OK_ACK is sent to the DLS user resulting in state DL_DATAXFER.

If the reset response is erroneous, DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_SYSERR

A system error has occurred and the UNIX system error is indicated in the DL_ERROR_ACK.

4.2.15 Message DL_RESET_CON (dl_reset_con_t)

Informs the reset-initiating DLS user that the reset has completed.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
     } dl_reset_con_t;
     

Parameters

dl_primitive

conveys DL_RESET_CON.

State

The message is valid in state DL_USER_RESET_PENDING.

New State

The resulting state is DL_DATAXFER.

4.3 Connectionless-mode Service Primitives

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.

4.3.1 Message DL_UNITDATA_REQ (dl_unitdata_req_t)

Conveys one DLSDU from the DLS user to the DLS provider for transmission to a peer DLS user.

Because connectionless data transfer is an unacknowledged service, the DLS provider makes no guarantees of delivery of connectionless DLSDUs. It is the responsibility of the DLS user to do any necessary sequencing or retransmission of DLSDUs in the event of a presumed loss.

Message Format

The message consists of one M_PROTO message block containing the structure shown below, followed by one or more M_DATA blocks containing at least one byte of data. The amount of user data that may be transferred in a single DLSDU is limited. This limit is conveyed by the parameter dl_max_sdu in the DL_INFO_ACK primitive.

     typedef struct {
             ulong dl_primitive;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             dl_priority_t dl_priority;
     } dl_unitdata_req_t;
     

Parameters

dl_primitive

conveys DL_UNITDATA_REQ.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS user. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_priority

indicates the priority value within the supported range for this particular DLSDU.

State

The message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

Response

If the DLS provider accepts the data for transmission, there is no response. This does not, however, guarantee that the data will be delivered to the destination DLS user, since the connectionless data transfer is not a confirmed service.

If the request is erroneous, message DL_UDERROR_IND is returned, and the resulting state is unchanged.

If for some reason the request cannot be processed, the DLS provider may generate a DL_UDERROR_IND to report the problem. There is, however, no guarantee that such an error report will be generated for all undeliverable data units, since connectionless data transfer is not a confirmed service.

Reasons for Failure

DL_BADADDR

The destination DLSAP address was in an incorrect format or contained invalid information.

DL_BADDATA

The amount of data in the current DLSDU exceeded the DLS provider's DLSDU limit.

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_UNSUPPORTED

Requested priority not supplied by provider.

4.3.2 Message DL_UNITDATA_IND (dl_unitdata_ind_t)

Conveys one DLSDU from the DLS provider to the DLS user.

Message Format

The message consists of one M_PROTO message block containing the structure shown below, followed by one or more M_DATA blocks containing at least one byte of data. The amount of user data that may be transferred in a single DLSDU is limited. This limit is conveyed by the parameter dl_max_sdu in the DL_INFO_ACK primitive.

     typedef struct {
             ulong dl_primitive;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
             ulong dl_group_address;
     } dl_unitdata_ind_t;
     

Parameters

dl_primitive

conveys DL_UNITDATA_IND.

dl_dest_addr_length

conveys the length of the address of the DLSAP where this DL_UNITDATA_IND is intended to be delivered.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the DLSAP address of the sending DLS user.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

dl_group_address

is set by the DLS Provider upon receiving and passing upstream a data message when the destination address of the data message is a multicast or broadcast address.

State

The message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

4.3.3 Message DL_UDERROR_IND (dl_uderror_ind_t)

Informs the DLS user that a previously sent DL_UNITDATA_REQ produced an error or could not be delivered. The primitive indicates the destination DLSAP address associated with the failed request, and conveys an error value that specifies the reason for failure.

Message Format

The message consists of either one M_PROTO message block or one M_PCPROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_unix_errno;
             ulong dl_errno;
     } dl_uderror_ind_t;
     

Parameters

dl_primitive

conveys DL_UDERROR_IND.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS user.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_unix_errno

conveys the UNIX system error code associated with the failure. This value should be non-zero only when dl_errno is set to DL_SYSERR. It is used to report UNIX system failures that prevent the processing of a given request.

dl_errno

conveys the DLPI error code associated with the failure. See Reasons for Failure in the description of DL_UNITDATA_REQ for the error codes that apply to an erroneous DL_UNITDATA_REQ. In addition, the error value DL_UNDELIVERABLE may be returned if the request was valid but for some reason the DLS provider could not deliver the data unit (e.g. due to lack of sufficient local buffering to store the data unit). There is, however, no guarantee that such an error report will be generated for all undeliverable data units, since connectionless data transfer is not a confirmed service.

State

The message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

4.3.4 Message DL_UDQOS_REQ (dl_udqos_req_t)

Requests the DLS provider to apply the specified quality of service parameter values to subsequent data unit transmissions. These new values will remain in effect until another DL_UDQOS_REQ is issued.

Message Format

The message consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_qos_length;
             ulong dl_qos_offset;
     } dl_udqos_req_t;
     

Parameters

dl_primitive

conveys DL_UDQOS_REQ.

dl_qos_length

conveys the length, in bytes, of the requested quality of service parameter values. The values are conveyed in the appropriate structure defined in QOS Data Structures. The available range of QoS values that may be selected is specified by the dl_qos_range_length and dl_qos_range_offset parameters in the DL_INFO_ACK primitive.

For any parameter whose value the DLS user does not wish to select, the value DL_QOS_DONT_CARE may be set and the DLS provider will maintain the current value for that parameter. See Quality of Data Link Service, for a full description of the quality of service parameters.

dl_qos_offset

conveys the offset from the beginning of the M_PROTO message block where the quality of service parameters begin.

State

The message is valid in state DL_IDLE.

New State

The resulting state is DL_UDQOS_PENDING.

Response

If the quality of service request is successful, DL_OK_ACK is sent to the DLS user and the resulting state is DL_IDLE.

If the request fails, message DL_ERROR_ACK is returned and the resulting state is unchanged.

Reasons for Failure

DL_BADQOSPARAM

The quality of service parameters contained values outside the range of those supported by the DLS provider.

DL_BADQOSTYPE

The quality of service structure type was not supported by the DLS provider.

DL_OUTSTATE

The primitive was issued from an invalid state.

4.4 Primitives to handle XID and TEST operations

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.

4.4.1 Message DL_TEST_REQ (dl_test_req_t)

Conveys one TEST command DLSDU from the DLS User to the DLS Provider for transmission to a peer DLS Provider.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
     } dl_test_req_t;
     

Parameters

dl_primitive

conveys DL_TEST_REQ

dl_flag

indicates flag values for the request as follows:

DL_POLL_FINAL

indicates if the poll/final bit is set.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

Response

On an invalid TEST command request, a DL_ERROR_ACK is issued to the user. If the DLS Provider receives a response from the remote side, a DL_TEST_CON is issued to the DLS User. It is recommended that the DLS User use a timeout procedure to recover from a situation when there is no response from the peer DLS User.

Reasons for failure

DL_OUTSTATE

The primitive was issued from an invalid state

DL_BADADDR

The DLSAP address information was invalid or was in an incorrect format.

DL_SYSERR

A System error has occurred and the UNIX System error is indicated in the DL_ERROR_ACK.

DL_NOTSUPPORTED

Primitive is known but not supported by the DLS Provider

DL_TESTAUTO

Previous bind request specified automatic handling of TEST responses.

DL_UNSUPPORTED

Requested service not supplied by provider.

4.4.2 Message DL_TEST_IND (dl_test_ind_t)

Conveys the TEST response/indication DLSDU from the DLS Provider to the DLS User.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
     } dl_test_ind_t;
     

Parameters

dl_primitive

conveys DL_TEST_IND

dl_flag

indicates the flag values associated with the received TEST frame:

DL_POLL_FINAL

indicates if the poll/final bit is set.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the source DLSAP address. If the source user is implemented using DLPI, this address if the full DLSAP address returned on the DL_BIND_ACK.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

4.4.3 Message DL_TEST_RES (dl_test_res_t)

Conveys the TEST response DLSDU from the DLS User to the DLS Provider in response to a DL_TEST_IND.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
     } dl_test_res_t;
     

Parameters

dl_primitive

conveys DL_TEST_RES

dl_flag

indicates the flag values for the response as follows:

DL_POLL_FINAL

indicates if the poll/final bit is set.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

4.4.4 Message DL_TEST_CON (dl_test_con_t)

Conveys the TEST response DLSDU from the DLS Provider to the DLS User in response to a DL_TEST_REQ.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
     } dl_test_con_t;
     

Parameters

dl_primitive

conveys DL_TEST_RES

dl_flag

indicates the flag values for the request as follows:

DL_POLL_FINAL

indicates if the poll/final bit is set.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the source DLSAP address. If the source user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

4.4.5 Message DL_XID_REQ (dl_xid_req_t)

Conveys one XID DLSDU from the DLS User to the DLS Provider for transmission to a peer DLS User.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
     } dl_xid_req_t;
     

Parameters

dl_primitive conveys

DL_XID_REQ

dl_flag

indicates the flag values for the response as follows:

DL_POLL_FINAL

indicates status of the poll/final bit in the xid frame.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

State

The message is valid in state DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

Response

On an invalid XID request, a DL_ERROR_ACK is issued to the user. If the remote side responds to the XID request, a DL_XID_CON will be sent to the User. It is recommended that the DLS User use a timeout procedure on an XID_REQ. The timeout may be used if the remote side does not respond to the XID request.

Reasons for failure

DL_BADDATA

The amount of data in the current DLSDU exceeded the DLS Provider's DLSDU limit.

DL_XIDAUTO

Previous bind request specified Provider would handle XID.

DL_OUTSTATE

The primitive was issued from an invalid state

DL_BADADDR

The DLSAP address information was invalid or was in an incorrect format.

DL_SYSERR

A System error has occurred and the UNIX System error is indicated in the DL_ERROR_ACK.

DL_NOTSUPPORTED

Primitive is known but not supported by the DLS Provider

4.4.6 Message DL_XID_IND (dl_xid_ind_t)

Conveys an XID DLSDU from the DLS Provider to the DLS User.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
     } dl_xid_ind_t;
     

Parameters

dl_primitive

conveys DL_XID_IND

dl_flag

conveys the flag values associated with the received XID frame.

DL_POLL_FINAL

indicates if the received xid frame had the poll/final bit set.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the source DLSAP address. If the source user is implemented using DLPI, this address if the full DLSAP address returned on the DL_BIND_ACK.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

State

The message is valid in state DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

Response

The DLS User must respond with a DL_XID_RES.

4.4.7 Message DL_XID_RES (dl_xid_res_t)

Conveys an XID DLSDU from the DLS User to the DLS Provider in response to a DL_XID_IND.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
     } dl_xid_res_t;
     

Parameters

dl_primitive conveys

DL_XID_RES

dl_flag

conveys the flag values associated with the received XID frame.

DL_POLL_FINAL

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

4.4.8 Message DL_XID_CON (dl_xid_con_t)

Conveys an XID DLSDU from the DLS Provider to the DLS User in response to a DL_XID_REQ.

Message Format

The message consists of one M_PROTO message block, followed by zero or more M_DATA blocks containing zero or more bytes of data. The message structure is as follows:

     typedef struct {
             ulong dl_primitive;
             ulong dl_flag;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
     } dl_xid_con_t;
     

Parameters

dl_primitive

conveys DL_XID_CON

dl_flag

conveys the flag values associated with the received XID frame.

DL_POLL_FINAL

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the source DLSAP address. If the source user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

State

The message is valid in states DL_IDLE and DL_DATAXFER.

New State

The resulting state is unchanged.

4.5 Acknowledged Connectionless-mode Service Primitives

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.

4.5.1 Message DL_DATA_ACK_REQ (dl_data_ack_req_t)

This request is passed to the Data Link Provider to request that a DLSDU be sent to a peer DLS User using acknowledged connectionless mode data unit transmission procedures.

Message Format

Consists of one M_PROTO message block containing the structure shown below, followed by one or more M_DATA blocks containing one or more bytes of data. The amount of user data that may be transferred in a single DLSDU is limited. This limit is conveyed by the parameter dl_max_sdu in the DL_INFO_ACK primitive.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correlation;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
             ulong dl_priority;
             ulong dl_service_class;
     } dl_data_ack_req_t;
     

Parameters

dl_primitive

conveys DL_DATA_ACK_REQ

dl_correlation

Conveys a unique identifier which will be returned in the DL_DATA_ACK_STATUS_IND primitive to allow the DLS User to correlate the status to the appropriate DL_DATA_ACK_REQ primitive.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the DLSAP address of the source DLS User.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

dl_priority

indicates the priority value within the supported range for this particular DLSDU.

dl_service_class

Specifies whether or not an acknowledge capability in the medium access control sublayer is to be used for the data unit transmission.

DL_RQST_RSP

Request acknowledgment service from the medium access control sublayer if supported

DL_RQST_NORSP

No acknowledgment service requested from the medium access control sublayer.

State

This message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

Response

If the request is erroneous, message DL_ERROR_ACK is returned, and the resulting state is unchanged.

If the DLS Provider accepts the data for transmission, a DL_DATA_ACK_STATUS_IND is returned.

This indication will indicate the success or failure of the data transmission. Although the exchange service is connectionless, in-sequence delivery is guaranteed for data sent by the initiating station.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_BADADDR

The destination DLSAP address was in an incorrect format or contained invalid information.

DL_NOTSUPPORTED

Primitive is valid, but not supported.

DL_BADDATA

The amount of data in the current DLSDU exceeded the DLS provider's DLSDU limit.

DL_UNSUPPORTED

Requested service or priority not supported by Provider (Request with response at the Medium Access Control sublayer).

4.5.2 Message DL_DATA_ACK_IND (dl_data_ack_ind_t)

Conveys one DLSDU from the DLS Provider to the DLS User. This primitive indicates the arrival of anon-null, non-duplicate DLSDU from a peer Data Link User entity.

Message Format

Consists of one M_PROTO message block containing the structure shown below, followed by one or more M_DATA blocks containing one or more bytes of data. The amount of user data that may be transferred in a single DLSDU is limited. This limit is conveyed by the parameter dl_max_sdu in the DL_INFO_ACK primitive.

     typedef struct {
             ulong dl_primitive;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
             ulong dl_priority;
             ulong dl_service_class;
     } dl_data_ack_ind_t;
     

Parameters

dl_primitive

conveys DL_DATA_ACK_IND

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the DLSAP address of the source DLS User.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins. address returned on the DL_BIND_ACK.

dl_priority

priority provided for the data unit transmission.

dl_service_class

Specifies whether or not an acknowledge capability in the medium access control sublayer is to be used for the data unit transmission.

DL_RQST_RSP

Use acknowledgment service in the medium access control sublayer.

DL_RQST_NORSP No

acknowledgment service to be used in the medium access control sublayer.

State

This message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

4.5.3 Message DL_DATA_ACK_STATUS_IND (dl_data_ack_status_ind_t)

Conveys the results of the previous associated DL_DATA_ACK_REQ from the DLS Provider to the DLS User.

Message Format

Consists of one M_PROTO message block containing the structure shown below.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correlation;
             ulong dl_status;
     } dl_data_ack_status_ind_t;
     

Parameters

dl_primitive

conveys DL_DATA_ACK_STATUS_IND

dl_correlation

conveys the unique identifier passed with the DL_DATA_ACK_REQ primitive, to allow the DLS User correlate the status to the appropriate DL_DATA_ACK_REQ.

dl_status

indicates the success or failure of the previous associated acknowledged connectionless-mode data unit transmission request.

DL_CMD_OK

Command accepted.

DL_CMD_RS

Unimplemented or inactivated service.

DL_CMD_UE

LLC User Interface error

DL_CMD_PE

Protocol error

DL_CMD_IP

Permanent implementation dependent error

DL_CMD_UN

Resources temporarily unavailable.

DL_CMD_IT

Temporary implementation dependent error.

State

This message is valid in state DL_IDLE.

New State

The resulting state is unchanged.

4.5.4 Message DL_REPLY_REQ (dl_reply_req_t)

This request primitive is passed to the DLS Provider by the DLS User to request that a DLSDU be returned from a peer DLS Provider or that DLSDUs be exchanged between stations using acknowledged connectionless mode data unit exchange procedures.

Message Format

Consists of one M_PROTO message block containing the structure shown below, followed by one or more M_DATA blocks with one or more bytes of data.

     typedef struct {
             ulong dl_primitive;
             ulong dl_correlation;
             ulong dl_dest_addr_length;
             ulong dl_dest_addr_offset;
             ulong dl_src_addr_length;
             ulong dl_src_addr_offset;
             ulong dl_priority;
             ulong dl_service_class;
     } dl_reply_req_t;
     

Parameters

dl_primitive

conveys DL_REPLY_REQ

dl_correlation

Conveys a unique identifier which will be returned in the DL_REPLY_STATUS_IND primitive to allow the DLS User to correlate the status to the appropriate DL_REPLY_REQ primitive.

dl_dest_addr_length

conveys the length of the DLSAP address of the destination DLS User. If the destination user is implemented using DLPI, this address is the full DLSAP address returned on the DL_BIND_ACK.

dl_dest_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the destination DLSAP address begins.

dl_src_addr_length

conveys the length of the DLSAP address of the source DLS User.

dl_src_addr_offset

conveys the offset from the beginning of the M_PROTO message block where the source DLSAP address begins.

dl_priority

priority provided for the data unit transmission.

dl_service_class

Specifies whether or not an acknowledge capability in the medium access control sublayer is to be used for the data unit transmission.

State

This primitive is valid in state DL_IDLE.

New State

The resulting state is unchanged.

Response

If the request is erroneous, message DL_ERROR_ACK is returned, and the resulting state is unchanged. If the message is valid, a DL_REPLY_STATUS_IND is returned. This will indicate the success or failure of the previous associated acknowledged connectionless-mode data unit exchange.

Reasons for Failure

DL_OUTSTATE

The primitive was issued from an invalid state.

DL_BADADDR

The destination DLSAP address was in an incorrect format or contained invalid information.

DL_NOTSUPPORTED

Primitive is valid, but not supported.

DL_BADDATA

The amount of data in the current DLSDU exceeded the DLS provider's DLSDU limit.

DL_UNSUPPO