dlpi.7.man

This a separate release of the OpenSS7 X/Open XTI/TLI library, TLI modules (timod, tirdwr) and the I

'\" rtp
.\" -*- nroff -*- vim: ft=nroff noautoindent nocindent nosmartindent
.\"
.\" @(#) dlpi.7.man,v 0.9.2.3 2004/05/16 02:35:49 brian Exp
.\"
.\" =========================================================================
.\"
.\" Copyright (C) 2001-2004  OpenSS7 Corporation <www.openss7.com>
.\"
.\" All Rights Reserved.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" -------------------------------------------------------------------------
.\"
.\" U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software
.\" on behalf of the U.S. Government ("Government"), the following
.\" provisions apply to you.  If the Software is supplied by the Department
.\" of Defense ("DoD"), it is classified as "Commercial Computer Software"
.\" under paragraph 252.227-7014 of the DoD Supplement to the Federal
.\" Acquisition Regulations ("DFARS") (or any successor regulations) and the
.\" Government is acquiring only the license rights granted herein (the
.\" license rights customarily provided to non-Government users).  If the
.\" Software is supplied to any unit or agency of the Government other than
.\" DoD, it is classified as "Restricted Computer Software" and the
.\" Government's rights in the Software are defined in paragraph 52.227-19
.\" of the Federal Acquisition Regulations ("FAR") (or any success
.\" regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
.\" NASA Supplement to the FAR (or any successor regulations).
.\"
.\" =========================================================================
.\" 
.\" Commercial licensing and support of this software is available from
.\" OpenSS7 Corporation at a fee.  See http://www.openss7.com/
.\" 
.\" =========================================================================
.\"
.\" Last Modified 2004/05/16 02:35:49 by brian
.\"
.\" =========================================================================
.so strxnet.macros
.R1
bracket-label "\fR[\fB" "\fR]" "\fR, \fB"
no-default-database
database strxnet.refs
accumulate
move-punctuation
abbreviate A
join-authors ", " ", " " and "
et-al " et al" 2 3
abbreviate-label-ranges ".."
sort-adjacent-labels
.R2
.\"
.\"
.TH DLPI 7 "2004/05/16 02:35:49" "strxnet-0_9_2-4" "Data Link Provider Interface (DLPI)"
.\"
.\"
.SH NAME
.B DLPI
\- Data Link Provider Interface
.\"
.\"
.SH SYNOPSIS
.B #include <sys/dlpi.h>
.\"
.\"
.SH DESCRIPTION
.\"
.\"
.\"
.\"
The data link layer (layer 2 in the OSI Reference Model) is responsible for
the transmission and error-free delivery of bits of information over a physical
communications medium.
.\"
.\"
.PP
The model of the data link layer is presented here to describe concepts that
are used throughout the specification of
.BR 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.
.\"
.\"
.PP
Each layer of the OSI Reference Model has two standards:
.\"
.\"
.IP \(bu 3
one that defines the services provided by the layer, and
.\"
.\"
.IP \(bu 3
one that defines the protocol through which layer services are provided.
.\"
.\"
.PP
.B DLPI
is an implementation of the first type of standard.  It specifies an
interface to the services of the data link layer.
.\"
.\"
.PP
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.
.\"
.\"
.PP
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
.IR STREAMS (4)
development environment, constitute a major portion of this effort.  The
service primitives that make up these interfaces are defined as
.IR STREAMS (4)
messages that are transferred between the user and provider of the service.
.B DLPI
is one such kernel-level interface, and is targeted for
.IR STREAMS (4)
protocol modules that either use or provide data link services.  In addition,
user programs that wish to access a
.IR STREAMS (4)-based
data link provider directly may do so using the
.BR putmsg(2) " and " getmsg (2)
system calls.
The DLS provider is configured as a
.IR STREAMS (4)
driver,and the DLS user accesses the provider using
.BR 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.
.B DLPI
is intended to free data link users from specific knowledge of the
characteristics of the data link provider.  Specifically, the definition of
.B 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
.B 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.
.\"
.\"
.PP
.\"
.\"
.SS "MODES OF COMMUNICATION"
The data link provider interface supports three modes of communication:
connection, connectionless and acknowledged connectionless.
.\"
.\"
.PP
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.
.\"
.\"
.PP
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.
.\"
.\"
.PP
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.
.\"
.\"
.PP
.B CONNECTION-MODE SERVICE
.\"
.\"
.PP
The connection-mode service is characterized by four phases of communication:
local management,connection establishment, data transfer, and connection
release.
.\"
.\"
.TP
.B Local Management
This phase enables a DLS user to initialize a stream for use in communication
and establish an identity with the DLS provider.
.\"
.\"
.TP
.B 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).
.sp
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.
.\"
.\"
.TP
.B 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.
.\"
.\"
.TP
.B 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.
.\"
.\"
.PP
.B CONNECTIONLESS-MODE SERVICE
.\"
.\"
.PP
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).
.\"
.\"
.PP
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.
.\"
.\"
.PP
.B ACKNOWLEDGED CONNECTIONLESS-MODE SERVICE
.\"
.\"
.PP
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.
.\"
.\"
.SS "DLPI ADDRESSING"
Each user of
.B 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.
.\"
.\"
.PP
.B PHYSICAL ATTACHMENT IDENTIFICATION
.\"
.\"
.PP
The physical point of attachment (PPA) is the point at which a system attaches
itself to a physical communications medium.  All communication on that
physical medium funnels through the PPA.
.\"
.\"
.PP
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.
.\"
.\"
.PP
Two styles of DLS provider are defined by
.BR 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
.IR STREAMS (4)
clone open feature to be used for each PPA configured.  This style of provider
is appropriate when few PPAs will be supported.
.\"
.\"
.PP
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. 
.B DLPI
provides a mechanism to get and/or modify the physical address.  The
primitives to handle these functions are described in Appendix A.  The
physical address value can be modified in a post-attached state.  This would
modify the value for all streams for that provider for a particular PPA.  The
physical address cannot be modified if even a single stream for that PPA is in
the bound state.
.\"
.\"
.PP
The DLS User uses the supported primitives
.RB ( DL_ATTACH_REQ (7),
.BR DL_BIND_REQ (7),
.BR DL_ENABMULTI_REQ (7),
.BR DL_PROMISCON_REQ (7))
to define a set of enabled physical and SAP address components on a per Stream
basis.  It is invalid for a DLS Provider to ever send upstream a data message
for which the DLS User on that stream has not requested.  The burden is on the
provider to enforce by any means that it chooses, the isolation of SAP and
physical address space effects on a per-stream basis.
.\"
.\"
.PP
.B DATA LINK USER IDENTIFICATION
.\"
.\"
.PP
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,
.B DLPI
provides a mechanism for decomposing the DLSAP address into component pieces.
The
.BR DL_INFO_ACK (7)
primitive returns the length of the SAP component of the DLSAP address, along
with the total length of the DLSAP address.  Certain DLS Providers require the
capability of binding on multiple DLSAP addresses.  This can be achieved
through subsequent binding of DLSAP addresses.
.B 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
.BR DL_BIND_REQ (7).
This will allow for a choice to be made between a number of DLSAPs on a stream
when determining traffic based on DLSAP values.  An example of this would be
to specify various ether_type values as DLSAPs.  The
.BR DL_BIND_REQ (7),
for example, could be issued with ether_type value of IP, and a subsequent
bind could be issued with ether type value of ARP.  The Provider may now
multiplex off of the ether_type field and allow for either IP or ARP traffic
to be sent up this stream.  When the DLS User requests hierarchical binding,
the subsequent bind will specify a DLSAP that will be used in addition to the
DLSAP bound using a
.BR DL_BIND_REQ (7).
This will allow additional information to be specified, that will be used in a
header or used for de-multiplexing.  An example of this would be to use
hierarchical bind to specify the OUI (Organizationally Unique Identifier) to
be used by SNAP.
.\"
.\"
.SS "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