SS7(7)

NAME
smi - Signalling System No. 7 - SS7 Management Interface (SMI)

SYNOPSIS
#include <ss7/smi.h>
fd = open("/dev/module", flags);
ret = ioctl(fd, cmd, ... /* arg */ );

DESCRIPTION
This man page describes the STREAMS interface which is used to manage and configure SS7 modules and drivers conforming to the OpenSS7 SS7 Management Interface (SMI) specification. SMI is the common interface to OpenSS7 modules and drivers configured by the SS7 Configuration Daemon ss7d(8) using streamio(7) I_PUSH and I_LINK ioctls. This interface is also available for the development of special purposes management entities (e.g. SNMP, TMN) for management of the OpenSS7 stack. All SS7 drivers, modules and multiplexors in the OpenSS7 stack provide the SMI for management. The SMI consists of two subcomponents:

PROTOCOL MANAGEMENT INTERFACE
    SMI provides a protoocl management interface which utilizes M_PROTO and M_PCPROTO messages which can be exchanged with putmsg(2) and getmsg(2) system calls on the stream head or control stream once the interface is opened, or M_CTL(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 ss7d(8) on the driver interface or multiplexor control channel before or after the SS7 protocol stack has been configured.

INPUT OUTPUT CONTROL INTERFACE
    SMI provides a control interface which utilizes ioctl(2) transparent calls, pass-through calls, or I_STR ioctl calls using streamio(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 ss7d(8) or upstream modules during stack operation.

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 modname_config_t, state machine structure modname_statem_t, statistics structure modname_stats_t and event categories. Protocol management primitives are exchanged using M_PROTO and M_PCPROTO messages in the same manner as protocol primitives, using putmsg(2) and getmsg(2) system calls at the stream head or using the pass through mechanism provided by the control stream of an open multiplexor (see sls(8) and mtp(8)). These primitivies are normally only used by the ss7d(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 M_CTL messages with these primitives for inter-module communications, and many of the primitive functions are also supported using the ioctl(2) interface described in the next section.

  Protocol Configuration

Protocol management primitives are invoked by stack and layer management to configure or request configuration information from the layer service provider. Any M_DATA block attached to the primitives contains a modname_config_t structure (see below) which represents the configuration parameters. Configuration requests should normally be sent as M_PCPROTO or M_CTL messages.

Each OpenSS7 module defines a configuration structure modname_config_t which contains the following two members:

    typedef struct modname_config {
        ss7_ulong   pvar;   /* protocol variant */
        ss7_ulong   popt;   /* protocol options */
        ...
        /* additional level specific options */
        ...
    } modname_config_t;

pvar
    The OpenSS7 stack provides the capability to run many SS7 protocol variants simultaneously. Therefore, all OpenSS7 stack modules contain a pvar configuration parameter which contains the selected protocol variant. Currently defined protocol variants are as follows:

    SS7_PVAR_ITUT_88 ITU-T Q.700 Series Blue Book
    SS7_PVAR_ITUT_93 ITU-T Q.700 Series White Book
    SS7_PVAR_ITUT_96 ITU-T Q.700 Series Grey Book
    SS7_PVAR_ITUT_00 ITU-T Q.700 Series Black Book
    SS7_PVAR_ETSI_88 ETSI ETS 300 Series (based on Blue Book)
    SS7_PVAR_ETSI_93 ETSI ETS 300 Series (based on White Book)
    SS7_PVAR_ETSI_96 ETSI ETS 300 Series (based on Grey Book)
    SS7_PVAR_ETSI_00 ETSI ETS 300 Series (based on Black Book)
    SS7_PVAR_ANSI_88 ANSI T1.111-1988
    SS7_PVAR_ANSI_92 ANSI T1.111-1992
    SS7_PVAR_ANSI_96 ANSI T1.111-1996
    SS7_PVAR_ANSI_00 ANSI T1.111-2000
    SS7_PVAR_JTTC_94 Japan TTC JQ.700 Series (based on Blue Book)

    These protocol variant parameters are defined in such a way that they can be tested against the following to find the major variant:

    SS7_PVAR_ITUT ITU-T Q.700 Series
    SS7_PVAR_ETSI ETSI ETS 300 Series (based on ITU-T)
    SS7_PVAR_ANSI ANSI T1.111
    SS7_PVAR_JTTC TTC JQ.700 Series

popt
    In addition, each OpenSS7 module can enable or disable a number of major options which are described in the standards specifications. Each OpenSS7 module has a popt 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.

... Additional configuration members are layer-specific and are defined by the corresponding layer interface specifications. See section "SS7 STREAMS INTERFACES" for more information.

Each OpenSS7 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 M_DATA block attached to the primitives contains a modname_config_t structure (see above) which represents the configuration parameters. Configuration request should normally be sent as M_PCPROTO messages.

SMI_CONFIG_SETUP
    Test if the configuration parameters provided in the attached M_DATA block are settable and correct. Any values set to 0xffffffff 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 SMI_CONFIG_COMMIT is executed. This primitive contains only the smi_primitive member.

SMI_CONFIG_COMMIT
    Commits the changes of a previous successful SMI_CONFIG_TEST operation. No configuration data is associated with this request and any attached M_DATA is ignored. When successful, this request also releases the write locks on the configuration. This primitive contains only the smi_primitive member.

SMI_CONFIG_SET
    Sets the configuration parameters to the values provided in the attached M_DATA block. This request will fail if the configuration is write locked. This primitive contains only the smi_primitive member.

SMI_CONFIG_GET
    Get the configuration parameters. Any attached M_DATA 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 smi_primitive member.

ERRORS (see also "ERROR HANDLING")
    Upon success, the layer service provider will return a SMI_OK_ACK to confirm a successful configuration request. The provider attached a M_DATA block which contains the modname_config_t structure with the results of the configuration request. Upon failure, the layer service provider will return a SMI_ERROR_ACK to reject the configuration request due to an error. The provider attaches a M_DATA block which contains a modname_config_t structure with 0xffffffff in any values which are in error. Error numbers smi_errno which are specific to a configuration request rejection are as follows:

    SMI_CONFLOCKED
        The request attempted to perform an illegal operation on a locked configuration.

    SMI_NOCONFDATA
        The request was missing configuration data (i.e. missing M_DATA block or M_DATA block too short.

    SMI_BADCONFDATA
        Some configuration data was invalid. The attached M_DATA block contains 0xffffffff in the data elements which are considered invalid.

  Protocol State
Each OpenSS7 module defines a state structure modname_statem_t which contains primary state machine variables and flags. These structures may be included in M_DATA blocks and attached to protocol management primitives affecting or indicating state. The modname_statem_t structure is formatted as follows:

    typedef struct {
        smi_ulong   sm_mod1_state;
        smi_ulong   sm_mod2_state;
        smi_ulong       sm_mod2_flag1;
        smi_ulong       sm_mod2_flag2;
        smi_ulong   sm_mod3_state;
        smi_ulong       sm_mod3_flag1;
        smi_ulong   sm_mod4_state;
    } modname_statem_t;

sm_modX_state

sm_modX_flagY

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 M_DATA block attached to the primitive or acknowledgement contains a layer-specific modname_statem_t structure (see above) which represents the current state of the layer protocol state machines. State requests may be sent as M_PROTO or M_PCPROTO messages depending on their urgency. Upstream modules may send a M_CTL message if desired.

SMI_STATE_REQ
    Requests that the layer service provider return the current state variables associated with the layer state machines. This primitive uses the smi_state_req_t structure which contains only the smi_primitive.

ERRORS (see also "ERROR HANDLING")
    Upon success, the layer service provider will return a SMI_OK_ACK to confirm the successful state request. The provider attaches a M_DATA block which contains the modname_statem_t structure containing the layer-specific state variables. Upon failure, the layer service provider will return a SMI_ERROR_ACK to reject the state request. Normally a request is successful and only the general error codes (see "ERROR HANDLING") will be returned.

  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 M_DATA block attached to the primitive or acknowledgement contains a layer-specific modname_stats_t 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 M_PROTO or M_CTL messages. The provider will respond with low priority band M_PROTO or M_CTL messages for all but error conditions, which are sent as M_PCPROTO. SMI_STATS_IND messages will all be sent as low priority band M_PROTO or M_CTL messages. This avoids congestion resulting from synchronized data collection intervals across a number of managed objects in the stack.

SMI_STATS_SET
    Sets the statistics collection and aggregation parameters as well clearing any counts marked as 0xffffffff provided in the attached M_DATA block containing a modname_stats_t structure. This primitives uses the smi_stats_set_t structure which contains the smi_primitive as its only member.

SMI_STATS_GET
    Gets the statistics collection and aggregation parameters as well as the counts for the current collection interval. This primitives uses the smi_stats_get_t structure which contains the smi_primitive as its only member.

SMI_STATS_IND
    Delivers an indication of the aggregated statistics for a collection interval. An attached M_DATA block contains the aggregated statistics for the collection interval. This primitives uses the smi_stats_ind_t struct which contains the following members:

    typedef struct {
        smi_ulong   smi_primitive;  /* SMI_STATS_IND */
        smi_ulong   smi_interval;
        smi_ulong   smi_timestamp;
    } smi_stats_ind_t;

    smi_interval
        The interval for which this indication corresponds (in jiffies). This could normally be 5 minutes, 15 minutes, 30 minutes, 60 minutes.

    smi_timestamp
        The UNIX timestamp (seconds since epoch) corresponding to the beginning of the interval for which statistics have been collected.

ERRORS (see also "ERROR HANDLING")
    Upon success, the layer service provider will return a SMI_OK_ACK to confirm the successful statistics request. The provider attaches a M_DATA block which contians the modname_stats_t structure containing the layer-specific statistics parameters and counts. Upon failure, the layer specific provider will return a SDM_ERROR_ACK to reject the state request. The provider attaches a M_DATA block which contains a modname_stats_t structure with 0xffffffff in any values which are in error. If the layer service provider fails in an attempt to generate a statistics indications, it will instead deliver a SDM_ERROR_IND to indicate the failure to provide the statistics indication. The provider may provide a partial indication using an attached M_DATA block which contains a modname_stats_t structure with 0xffffffff in any values which are in error. Error numbers in smi_errno which are specific to a statistics request rejection and indication failure are as follows:

    SMI_STATSOOM
        Statistic collection has run out of memory.

    SMI_STATSSUS
        Statistics collection is congested and has been temporarily suspended.

    SMI_STATSRES
        Statistics collection congestion has cleared and has been resumed.

  Protocol Events

typedef modname_event {
} modname_event_t;

Protocol management primitives may be delivered by the layer service provider to the stack or layer management to indicate the occurence of a protocol event which is of interest. Any M_DATA block attached to the primitive contains a layer-specific modname_event_t structure (see above) which represents detailed layer-specific event information. Event indications are delivered as low priority M_PROTO, M_EVENT or M_CTL messages. This allows data exchange and configuration to take precedence over event reporting. Event reporting, however takes precedence over statistics reporting.

SMI_EVENT_IND

    typedef struct {
        smi_ulong   smi_primitive;  /* SMI_EVENT_IND */
        smi_utime   smi_timestamp;
        smi_ulong   smi_severity;
        smi_caddr   smi_module_name;
        smi_caddr   smi_clli;
    } modname_event_t;

ERRORS (see also "ERROR HANDLING")

ERROR HANDLING

SMI_OK_ACK
    Upon success, the layer service provider will return a SMI_OK_ACK to confirm a successful request. The provider may attach a M_DATA block which contains a request-specific structure with the results of the request. This primitive uses the smi_ok_ack_t structure as follows:

    typedef struct {
        smi_ulong  smi_primitive; /* SMI_OK_ACK */
        smi_ulong  smi_state;
        smi_ulong  smi_correct_primitive;
    } smi_ok_ack_t;

    smi_state
        Contains the management state of the interface.

    smi_correct_primitive
        Contains the request primitive which this response is acknowledging.

SMI_ERROR_ACK
    Upon failure, the layer service provider will return a SMI_ERROR_ACK to reject the request due to an error. The provider may attach a M_DATA block which contains a request-specific structure which indicates the elements of the request which are in error. This primitive uses the smi_error_ack_t structure as follows:

    typedef struct {
        smi_ulong  smi_primitive; /* SMI_ERROR_ACK */
        smi_ulong  smi_state;
        smi_ulong  smi_error_primitive;
        smi_ulong  smi_errno;
        smi_ulong  smi_reason;
    } smi_error_ack_t;

    smi_state
        Contains the management state of the interface.

    smi_error_primitive
        Contains the request primitive which this response is acknowledging.

    smi_errno
        The error number indicating which error occured.

    smi_reason
        An additional error reason code.

  ERRORS

    Error numbers which are specific to a configuration request rejection are as follows:

    SMI_CONFLOCKED
        The request attempted to perform an illegal operation on a locked configuration.

    SMI_NOCONFDATA
        The request was missing configuration data (i.e. missing M_DATA block or M_DATA block too short.

    SMI_BADCONFDATA
        Some configuration data was invalid. The attached M_DATA block contains 0xffffffff in the data elements which are considered invalid.

SS7 STREAMS INTERFACES
The OpenSS7 stack provides drivers and modules at all levels of the SS7 stack below ISUP and TCAP. That is, it provides SS7 Level 2 (Link), SS7 Level 3 (Network), and SCCP (Signalling Connection Control Part) functionality. These protocol components have been broken into a number of sublevels, starting from the bottom-most, as follows:

sdli(7)
    The Signalling Data Link Interface (SDLI) implements SS7 Level 1 [Q702]. SDLI allows real and emulated transmission channels to be implemented for use under the sdt(8) module. It provides access to the DAEDT and DAEDR functions of the SS7 Signalling Link [Q703]. Header file <sys/sdli.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sdl_eth(8)
        SDL emulation using raw Ethernet (IEEE 802.2/802.3).

    sdl_ip(8)
        SDL emulation using raw Internet Protocol (IP).

    sdl_udp(8)
        SDL emulation using User Datagram Protocol (UDP).

    sdl_tcp(8)
        SDL emulation using Transmission Control Protocol (TCP).

    sdl_rtp(8)
        SDL emulation using Real-Time Transport Protocol (RTP).

    sdl_sctp(8)
        SDL emulation using Strean Control Transport Protocol (SCTP).

sdti(7)
    The Signalling Data Terminal Interface (SDTI) implements partial SS7 Level 2 [Q703]. SDTI allows real and emulated data terminals to be implemented for use under the sl(8) module. It provides access to the AERM, SUERM, EIM, DAEDR and DAEDT functions of the SS7 Signalling Link [Q703]. Header file <sys/sdti.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sdt(8)
        SDT module for use with SDLI compliant streams.

    vsdt(8)
        SDT module for emulating a virtual SDT.

    acb56t(8)
        SDT driver for the SeaLevel ACB56 ISA card.

    m2tp(8)
        SDT driver for the MTP Level 2 Tunneling Protocol (M2TP).

    soip(8)
        SDT driver for SS7 over IP.

sli(7)
    The Signalling Link Interface (SLI) implements complete SS7 Level 2 [Q703]. SLI allows real and emulated signalling links to be implemented for use under the sls(8) module. It provides access to all SS7 Level 2 state machine functions of the SS7 Signalling Link [Q703]. Header file <sys/sli.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sl(8)
        SL module for use with SDTI compliant streams.

    vsl(8)
        SL module for emulating a virual SL.

    acb56l(8)
        SL driver for the SeaLevel ACB56 ISA card.

    m2pa(8)
        SL driver for the MTP Level 2 Peer Adaptation (M2PA).

    m2ua(8)
        SL driver for the MTP Level User Adaptation (M2UA).

slsi(7)
    The Signalling Link Set Interface (SLSI) implements partial SS7 Level 3 [Q704]. SLSI allows real and emulated signalling link sets to be implemented for use under the mtp(8) multipexor. It provides access to SS7 Level 3 Link Set state machine functions of the SS7 Message Transfer Part [Q704]. Header file <sys/slsi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sls(8)
        SLS multiplexor for use with SLI compliant streams.

    vsls(8)
        SLS module for emulating a virtual SLS.

    m3tp(8)
        SLS driver for the MTP Level 3 Tunelling Protocol (M3TP).

mtpi(7)
    The Message Transfer Part Interface (MTPI) implements complete SS7 Level 3 [Q704]. MTPI allows real and virtual signalling points and signalling transfer points to be implemented for use under the sccp(8) and tcap(8) modules. It provides access to all SS7 Level 3 state machines and functions of SS7 Message Transfer Part [Q704]. Header file <sys/mtpi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    mtp(8)
        MTP multiplexor for use with SLSI compliant streams.

    m3pa(8)
        MTP module for the MTP Level 3 Peer Adaptation (M3PA).

    m3ua(8)
        MTP module for the MTP Level 3 User Adaptation (M3UA).

sccpi(7)
    The Signalling Connection Control Part Interface (SCCPI) implements complete SS7 Level 4 [Q711]. SCCPI allows real and virtual subsystems and global title translations to be implemented for use under the tcap(8) module. It provides access to all SS7 Level 4 state machines of the SS7 Signalling Connnection Control Part [Q711]. Header file <sys/sccpi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sccp(8)
        SCCP module for use with MTPI compliant streams.

    sua(8)
        SCCP module for the SCCP User Adaptation (SUA).

isupi(7)
    The Integrated Services Digital Network (ISDN) User Part Interface (ISUPI) implements partial SS7 ISUP [Q767]. ISUPI allows call processing agents to attach to specific PC-PC-CIC ranges in control of trunk groups. It provides some basis low-level ISUP state machines (e.g. Unequipped CIC) of the SS7 ISUP [Q767]. Header file <sys/isupi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    isup(8)
        ISUP module for use with MTPI compliant streams.

    iua(8)
        ISUP module for the ISDN User Adaptation (IUA).

tcapi(7)
    The Transaction Capabilities Application Part Interface (TCAPI) implements partion SS7 TCAP [Q7??]. TCAPI allows transaction processing agents to attach to specific subsystem instances in control of database queries. It provides the TC state machines of the SS7 TCAP [Q???]. Header file <sys/tcapi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    tcap(8)
        TCAP module for use with SCCPI compliant streams.

SEE ALSO
isupi(7), mtpi(7), sccpi(7), sdli(7), sdti(7), sli(7), slsi(7), tcapi(7), acb56l(8), acb56t(8), isup(8), iua(8), m2pa(8), m2tp(8), m2ua(8), m3pa(8), m3tp(8), m3ua(8), mtp(8), sccp(8), sdl_eth(8), sdl_ip(8), sdl_rtp(8), sdl_sctp(8), sdl_tcp(8), sdl_udp(8), sdt(8), sl(8), sls(8), soip(8), ss7d(8), sua(8), tcap(8), vsdt(8), vsl(8), vsls(8)

BUGS
Too many to mention.

AUTHOR

Brian F. G. Bidulock, <bidulock@openss7.org>.

HISTORY
This STREAMS interface for SS7 is an orignal part of the OpenSS7 package.

REFERENCES

[Q702]
    ITU-T Recommendation Q.702 Signalling Data Link

[Q703]
    ITU-T Recommendation Q.703 Signalling Link

[Q704]
    ITU-T Recommendation Q.704 Message Transfer Part

[Q711]
    ITU-T Recommendation Q.711 Signalling Connection Control Part

[Q767]
    ITU-T Recommendation Q.767 Integrated Services Digital Network (ISDN) User Part

[Q77?]
    ITU-T Recommendation Q.77? Transaction Capabilities Application Part

COPYRIGHT NOTICE

Copyright © 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.