smi.7

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

'\" t
.\" -*- nroff -*-
.\"
.\" @(#) smi.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
.\"
.\" smi.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.4  2001/01/17 00:29:10  brian
.\" Working on man pages.
.\"
.\" 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/08 09:17:23  brian
.\" Updated man pages somewhat.
.\"
.\" 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 SS7 7 "2001/12/11 13:16:08" "SS7 STREAMS Man Page" "Linux STREAMS Programmer's Manual" 
.SH "NAME"
smi \- Signalling System No. 7 - SS7 Management Interface (SMI)
.SH "SYNOPSIS"
.nf
\fB#include <ss7/smi.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 SS7
Management Interface (SMI) specification.

SMI 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 the SMI for management.

The SMI consists of two subcomponents:
.TP
.I "PROTOCOL MANAGEMENT INTERFACE"
SMI provides a protoocl 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"
SMI 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 "PROTOCOL MANAGEMENT INTERFACE"
Protocol management primitives are provided to allow for
protocol-layer-specific configuration, state examination, statistical and
event retporting.  These primitives use a layer-specific  configuration structure
\fImodname\fR\fB_config_t\fR, state machine structure \fImodname\fR\fB_statem_t\fR,
statistics structure \fImodname\fR\fB_stats_t\fR and event categories.

Protocol management primitives are exchanged using \fBM_PROTO\fR and
\fBM_PCPROTO\fR messages in the same manner as protocol primitives, using
\fBputmsg\fR(2) and \fBgetmsg\fR(2) system calls at the stream head or using
the pass through mechanism provided by the control stream of an open
multiplexor (see \fBsls\fR(8) and \fBmtp\fR(8)).  These primitivies are
normally only used by the \fBss7d\fR(8) during configuration and operation,
but may be used for testing and special purposes by user-level programs from
the stream head.

To avoid define clashes, protocol modules will also accept \fBM_CTL\fR
messages with these primitives for inter-module communications, and many of
the primitive functions are also supported using the \fBioctl\fR(2) interface
described in the next section.

.SS Protocol Configuration
.PP
Protocol management primitives are invoked by stack and layer management to
configure or request configuration information from the layer service
provider.  Any \fBM_DATA\fR block attached to the primitives contains a
\fImodname\fR\fB_config_t\fR structure (see below) which represents the
configuration parameters.  Configuration requests should normally be sent as
\fBM_PCPROTO\fR or \fBM_CTL\fR messages.
.PP
Each \fIOpenSS7\fR module defines a configuration structure
\fImodname\fR\fB_config_t\fR which contains the following two members:
.RS
.sp
.nf
typedef struct \fImodname\fR_config {
    ss7_ulong   pvar;   /* protocol variant */
    ss7_ulong   popt;   /* protocol options */
    \fI...\fR
    \fI/* additional level specific options */\fR
    \fI...\fR
} \fImodname\fR_config_t;
.fi
.RE
.TP
.I pvar
The \fIOpenSS7\fR stack provides the capability to run many SS7 protocol
variants simultaneously.  Therefore, all \fIOpenSS7\fR stack modules contain a
\fIpvar\fR configuration parameter which contains the selected protocol
variant.  Currently defined protocol variants are as follows:
.IP
.B SS7_PVAR_ITUT_88
ITU-T Q.700 Series Blue Book
.br
.B SS7_PVAR_ITUT_93
ITU-T Q.700 Series White Book
.br
.B SS7_PVAR_ITUT_96
ITU-T Q.700 Series Grey Book
.br
.B SS7_PVAR_ITUT_00
ITU-T Q.700 Series Black Book
.br
.B SS7_PVAR_ETSI_88
ETSI ETS 300 Series (based on Blue Book)
.br
.B SS7_PVAR_ETSI_93
ETSI ETS 300 Series (based on White Book)
.br
.B SS7_PVAR_ETSI_96
ETSI ETS 300 Series (based on Grey Book)
.br
.B SS7_PVAR_ETSI_00
ETSI ETS 300 Series (based on Black Book)
.br
.B SS7_PVAR_ANSI_88
ANSI T1.111-1988
.br
.B SS7_PVAR_ANSI_92
ANSI T1.111-1992
.br
.B SS7_PVAR_ANSI_96
ANSI T1.111-1996
.br
.B SS7_PVAR_ANSI_00
ANSI T1.111-2000
.br
.B SS7_PVAR_JTTC_94
Japan TTC JQ.700 Series (based on Blue Book)
.IP
These protocol variant parameters are defined in such a way that they can be
tested against the following to find the major variant:
.IP
.B SS7_PVAR_ITUT
ITU-T Q.700 Series
.br
.B SS7_PVAR_ETSI
ETSI ETS 300 Series (based on ITU-T)
.br
.B SS7_PVAR_ANSI
ANSI T1.111
.br
.B SS7_PVAR_JTTC
TTC JQ.700 Series
.TP
.I popt
In addition, each \fIOpenSS7\fR module can enable or disable a number of major options
which are described in the standards specifications.  Each \fIOpenSS7\fR module has a
\fIpopt\fR configuration parameter which contains a bit vector of the enabled
protocol options for that module.  For a definition of the options at each
level, see the man page for the specific interface.
.TP
.I ...
Additional configuration members are layer-specific and are defined by the
corresponding layer interface specifications.  See section "SS7 STREAMS
INTERFACES" for more information.
.PP
Each \fIOpenSS7\fR module recognizes protocol management primitives for
configuration.  These primitives are invoked by protocol layer management to
configure or request configuration information from the layer service
provider.  Any \fBM_DATA\fR block attached to the primitives contains a
\fImodname\fR\fB_config_t\fR structure (see above) which represents the configuration
parameters.  Configuration request should normally be sent as \fBM_PCPROTO\fR
messages.
.TP
.B SMI_CONFIG_SETUP
Test if the configuration parameters provided in the attached \fBM_DATA\fR
block are settable and correct.  Any values set to \fI0xffffffff\fR in the
configuration parameters should not be tested for change by the layer service
provider.  When successful, this request also write locks the configuration
until a successful \fBSMI_CONFIG_COMMIT\fR is executed.
This primitive contains only the \fIsmi_primitive\fR member.
.TP
.B SMI_CONFIG_COMMIT
Commits the changes of a previous successful \fBSMI_CONFIG_TEST\fR operation.
No configuration data is associated with this request and any attached
\fBM_DATA\fR is ignored.  When successful, this request also releases the
write locks on the configuration.
This primitive contains only the \fIsmi_primitive\fR member.
.TP
.B SMI_CONFIG_SET
Sets the configuration parameters to the values provided in the attached
\fBM_DATA\fR block.  This request will fail if the configuration is write
locked.
This primitive contains only the \fIsmi_primitive\fR member.
.TP
.B SMI_CONFIG_GET
Get the configuration parameters.  Any attached \fBM_DATA\fR is ignored.  If
the configuration is write locked, this request will only return the values
which have been setup for a commit and not necessarily the current values.
This primitive contains only the \fIsmi_primitive\fR member.
.TP
\fBERRORS\fR (see also "ERROR HANDLING")

Upon success, the layer service provider will return a \fBSMI_OK_ACK\fR to
confirm a successful configuration request.  The provider attached a
\fBM_DATA\fR block which contains the \fImodname\fR\fB_config_t\fR structure with
the results of the configuration request.

Upon failure, the layer service provider will return a \fBSMI_ERROR_ACK\fR to
reject the configuration request due to an error.  The provider attaches a
\fBM_DATA\fR block which contains a \fImodname\fR\fB_config_t\fR structure with
\fI0xffffffff\fR in any values which are in error.

Error numbers \fIsmi_errno\fR which are specific to a configuration request
rejection are as follows:
.RS
.TP 16
.B SMI_CONFLOCKED
The request attempted to perform an illegal operation on a locked
configuration.
.TP
.B SMI_NOCONFDATA
The request was missing configuration data (i.e. missing \fBM_DATA\fR block or
\fBM_DATA\fR block too short.
.TP
.B SMI_BADCONFDATA
Some configuration data was invalid.  The attached \fBM_DATA\fR block contains
\fI0xffffffff\fR in the data elements which are considered invalid.
.RE

.SS "Protocol State"

Each \fIOpenSS7\fR module defines a state structure
\fImodname\fR\fB_statem_t\fR which contains primary state machine variables
and flags.
These structures may be included in \fBM_DATA\fR blocks and attached to
protocol management primitives affecting or indicating state.  The
\fImodname\fR\fB_statem_t\fR structure is formatted as follows:
.RS
.sp
.nf
typedef struct {
    smi_ulong   \fIsm_mod1\fR_state;
    smi_ulong   \fIsm_mod2\fR_state;
    smi_ulong       \fIsm_mod2_flag1\fR;
    smi_ulong       \fIsm_mod2_flag2\fR;
    smi_ulong   \fIsm_mod3\fR_state;
    smi_ulong       \fIsm_mod3_flag1\fR;
    smi_ulong   \fIsm_mod4\fR_state;
} \fImodname\fR_statem_t;
.fi
.RE
.TP
\fIsm_modX\fR_state

.TP
\fIsm_modX_flagY\fR

.PP
Protocol management primitives may be invoked by stack or layer management to
request and return state information about the layer service provider.  This
may be useful for resynchronization between protocol modules as well as for
testing and diagnostic purposes.  Any \fBM_DATA\fR block attached to the
primitive or acknowledgement contains a layer-specific
\fImodname\fR\fB_statem_t\fR structure (see above) which represents the
current state of the layer protocol state machines.  State requests may be
sent as \fBM_PROTO\fR or \fBM_PCPROTO\fR messages depending on their urgency.
Upstream modules may send a \fBM_CTL\fR message if desired.

.TP
.B SMI_STATE_REQ
Requests that the layer service provider return the current state variables
associated with the layer state machines.  This primitive uses the
\fBsmi_state_req_t\fR structure which contains only the \fIsmi_primitive\fR.
.TP
\fBERRORS\fR (see also "ERROR HANDLING")

Upon success, the layer service provider will return a \fBSMI_OK_ACK\fR to
confirm the successful state request.  The provider attaches a \fBM_DATA\fR
block which contains the \fImodname\fR\fB_statem_t\fR structure containing the
layer-specific state variables.

Upon failure, the layer service provider will return a \fBSMI_ERROR_ACK\fR to
reject the state request.  Normally a request is successful and only the
general error codes (see "ERROR HANDLING") will be returned.

.SS "Protocol Statistics"

Protocol management primitives may be invoked by the stack or layer management
to request and return statistical information collected during the operation
of the layer service provider.  Any \fBM_DATA\fR block attached to the
primitive or acknowledgement contains a layer-specific
\fImodname\fR\fB_stats_t\fR structure (see above) which represents current
collection periods and the statistics collected during the collection
interval by the provider.  Statistics requests should be sent as low priority
band \fBM_PROTO\fR or \fBM_CTL\fR messages.  The provider will respond with
low priority band \fBM_PROTO\fR or \fBM_CTL\fR messages for all but error
conditions, which are sent as \fBM_PCPROTO\fR.  \fBSMI_STATS_IND\fR messages
will all be sent as low priority band \fBM_PROTO\fR or \fRM_CTL\fR messages.
This avoids congestion resulting from synchronized data collection intervals
across a number of managed objects in the stack.
.TP
.B SMI_STATS_SET
Sets the statistics collection and aggregation parameters as well clearing any
counts marked as \fI0xffffffff\fR provided in the attached \fBM_DATA\fR block
containing a \fImodname\fR\fB_stats_t\fR structure.
This primitives uses the \fBsmi_stats_set_t\fR structure which contains the
\fIsmi_primitive\fR as its only member.
.TP
.B SMI_STATS_GET
Gets the statistics collection and aggregation parameters as well as the
counts for the current collection interval.
This primitives uses the \fBsmi_stats_get_t\fR structure which contains the
\fIsmi_primitive\fR as its only member.
.TP
.B SMI_STATS_IND
Delivers an indication of the aggregated statistics for a collection interval.
An attached \fBM_DATA\fR block contains the aggregated statistics for the
collection interval.
This primitives uses the \fBsmi_stats_ind_t\fR struct which contains the
following members:
.RS
.sp
.nf
typedef struct {
    smi_ulong   smi_primitive;  /* SMI_STATS_IND */
    smi_ulong   smi_interval;
    smi_ulong   smi_timestamp;
} smi_stats_ind_t;
.fi
.TP
.I smi_interval
The interval for which this indication corresponds (in jiffies).  This could
normally be 5 minutes, 15 minutes, 30 minutes, 60 minutes.
.TP
.I smi_timestamp
The UNIX timestamp (seconds since epoch) corresponding to the beginning of the
interval for which statistics have been collected.
.RE
.TP
\fBERRORS\fR (see also "ERROR HANDLING")

Upon success, the layer service provider will return a \fBSMI_OK_ACK\fR to
confirm the successful statistics request.  The provider attaches a
\fBM_DATA\fR block which contians the \fImodname\fR\fB_stats_t\fR structure
containing the layer-specific statistics parameters and counts.