Network Provider Interface (NPI)

NPI

Section: Network Provider Interface (NPI) (7)
Updated: 2008-10-31
Index Return to Main Contents

NAME

NPI - Network Provider Interface

SYNOPSIS

#include <sys/npi.h>

DESCRIPTION

This document specifies a STREAMS(4)-based kernel-level instantiation of the ISO/CCITT network service definition. The Network Provider Interface (NPI) enables the user of a network layer service to access and use any of a variety of conforming network layer service providers without specific knowledge of the provider's protocol. The service interface is designed to support any connection-mode network protocol and connectionless network protocol. This interface only specifies access to network layer service providers, and does not address issues concerning network layer management,protocol performance, and performance analysis tools.

The specification assumes that the reader is familiar with the OSI reference model terminology, ISO/CCITT Network Layer Service, and STREAMS(4).

Role

This document specifies an interface that supports the service provided by the Network Services Definition for Open Systems Interconnection for CCITT Applications as described in CCITT Recommendation X.213 and ISO 8348 (for CONS) and ISO8348/Addendum 1 (for CLNS). These specifications are targeted for use by developers and testers of protocol modules that require network layer service.

Definitions, Acronyms, and Abbreviations

Calling NS user: An NS user that initiates a Network Connection (NC).
Called NS User: An NS user with whom a calling NS user wishes to establish a network connection (NC).
CLNP: Connection-less Network Protocol
CLNS: Connection-less Network Service.
CONP: Connection Oriented Network Protocol
CONS: Connection Oriented Network Service.
DLSAP: Data Link Service Access Point
ISO: International Organization for Standardization
NC: Network Connection
Network User: Kernel level protocol or user level application that is accessing the services of the network layer.
Network Provider: Network layer entity/entities that provide/s the services of the network interface.
NPI: Network Provider Interface
NS: Network Service.
NIDU: Network Interface Data Unit
NSAP: Network Service Access Point
NSDU: Network Service Data Unit
OSI: Open Systems Interconnection
QOS: Quality of Service.
STREAMS(4): A communication services development facility first available with UNIX System V Release 3

The Network Layer

The Network Layer provides the means to manage the operation of the network. It is responsible for the routing and management of data exchange between network-user entities.

Model of the NPI

The NPI defines the services provided by the network layer to the network-user at the boundary between the network layer and the network layer user entity. The interface consists of a set of primitives defined as STREAMS(4) messages that provide access to the network layer services, and are transferred between the NS user entity and the NS provider. These primitives are of two types; ones that originate from the NS user, and others that originate from the NS provider. The primitives that originate from the NS user make requests to the NS provider, or respond to an event of the NS provider. The primitives that originate from the NS provider are either confirmations of a request or are indications to the NS user that the event has occurred.

The NPI allows the NS provider to be configured with any network layer user (such as the OSI Transport Layer) that also conforms to the NPI. A network layer user can also be a user program that conforms to the NPI and accesses the NS provider via putmsg(2) and getmsg(2) system calls.

NPI Services

The features of the NPI are defined in terms of the services provided by the NS provider,and the individual primitives that may flow between the NS user and the NS provider.

The services supported by the NPI are based on two distinct modes of communication,connection (CONS) and connectionless (CLNS). In addition, the NPI supports services for local management.

CONS

The main features of the connection mode communication are:

a.: It is virtual circuit oriented;
b.: It provides transfer of data via a pre-established path;
c.: It provides reliable data transfer.

There are three phases to each instance of communication: Connection Establishment;Data Transfer; and Connection Termination. Units of data arrive at their destination in the same order as they departed their source and the data is protected against duplication or loss of data units within some specified quality of service.

CLNS

The main features of the connectionless mode communication are:

a.: It is datagram oriented;
b.: It provides transfer of data in self contained units;
c.: There is no logical relationship between these units of data;
d.: It is unreliable.

Connectionless mode communication has no separate phases. Each unit of data is transmitted from source to destination independently, appropriate addressing information is included with each unit of data. As the units of data are transmitted independently from source to destination, there are, in general, no guarantees of proper sequence and completeness of the data stream.

Local Management

The NPI specifications also define a set of local management functions that apply to both CONS and CLNS modes of communication. These services have local significance only.

Tables 1 and 2 summarizes the NPI service primitives by their state and service.

TABLE 1. Service Primitives for Connection Mode Data Transfer

STATE	SERVICE	PRIMITIVES

Local Management	Information Reporting	N_INFO_REQ(7), N_INFO_ACK(7), N_ERROR_ACK(7)

	Bind	N_BIND_REQ(7), N_BIND_ACK(7), N_UNBIND_REQ(7), N_OK_ACK(7), N_ERROR_ACK(7)

	Options Management	N_OPTMGMT_REQ(7), N_OK_ACK(7), N_ERROR_ACK(7)

Connection Establishment	Connection Establishment	N_CONN_REQ(7), N_CONN_IND(7), N_CONN_RES(7), N_CONN_CON(7), N_TOKEN_REQ(7), N_TOKEN_ACK(7), N_OK_ACK(7), N_ERROR_ACK(7)

Connection Mode Data Transfer	Data Transfer	N_DATA_REQ(7), N_DATA_IND(7), N_EXDATA_REQ(7), N_EXDATA_IND(7), N_DATACK_REQ(7), N_DATACK_IND(7)

	Reset	N_RESET_REQ(7), N_RESET_IND(7), N_RESET_RES(7), N_RESET_CON(7)

Connection Release	Connection Release	N_DISCON_REQ(7), N_DISCON_IND(7), N_OK_ACK(7), N_ERROR_ACK(7)

TABLE 2. Service Primitives for Connectionless Mode Data Transfer

STATE	SERVICE	PRIMITIVES

Local Management	Information Reporting	N_INFO_REQ(7), N_INFO_ACK(7), N_ERROR_ACK(7)

	Bind	N_BIND_REQ(7), N_BIND_ACK(7), N_UNBIND_REQ(7), N_OK_ACK(7), N_ERROR_ACK(7)

	Options Management	N_OPTMGMT_REQ(7), N_OK_ACK(7), N_ERROR_ACK(7)

Connectionless Mode Data Transfer	Data Transfer	N_UNITDATA_REQ(7), N_UNITDATA_IND(7), N_UDERROR_IND(7)

NPI Services Definition

This section describes the services of the NPI primitives. Time-sequence diagrams that illustrate the sequence of primitives are included. (Conventions for the time-sequence diagrams are defined in CCITT X.210 [8].) The format of the primitives will be defined later in this document.

Local Management Services Definition

The services defined in this section are outside the scope of the international standards. These services apply to both connection-mode as well as the connection-less modes of communication. They are invoked for the initialization/de-initialization of a stream connected to the NS provider. They are also used to manage options supported by the NS provider and to report information on the supported parameter values.

Network Information Reporting Service. This service provides information on the options supported by the NS provider.

---: N_INFO_REQ(7): This primitive requests that the NS provider return the values of all the supported protocol parameters. This request may be invoked during any phase.
---: N_INFO_ACK(7): This primitive is in response to the N_INFO_REQ(7) primitive and returns the values of the supported protocol parameters to the NS user.

NS User Bind Service. This service allows a network address to be associated with a stream. It allows the NS user to negotiate the number of connect indications that can remain unacknowledged for that NS user (a connect indication is considered unacknowledged while it is awaiting a corresponding connect response or disconnect request from the NS user). This service also defines a mechanism that allows a stream (bound to a network address of the NS user) to be reserved to handle incoming calls only. This stream is referred to as the listener stream.

---: N_BIND_REQ(7): This primitive requests that the NS user be bound to a particular network address, and negotiate the number of allowable outstanding connect indications for that address.
---: N_BIND_ACK(7): This primitive is in response to the N_BIND_REQ(7) primitive and indicates to the user that the specified NS user has been bound to a network address.

NS User Unbind Service. This service allows the NS user to be unbound from a network address.

---: N_UNBIND_REQ(7): This primitive requests that the NS user be unbound from * the network address that it had previously been bound to.

Receipt Acknowledgment Service.

---: N_OK_ACK(7): This primitive indicates to the NS user that the previous NS user originated primitive was received successfully by the NS provider.

Options Management Service. This service allows the NS user to manage the QOS parameter values associated with the NS provider.

---: N_OPTMGMT_REQ(7): This primitive allows the NS user to select default values for QOS parameters within the range supported by the NS provider, and to indicate the default selection of receipt confirmation.

Error Acknowledgment Service.

---: N_ERROR_ACK(7): This primitive indicates to the NS user that a non-fatal error has occurred in the last NS user originated request or response primitive on the stream.

Connection-Mode Network Services Definition

This section describes the required network service primitives that define the CONS interface.

The queue model for CONS is discussed in more detail in CCITT X.213 section 9.2. The queue model represents the operation of a network connection in the abstract by a pair of queues linking the two network addresses. There is one queue for each direction of information flow.

Each queue represents a flow control function in one direction of transfer. The ability of a user to add objects to a queue will be determined by the behavior of the user removing objects from that queue, and the state of the queue. The pair of queues is considered to be available for each potential NC. Objects that are entered or removed from the queue are either as a result of interactions at the two network addresses, or as the result of NS provider initiatives.

---: A queue is empty until a connect object has been entered and can be returned to this state, with loss of its contents, by the NS provider.
---: Objects may be entered into a queue as a result of the actions of the source NS user,subject to control by the NS provider;
---: Objects may also be entered into a queue by the NS provider.
---: Objects are removed from the queue under the control of the receiving NS user.
---: Objects are normally removed under the control of the NS user in the same order as they were entered except:
---: if the object is of a type defined to be able to advance ahead of the preceding object (however, no object is defined to be able to advance ahead of another object of the same type), or
---: if the following object is defined to be destructive with respect to the preceding object on the queue.

If necessary, the last object on the queue will be deleted to allow a destructive object to be entered - they will therefore always be added to the queue. For example, "disconnect" objects are defined to be destructive with respect to all other objects. "Reset" objects are defined to be destructive with respect to all other objects except "connect", "disconnect", and other "reset" objects. Table 3 shows the ordering relationships among the queue model objects.

Connection Establishment Phase A pair of queues is associated with an NC between two network addresses when the NS provider receives an N_CONN_REQ(7) primitive at one of the network addresses resulting in a connect object being entered into the queue. The queues will remain associated with the NC until a N_DISCON_REQ(7) primitive (resulting in a disconnect object) is either entered or removed from a queue. Similarly, in the queue from the called NS user, objects can be entered into the queue only after the connect object associated with the N_CONN_RES(7) has been entered into the queue. Alternatively, the called NS user can enter a disconnect object into the queue instead of the connect object to terminate the NC. The NC establishment procedure will fail if the NS provider is unable to establish an NC,or if the destination NS user is unable to accept the N_CONN_IND(7) (see NC Release primitive definition).

User Primitives for Successful Network Connection Establishment

---: N_CONN_REQ(7): This primitive requests that the NS provider make a connection to the specified destination.
---: N_CONN_RES(7): This primitive requests that the NS provider accept a previous connection indication.

Provider Primitives for Successful Network Connection Establishment

---: N_CONN_IND(7): This primitive indicates to the NS user that a connect request has been made by a user at the specified source address.
---: N_CONN_CON(7): This primitive indicates to the NS user that a connect request has been confirmed on the specified responding address.

Data Transfer Phase Flow control on the NC is done by management of the queue capacity, and by allowing objects of certain types to be inserted to the queues, as shown in Table 4.

User Primitives for Data Transfer

---: N_DATA_REQ(7): This primitive requests that the NS provider transfer the specified data.
---: N_DATACK_REQ(7): This primitive requests that the NS provider acknowledge the data that had previously been received with receipt confirmation requested.
---: N_EXDATA_REQ(7): This primitive requests that the NS provider transfer the specified expedited network service data unit.

Provider Primitives for Data Transfer

---: N_DATA_IND(7): This primitive indicates to the NS user that this message contains data.
---: N_DATACK_IND(7): This primitive indicates to the NS user that the remote NS user has acknowledged the data that had previously been sent with receipt confirmation requested.
---: N_EXDATA_IND(7): This primitive indicates to the NS user that this message unit contains expedited data.

The sequence of primitives may remain incomplete if a N_RESET or N_DISCON primitive occurs.

A NS user must not issue an N_DATACK_REQ(7) primitive if no N_DATA_IND(7) with confirmation request set has been received, or if all such N_DATA_IND(7) have been previously acknowledged. Following a reset procedure (N_RESET_REQ(7) or N_RESET_IND(7)), a NS user may not issue aN_DATACK_REQ to acknowledge an outstanding N_DATA_IND(7) received before the reset procedure was signaled. (Note -- The withholding of confirmation of receipt by a NS user can have an effect on the attainable throughput on the NC.)

Reset Operation Primitives The reset service is used by the NS user to resynchronize the use of the NC, or by the NS provider to report detected loss of unrecoverable data.

The reset procedure involves the following interactions:

A.: a N_RESET_REQ(7) from the NS user, followed by a N_RESET_CON(7) from the NS provider; or
B.: a N_RESET_IND(7) from the NS provider, followed by a N_RESET_RES(7) from the NS user.

The complete sequence of primitives depends upon the origin/s of the reset action. The reset service may be:

1.: invoked by one NS user, leading to interaction (A) with that NS user and interaction (B) with the peer NS user;
2.: invoked by both NS users, leading to interaction (A) with both NS users;
3.: invoked by the NS provider, leading to interaction (B) with both NS users;
4.: invoked by one NS user and the NS provider, leading to interaction (A) with the originating NS user and (B) with the peer NS user.

The N_RESET_REQ(7) acts as a synchronization mark in the flow of N_DATA, N_EXDATA, and N_DATACK primitives transmitted by the issuing NS user; the N_RESET_IND(7) acts as a synchronization mark in the flow of N_DATA, N_EXDATA, and N_DATACK primitives received by the receiving NS user. Similarly, N_RESET_RES(7) acts as a synchronization mark in the flow of N_DATA, N_EXDATA, and N_DATACK primitives transmitted by the responding NS user, while the N_RESET_CON(7) acts as a synchronization mark in the flow of N_DATA, N_EXDATA, and N_DATACK primitives received by the NS user that originally issued the reset. The resynchronizing properties of the reset service are the following:

i.: All N_DATA, N_EXDATA, and N_DATACK primitives issued before issuing the N_RESET_REQ(7)/N_RESET_RES(7) that have not been delivered to the other NS user before the N_RESET_IND(7)/N_RESET_CON(7) are issued by the NS provider,should be discarded by the NS provider.
ii.: Any N_DATA, N_EXDATA, and N_DATACK primitives issued after the synchronization mark will not be delivered to the other NS user before the synchronization mark is received.

User Primitives for Reset Operations

---: N_RESET_REQ(7): This primitive requests that the NS provider reset the network connection.
---: N_RESET_RES(7): This primitive indicates to the NS provider that the NS user has accepted a reset indication.

Provider Primitives for Reset Operations

---: N_RESET_IND(7): This primitive indicates to the NS user that the network connection has been reset.
---: N_RESET_CON(7): This primitive indicates to the NS user that the reset request has been confirmed.

The sequence of primitives may remain incomplete if a N_DISCON primitive occurs.

Connection Termination Phase The NC release procedure is initialized by the insertion of a disconnect object(associated with a N_DISCON_REQ)(7) into the queue. As shown in Table 3, the disconnect procedure is destructive with respect to other objects in the queue, and eventually results in the emptying of queues and termination of the NC connection.

The sequence of primitives depends on the origin of the release action. The sequence may be:

1.: invoked by one NS user, with a request from that NS user leading to an indication to the other;
2.: invoked by both NS users, with a request from each of the NS users;
3.: invoked by the NS provider, with an indication to each of the NS users;
4.: invoked independently by one NS user and the NS provider, with a request from the originating NS user and an indication to the other.

User Primitives for Connection Termination

---: N_DISCON_REQ(7): This primitive requests that the NS provider deny an outstanding request for a connection or disconnect an existing connection.

Provider Primitives for Connection Termination

---: N_DISCON_IND(7): This primitive indicates to the NS user that either a request for connection has been denied or an existing connection has been terminated.

A NS user may reject an NC establishment attempt by issuing a N_DISCON_REQ(7). The originator parameter in the N_DISCON primitives will indicate NS user invoked release.

If the NS provider is unable to establish an NC, it indicates this to the requester by an N_DISCON_IND(7). The originator in this primitive indicates an NS provider invoked release.

Connectionless Network Services Definition

The CLNS allows for the transfer of the NS user data in one or both directions simultaneously without establishing a network connection. A set of primitives are defined that carry user data and control information between the NS user and NS provider entities. The primitives are modeled as requests initiated by the NS user and indications initiated by the NS provider. Indications may be initiated by the NS provider independently from requests by the NS user.

The connectionless network service consists of one phase.

User Request Primitives

---: N_UNITDATA_REQ(7): This primitive requests that the NS provider send the data unit to the specified destination.

Provider Response Primitives

---: N_UNITDATA_IND(7): This primitive indicates to the NS user that a data unit has been received from the specified source address.
---: N_UDERROR_IND(7): This primitive indicates to the NS user that the data unit with the specified destination address and QOS parameters produced an error. This primitive is specific to CLNS.

Local Management

The following management primitives are common to all modes of network service provider.

---: N_INFO_ACK(7): Requests information concerning the communications device, provider limits, styles and features.
---: N_INFO_REQ(7): Provides information concerning the communications device, provider limits, styles and features.
---: N_OPTMGMT_REQ(7): Requests the management of network provider options.
---: N_BIND_REQ(7): Requests the binding of the stream to a network endpoint address.
---: N_BIND_ACK(7): Provides acknowledgment of the bound network endpoint address.
---: N_UNBIND_REQ(7): Requests the stream be unbound from the bound network endpoint address.
---: N_OK_ACK(7): Provides positive acknowledgment of request primitives that require acknowledgment.
---: N_ERROR_ACK(7): Provides negative acknowledgment of request primitives that require acknowledgment.

Connectionless Data Transfer

The following primitives provide for the transfer of data with a connectionless network service provider.

---: N_UNITDATA_REQ(7): Requests the transmission of connectionless data.
---: N_UNITDATA_IND(7): Provides indication of the reception of connectionless data.
---: N_UDERROR_IND(7): Provides indication of errors encountered in the transmission of connectionless data.

Connection Establishment

The following primitives establish a network connection with a connection oriented network service provider.

---: N_CONN_REQ(7): Requests connection to a peer network endpoint.
---: N_CONN_CON(7): Provides confirmation of a connection request.
---: N_CONN_IND(7): Provides indication of a connection request from a peer endpoint.
---: N_CONN_RES(7): Responds to an outstanding connection indication.

Connection Data Transfer

The following primitives provide for the transfer of data with a connection oriented network service provider.

Data Transfer Service. The following primitives provide for the transfer of data on the network connection.

---: N_DATA_REQ(7): Requests the transmission of data on a network connection.
---: N_DATA_IND(7): Provides indication of the reception of data on a network connection.
---: N_EXDATA_REQ(7): Requests the transmission of expedited data on a network connection.
---: N_EXDATA_IND(7): Provides indication of the reception of expedited data on a network connection.

Data Acknowledgment Service. The following primitives provider for the acknowledgment of data transfer.

---: N_DATACK_REQ(7): Requests acknowledgment of the last received data on the network connection.
---: N_DATACK_IND(7): Provides indication of acknwowldgment of the last transmitted data on the network connection.

Connection Reset

The following primitives provide for the reset of the network connection.

---: N_RESET_REQ(7): Requests that a network connection be reset.
---: N_RESET_CON(7): Provides confirmation of the reset of the network connection.
---: N_RESET_IND(7): Provides indication of the reset of a network connection.
---: N_RESET_RES(7): Responds to an outstanding indication of network connection reset.

Connection Release

The following primitives provide for the release of a network connection with a connection oriented network service provider.

---: N_DISCON_REQ(7): Requests that a network connection be released.
---: N_DISCON_IND(7): Provides indication that a network connection has been released.

HISTORY

The Network Provider Interface first appeared in SVR 4[1].

CONFORMANCE

This interface conforms to NPI Revision 2[2].

REFERENCES

[1]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: NPI, Open Group CAE Specification: Network Provider Interface (NPI) Specification, Revision 2.0.0, Draft 2, August 17, 1992, (Parsippany, New Jersey), UNIXInternational,Inc., UNIX International Press. <http://www.openss7.org/docs/npi.pdf>
[3]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[4]: Advanced Programming in the UNIX®Environment, 15th edition, December 1997, (Reading, Massachusetts), W. R. Stevens, Addison Wesley. [ISBN 0-201-56317-7]