lmi.7

No7信令,我需要交换类似的代码, 请店长审核,谢谢了,急着交换,谢谢

'\" t
.\" -*- nroff -*-
.\"
.\" @(#) lmi.7,v 0.7.8.1 2001/12/11 13:16:08 brian Exp
.\"
.\" =========================================================================
.\"
.\" This manpage is Copyright (C) 1997-2001  Brian Bidulock.
.\"
.\" 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.
.\"
.\" =========================================================================
.\"
.\" Last Modified 2001/12/11 13:16:08 by brian
.\"
.\" lmi.7,v
.\" Revision 0.7.8.1  2001/12/11 13:16:08  brian
.\" Branched for new development.
.\"
.\" Revision 0.7.6.1  2001/02/18 12:11:14  brian
.\" New working branch for next release.
.\"
.\" Revision 0.7.4.1  2001/02/18 09:44:48  brian
.\" Added new working branch.
.\"
.\" Revision 0.7.2.7  2001/01/17 03:04:12  brian
.\" Removed interface lists from lmi.
.\"
.\" Revision 0.7.2.6  2001/01/17 00:29:10  brian
.\" Working on man pages.
.\"
.\" Revision 0.7.2.5  2001/01/16 03:19:47  brian
.\" Updated man pages.
.\"
.\" Revision 0.7.2.4  2001/01/15 03:55:48  brian
.\" Completed LMI man page.
.\"
.\" Revision 0.7.2.3  2001/01/14 23:29:12  brian
.\" Changed copyright notice.
.\"
.\" Revision 0.7.2.2  2001/01/14 11:07:53  brian
.\" Changed headers back to GPL.
.\"
.\" Revision 0.7.2.1  2001/01/09 07:13:09  brian
.\" Changes to man pages.
.\"
.\" Revision 0.7  2001/01/08 09:17:48  brian
.\" Added LMI man page.
.\"
.\" Revision 0.7  2000/11/29 02:09:56  brian
.\" Added man pages for interfaces.
.\"
.\" Revision 0.7  2000/11/19 00:25:57  brian
.\" Added man pages for streams drivers.
.\"
.\" =========================================================================
.TH LMI 7 "2001/12/11 13:16:08" "SS7 STREAMS Man Page" "Linux STREAMS Programmer's Manual" 
.SH "NAME"
lmi \- Signalling System No. 7 - Local Management Interface (LMI)
.SH "SYNOPSIS"
.nf
\fB#include <ss7/lmi.h>\fR
\fB#include <ss7/lmi_ioctl.h>\fR

\fIfd\fB = open("\fI/dev/module\fB", \fIflags\fB);
\fIret\fB = ioctl(\fIfd\fB, \fIcmd\fB, ... /* \fIarg\fB */ );
.fi
.SH "DESCRIPTION"
This man page describes the STREAMS interface which is used to manage and
configure SS7 modules and drivers conforming to the \fIOpenSS7\fR Local
Management Interface (LMI) specification.

LMI is the common interface to \fIOpenSS7\fR modules and drivers configured by
the SS7 Configuration Daemon \fBss7d\fR(8) using \fBstreamio\fR(7)
\fBI_PUSH\fR and \fBI_LINK\fR ioctls.  This interface is also available for
the development of special purposes management entities (e.g. SNMP, TMN) for
management of the \fIOpenSS7\fR stack.  All SS7 drivers, modules and
multiplexors in the \fIOpenSS7\fR stack provide for LMI management.

The LMI consists of two subcomponents:
.TP
.I "LOCAL MANAGEMENT INTERFACE"
LMI provides a local management interface which utilizes \fBM_PROTO\fR and
\fBM_PCPROTO\fR messages which can be exchanged with the interface using
\fBputmsg\fR(2) and \fBgetmsg\fR(2) system calls on the stream head once the
interface is opened.  The local management interface controls local management
(STREAMS configuration functions) which are normally used by the SS7
Configuration Daemon \fBss7d\fR(8) on the driver interface or the control
channel of a multiplexor before pushing a module on the stream head or linking
a stream under the multiplexor.  The local management interface is described
in detail in the the section "LOCAL MANAGEMENT INTERFACE".
.TP
.I "PROTOCOL MANAGEMENT INTERFACE"
LMI provides a protocol management interface which utilizes \fBM_PROTO\fR and
\fBM_PCPROTO\fR messages which can be exchanged with \fBputmsg\fR(2) and
\fBgetmsg\fR(2) system calls on the stream head or control stream once the
interface is opened, or \fBM_CTL\fR(2) messages between modules.  The protoocl
management interface supports general and layer-specific configuration, state
inquiry, event and statistics control (SNMP functions) which are normally used
by the SS7 Configuration Daemon \fBss7d\fR(8) on the driver interface or
multiplexor control channel before or after the SS7 protocol stack has been
configured.
.TP
.I "INPUT OUTPUT CONTROL INTERFACE"
LMI provides a control interface which utilizes \fBioctl\fR(2) transparent
calls, pass-through calls, or \fBI_STR\fR ioctl calls using \fBstreamio\fR(2)
from a stream head or a multiplexor control stream.  The control interface
provides for the control of layer-specific and device-specific aspects which
are outside the scope of the SS7 protocol proper, such as interface
configuration and is normally used by the SS7 Configuration Daemon
\fBss7d\fR(8) or upstream modules during stack operation.

.SH "LOCAL MANAGEMENT INTERFACE"
.SS "PPA STYLE"
.PP
From the local management view, most low-level LMI providers can support two
style for Point of Physical Address (PPA) selection.  These sytles are as
follows:
.TP
.B LMI_STYLE1
A \fIStyle 1\fR driver is a driver whose Point of Physical Address (PPA) is
associated with the stream at open time.  These drivers do not really
do anything in response to the \fBLMI_ATTACH_REQ\fR, but still require the
primitive to move the interface from the \fBLMI_UNATTACHED\fR state to the
\fBLMI_DISABLED\fR state.  \fIStyle 1\fR drivers do not require PPA addresses.
.TP
.B LMI_STYLE2
A \fIStyle 2\fR driver is a driver whose Point of Physical Appearance (PPA)
must be attached to the stream after open.  These drivers open in the
\fBLMI_UNATTACHED\fR state and must be attached with a \fBLMI_ATTACH_REQ\fR
local management primitive to associate them with a PPA before they can be
enabled for use.  \fIStyle 2\fR drivers require a PPA (Physical Point of
Attachment) address to indicate the physical transmission channel to which the
stream is to be attached.  The PPA Address is an opaque address which is
meaningful only to a specific driver implementation.

.SS "LOCAL MANAGEMENT STATES"
.PP
From the perspective of local management, the LMI provider can be in a number
of management states.  Some local management primitives are applicable only in
specific states.  The LMI provider can be moved through the states with local
management primitives.
.PP
The management states of the LMI provider are as follows:
.TP
.B LMI_UNATTACHED
The LMI driver or module is not attached to a PPA.  This state is only
meaningful to \fIStyle 2\fR drivers which must be explicitly attached to a
specific transmission channel.  Both \fIStype 1\fR and \fIStyle 2\fR drivers
open in this state.
.TP
.B LMI_UNUSABLE
The LMI driver or module is unusable.  This state occurs when the STREAMS
module or driver is no longer able to perform local management actions on the
LMI provider.  This may be due to the failure, removal, or failure to
communicate with, some component in the system.  The LMI provider cannot be
moved to this state with a local management primitive: this state only results
from internal events.
.TP
.B LMI_DISABLED
The LMI driver or module is attached but has not yet been enabled for use.
The driver must be enabled with a \fBLMI_ENABLE_REQ\fR local management
primitive before data or protocol primtives may be exchanged with the driver
or module.
.TP
.B LMI_ENABLE_PENDING
The LMI driver or module has accepted a \fBLMI_ENABLE_REQ\fR request on the
interface, but the provider must wait until some event occurs before the
provider can be considered to be enabled.  The provider will respond with a
\fBLMI_ENABLE_CON\fR confirmation once the enabling is successful, or a
\fBLMI_ERROR_ACK\fR if unsuccessful.

Most drivers use the \fBLMI_ENABLE_REQ\fR primitive and this state to peform
initialization on the device and preparations necessary for data exchange such
as assignment and activation of interrupt service routines.  Because this
initialization may entail communications with independent interface
processors, a pending state is provided.
.TP
.B LMI_ENABLED
The LMI driver or module is enabled and ready for use (to provide protocol
services).
.TP
.B LMI_DISABLE_PENDING
The LMI driver or module has accepted a \fBLMI_DISABLE_REQ\fR request on the
interface, but the provider must wait until some event occurs before the
provider can be considered disabled.  The provider will respond with a
\fBLMI_DISABLE_CON\fR confirmation once the disabling is successful, or a
\fBLMI_ERROR_ACK\fR if unsuccessful.

Most drivers use the \fBLMI_DISABLE_REQ\fR primitive and this state to perform
deactivation of the device and actions necessary to shut down data exchange
such as removal and deactivation of interrupt service routines.  Because this
deactivation may entail communications with independent interface processors,
a pending state is provided.

.SS "LOCAL MANAGEMENT PRIMITIVES"
.PP
Local management primitives can be exchanged with the device driver as
\fBM_PROTO\fR or \fBM_PCPROTO\fR primitives using the \fBputmsg\fR(2) or
\fBgetmsg\fR(2) system calls on the stream head after opening the device.
This interface is normally used only by the SS7 Configuration Daemon
\fBss7d\fR(8) during STREAMS configuration, or by the upstream protocol
modules during \fBstreamio\fR(7) \fBI_PUSH\fR and \fBI_POP\fR operations.  It
is possible, however, for a user-level program to use this interface directly
on an open driver or module stream head for special purposes and testing.
.PP
Only \fBM_PROTO\fR local management primitives will be deferred during
congestion or overload of the driver or module.  Local management primitives
sent as \fBM_PCPROTO\fR will be discarded and return a \fBLMI_ERROR_ACK\fR in
repsonse should it not be possible to execute them immediately.
.PP
Local management primitives provided by the LMI are as follows:
.PP
.B LMI_INFO_REQ, LMI_INFO_ACK, LMI_ERROR_ACK
.PP
Invoked by the LMI user to request and return information about the LMI
provider which is of interest to local configuration management.  These
requests are normally performed by the SS7 Configuration Daemon \fBss7d\fR(8)
on the stream head.
.TP
.B LMI_INFO_REQ
\fBLMI_INFO_REQ\fR uses a \fBlmi_info_req_t\fR structure which contains the
request primitive, \fIlmi_primitive\fR, as its only member
.TP
.B LMI_INFO_ACK
\fBLMI_INFO_ACK\fR uses \fBlmi_info_ack_t\fR structure as follows:
.RS
.sp
.nf
typedef struct {
    lmi_ulong   lmi_primitive;  /* LMI_INFO_ACK */
    lmi_ulong   lmi_version;
    lmi_ulong   lmi_state;
    lmi_ulong   lmi_max_sdu;
    lmi_ulong   lmi_min_sdu;
    lmi_ulong   lmi_ppa_style;
    lmi_ulong   lmi_ppa_addr[0];
} lmi_info_ack_t;
.fi
.TP
.I lmi_primitive
The primitive number which is set to \fBLMI_INFO_ACK\fR.
.TP
.I lmi_version
The version of the LMI interface specification to which the device conforms
with one byte per version umber in host order.  The current (and only) version
of the LMI is \fI1.0.0.0\fR or \fI0x10000000\fR.
.TP
.I lmi_state
The current local management state of the LMI interface.
.TP
.I lmi_max_sdu
The minimum data unit size which may be transferred to and from the
transmission channel.  From some devices this may be zero.
.TP
.I lmi_min_sdu
The maximum data unit size which may be transferred to and from the
transmission channel.  For some devices this size may be unlimited, in which
case the value returned here is \fI0xffffffff\fR.
.TP
.I lmi_ppa_style
The style of the driver which may be one of the following:
.RS
.TP
.B LMI_STYLE1
A \fIStyle 1\fR device which is implicitly associated with a transmission
channel at the time that the device is opened.  These devices do not require a
PPA address in the \fBLMI_ATTACH_REQ\fR.
.TP
.B LMI_STYLE2
A \fIStyle 2\fR device which is explicitly associated with a transmission
channel identified by a \fIlmi_ppa_addr\fR in an \fBLMI_ATTACH_REQ\fR
local management primitive after opening.  These devices open in the
\fBLMI_UNATTACHED\fR state.
.RE
.TP
.I lmi_ppa_addr
The PPA address that a \fIStyle 2\fR device is attached to.  If the device is
a \fIStyle 1\fR device or an unattached \fIStyle 2\fR device, this member will
return all zeros.
.RE
.TP
.B LMI_ERROR_ACK
\fBLMI_ERROR_ACK\fR containing the error number in \fIlmi_errno\fR and an
error explanation in \fIlmi_reason\fR will be returned by the LMI provider in
the rare event that an error occurs while attempting to retreive the
information requested by a \fBLMI_INFO_REQ\fR.
.PP
.B LMI_ATTACH_REQ, LMI_OK_ACK, LMI_ERROR_ACK
.PP
Invoked by the LMI user to attach a \fIStyle 2\fR LMI driver or module to a
PPA using a PPA Address.  This primitive is normally used by the SS7
Configuration Daemon \fBss7d\fR(8) when assembling the SS7 protocol stack.
The PPA address is obtained by the daemon from configuration files.
.TP
.B LMI_ATTACH_REQ
Request that the LMI driver or module attach to the PPA address specified in
the request.  The \fBLMI_ATTACH_REQ\fR primitive is only valid from the
\fBLMI_UNATTACHED\fR state for a \fIStyle 1\fR or \fIStyle 2\fR interface.
\fBLMI_ATTACH_REQ\fR uses the \fBlmi_attach_req_t\fR structure as follows:
.RS
.sp
.nf
typedef struct {
    lmi_ulong   lmi_primitive;  /* LMI_ATTACH_REQ */
    lmi_ulong   lmi_ppa[0];
} lmi_attach_req_t;
.fi
.TP
.I lmi_primitive
The primitive number which is set to \fBLMI_ATTACH_REQ\fR.
.TP
.I lmi_ppa_addr
Specifies the PPA (Physical Point of Appearance) of the transmision channel to
which the LMI driver should attach.  This is an opaque address to the
interface and is only meaningful to a specific driver implementation.
.RE
.TP
.B LMI_OK_ACK
Returned if the attach request is successful.
.TP
.B LMI_ERROR_ACK
Returned with the error number and explanation set if the attach request
fails.
.PP
.B LMI_DETACH_REQ, LMI_OK_ACK, LMI_ERROR_ACK
.PP
Invoked by the LMI user to detach a \fIStyle 2\fR LMI driver from its PPA.
This primitive is normally used by the SS7 Configuration Daemon \fBss7d\fR(8)
when disassembling or reconfiguring the SS7 protocol stack.
.TP
.B LMI_DETACH_REQ
Requests that the LMI driver detach itself from the current attached PPA.
\fBLMI_DETACH_REQ\fR is only valid for \fBStyle 1\fR or \fBStyle 2\fR drivers
in the \fBLMI_DISABLED\fR state.  The \fBLMI_DETACH_REQ\fR uses the
\fBlmi_detach_req_t\fR structure which contains only the \fIlmi_primitive\fR
which is set to \fBLMI_DETACH_REQ\fR.
.TP
.B LMI_OK_ACK
Returned if the detach request was successful.
.TP
.B LMI_ERROR_ACK
Returned with the error number and explanation set if the detach request
fails.
.PP
.B LMI_ENABLE_REQ, LMI_ENABLE_CON, LMI_ERROR_ACK
.PP
Invoked by the LMI on a \fIStyle 1\fR or \fIStyle 2\fR LMI provider to enable
it for data transfer and protocol operations.  This primitive is normaly used