LMI(7)

NAME
lmi - Signalling System No. 7 - Local Management Interface (LMI)

SYNOPSIS
#include <ss7/lmi.h>
#include <ss7/lmi_ioctl.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 Local Management Interface (LMI) specification. LMI 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 for LMI management. The LMI consists of two subcomponents:

LOCAL MANAGEMENT INTERFACE
    LMI provides a local management interface which utilizes M_PROTO and M_PCPROTO messages which can be exchanged with the interface using putmsg(2) and getmsg(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 ss7d(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".

PROTOCOL MANAGEMENT INTERFACE
    LMI provides a protocol 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
    LMI 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.

LOCAL MANAGEMENT INTERFACE

  PPA STYLE

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:

LMI_STYLE1
    A Style 1 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 LMI_ATTACH_REQ, but still require the primitive to move the interface from the LMI_UNATTACHED state to the LMI_DISABLED state. Style 1 drivers do not require PPA addresses.

LMI_STYLE2
    A Style 2 driver is a driver whose Point of Physical Appearance (PPA) must be attached to the stream after open. These drivers open in the LMI_UNATTACHED state and must be attached with a LMI_ATTACH_REQ local management primitive to associate them with a PPA before they can be enabled for use. Style 2 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.

  LOCAL MANAGEMENT STATES

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.

The management states of the LMI provider are as follows:

LMI_UNATTACHED
    The LMI driver or module is not attached to a PPA. This state is only meaningful to Style 2 drivers which must be explicitly attached to a specific transmission channel. Both Stype 1 and Style 2 drivers open in this state.

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.

LMI_DISABLED
    The LMI driver or module is attached but has not yet been enabled for use. The driver must be enabled with a LMI_ENABLE_REQ local management primitive before data or protocol primtives may be exchanged with the driver or module.

LMI_ENABLE_PENDING
    The LMI driver or module has accepted a LMI_ENABLE_REQ 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 LMI_ENABLE_CON confirmation once the enabling is successful, or a LMI_ERROR_ACK if unsuccessful. Most drivers use the LMI_ENABLE_REQ 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.

LMI_ENABLED
    The LMI driver or module is enabled and ready for use (to provide protocol services).

LMI_DISABLE_PENDING
    The LMI driver or module has accepted a LMI_DISABLE_REQ 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 LMI_DISABLE_CON confirmation once the disabling is successful, or a LMI_ERROR_ACK if unsuccessful. Most drivers use the LMI_DISABLE_REQ 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.

  LOCAL MANAGEMENT PRIMITIVES

Local management primitives can be exchanged with the device driver as M_PROTO or M_PCPROTO primitives using the putmsg(2) or getmsg(2) system calls on the stream head after opening the device. This interface is normally used only by the SS7 Configuration Daemon ss7d(8) during STREAMS configuration, or by the upstream protocol modules during streamio(7) I_PUSH and I_POP 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.

Only M_PROTO local management primitives will be deferred during congestion or overload of the driver or module. Local management primitives sent as M_PCPROTO will be discarded and return a LMI_ERROR_ACK in repsonse should it not be possible to execute them immediately.

Local management primitives provided by the LMI are as follows:

LMI_INFO_REQ, LMI_INFO_ACK, LMI_ERROR_ACK

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 ss7d(8) on the stream head.

LMI_INFO_REQ
    LMI_INFO_REQ uses a lmi_info_req_t structure which contains the request primitive, lmi_primitive, as its only member

LMI_INFO_ACK
    LMI_INFO_ACK uses lmi_info_ack_t structure as follows:

    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;

    lmi_primitive
        The primitive number which is set to LMI_INFO_ACK.

    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 1.0.0.0 or 0x10000000.

    lmi_state
        The current local management state of the LMI interface.

    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.

    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 0xffffffff.

    lmi_ppa_style
        The style of the driver which may be one of the following:

        LMI_STYLE1
            A Style 1 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 LMI_ATTACH_REQ.

        LMI_STYLE2
            A Style 2 device which is explicitly associated with a transmission channel identified by a lmi_ppa_addr in an LMI_ATTACH_REQ local management primitive after opening. These devices open in the LMI_UNATTACHED state.

    lmi_ppa_addr
        The PPA address that a Style 2 device is attached to. If the device is a Style 1 device or an unattached Style 2 device, this member will return all zeros.

LMI_ERROR_ACK
    LMI_ERROR_ACK containing the error number in lmi_errno and an error explanation in lmi_reason will be returned by the LMI provider in the rare event that an error occurs while attempting to retreive the information requested by a LMI_INFO_REQ.

LMI_ATTACH_REQ, LMI_OK_ACK, LMI_ERROR_ACK

Invoked by the LMI user to attach a Style 2 LMI driver or module to a PPA using a PPA Address. This primitive is normally used by the SS7 Configuration Daemon ss7d(8) when assembling the SS7 protocol stack. The PPA address is obtained by the daemon from configuration files.

LMI_ATTACH_REQ
    Request that the LMI driver or module attach to the PPA address specified in the request. The LMI_ATTACH_REQ primitive is only valid from the LMI_UNATTACHED state for a Style 1 or Style 2 interface. LMI_ATTACH_REQ uses the lmi_attach_req_t structure as follows:

    typedef struct {
        lmi_ulong   lmi_primitive;  /* LMI_ATTACH_REQ */
        lmi_ulong   lmi_ppa[0];
    } lmi_attach_req_t;

    lmi_primitive
        The primitive number which is set to LMI_ATTACH_REQ.

    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.

LMI_OK_ACK
    Returned if the attach request is successful.

LMI_ERROR_ACK
    Returned with the error number and explanation set if the attach request fails.

LMI_DETACH_REQ, LMI_OK_ACK, LMI_ERROR_ACK

Invoked by the LMI user to detach a Style 2 LMI driver from its PPA. This primitive is normally used by the SS7 Configuration Daemon ss7d(8) when disassembling or reconfiguring the SS7 protocol stack.

LMI_DETACH_REQ
    Requests that the LMI driver detach itself from the current attached PPA. LMI_DETACH_REQ is only valid for Style 1 or Style 2 drivers in the LMI_DISABLED state. The LMI_DETACH_REQ uses the lmi_detach_req_t structure which contains only the lmi_primitive which is set to LMI_DETACH_REQ.

LMI_OK_ACK
    Returned if the detach request was successful.

LMI_ERROR_ACK
    Returned with the error number and explanation set if the detach request fails.

LMI_ENABLE_REQ, LMI_ENABLE_CON, LMI_ERROR_ACK

Invoked by the LMI on a Style 1 or Style 2 LMI provider to enable it for data transfer and protocol operations. This primitive is normaly used by the SS7 Configuration Daemon ss7d(8) when enabling an assembled or reconfigured SS7 protocol stack.

LMI_ENABLE_REQ
    Requests that the LMI provider enable itself for data transfer and protocol operations. LMI_ENABLE_REQ is valid for both Style 1 and Style 2 LMI providers in the LMI_DISABLED state. The LMI_ENABLE_REQ uses the lmi_enable_req_t structure which contains only the lmi_primitive which is set to LMI_ENABLE_REQ.

LMI_ENABLE_CON
    Returned once the enable request is successful. For some Style 2 LMI providers, this may take some time and is not necessarily returned in immediate response to the enable request.

LMI_ERROR_ACK
    Returned with the error number and explanation set if the enable request fails.

LMI_DISABLE_REQ, LMI_DISABLE_CON, LMI_ERROR_ACK

Invoked by the LMI user on a Style 1 or Style 2 LMI provider to disable the provider from further data transfer and protocol operations. This primitive is normally used by the SS7 Configuration Daemon ss7d(8) when disabling an SS7 protocol stack for disassembly or reconfiguration.

LMI_DISABLE_REQ
    Requests that the LMI provider disable itself from further data transfer and protocol operations. LMI_DISABLE_REQ is valid for both Style 1 and Style 2 LMI providers in the LMI_ENABLED state. The LMI_DISABLE_REQ uses the lmi_disable_req_t structure which contains only the lmi_primitive which is set to LMI_DISABLE_REQ.

LMI_DISABLE_CON
    Returned once the disable request is successful. For some Style 2 LMI providers, this may take some time and is not necessarily returned in immediate response to the disable request.

LMI_ERROR_ACK
    Returned with the error number and explanation set if the disable request fails.

  ERROR HANDLING

LMI_OK_ACK
    Upon success, the layer service provider will return a LMI_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; /* LMI_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.

LMI_ERROR_ACK
    Upon failure, the layer service provider will return a LMI_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; /* LMI_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. This error number corresponds to the Unix errno (see strerror(2)) if applicable.

    smi_reason
        An additional error reason code.

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

    LMI_UNSPEC | Unknown or unspecified
    LMI_BADADDRESS | Address was invalid
    LMI_BADADDRTYPE | Invalid address type
    LMI_BADDIAL | (not used)
    LMI_BADDIALTYPE | (not used)
    LMI_BADDISPOSAL | Invalid disposal parameter
    LMI_BADFRAME | Defective SDU received
    LMI_BADPPA | Invalid PPA identifier
    LMI_BADPRIM | Unregognized primitive
    LMI_DISC | Disconnected
    LMI_EVENT | Protocol-specific event ocurred
    LMI_FATALERR | Device has become unusable
    LMI_INITFAILED | Link initialization failed
    LMI_NOTSUPP | Primitive not supported by this device
    LMI_OUTSTATE | Primitive was issued from invalid state
    LMI_PROTOSHORT | M_PROTO block too short
    LMI_SYSERR | UNIX system error
    LMI_WRITEFAIL | Unitdata request failed
    LMI_CRCERR | CRC or FCS error
    LMI_DLE_EOT | DLE EOT detected
    LMI_FORMAT | Format error detected
    LMI_HDLC_ABORT | Aborted frame detected
    LMI_OVERRUN | Input overrun
    LMI_TOOSHORT | Frame too short
    LMI_INCOMPLETE | Partial frame received
    LMI_BUSY | Telephone was busy
    LMI_NOANSWER | Connection went unanswered
    LMI_CALLREJECT | Connection rejected
    LMI_HDLC_IDLE | HDLC line went idle
    LMI_HDLC_NOTIDLE | HDLC link no longer idle
    LMI_QUIESCENT | Line being reassigned
    LMI_RESUMED | Line has been reassigned
    LMI_DSRTIMEOUT | Did not see DSR in time
    LMI_LAN_COLLISIONS | LAN excessive collisions
    LMI_LAN_REFUSED | LAN message refused
    LMI_LAN_NOSTATION | LAN no such station
    LMI_LOSTCTS | Lost Clear to Send signal
    LMI_DEVERR | Start of device-specific error codes

INPUT OUTPUT CONTROL INTERFACE

All device drivers or modules which provide a Local Management Interface (LMI) provide a set of IOCTLs which are used to configure and change the characteristics of the operation of the driver or module. Each driver or module named xxx provides IOCTLs of the form xxx_IOCfunction. For the particulars of datastructures and specific control commands see the xxx man page (e.g, sdli(7)) for the xxx protocol level driver. Controls which should be provided by all drivers are as follows:

xxx_IOCGOPTIONS, xxx_IOCSOPTIONS
    Used to get or set the options associated with the protocol for a specific LMI driver. The two common fields for all protocol drivers and modules are contained in the lmi_option_t structure as follows:

    typedef struct lmi_option {
        lmi_ulong   pvar;
        lmi_ulong   popt;
    } lmi_option_t;

    pvar
        Contains a protocol variant number which defaults to SS7_PVAR_ITUT_88. The protocol variant number is one of the following values:

        SS7_PVAR_ITUT_88 | ITU-T 1988 (Blue Book)
        SS7_PVAR_ITUT_93 | ITU-T 1993 (White Book)
        SS7_PVAR_ITUT_96 | ITU-T 1996 (Grey Book)
        SS7_PVAR_ITUT_00 | ITU-T 2000 (? Book)
        SS7_PVAR_ANSI_88 | ANSI T1.111-1988
        SS7_PVAR_ANSI_92 | ANSI T1.111-1992
        SS7_PVAR_ETSI_88 | ETSI ETS 300 008 1988
        SS7_PVAR_ETSI_93 | ETSI ETS 300 008 1993
        SS7_PVAR_ETSI_96 | ETSI ETS 300 008 1996
        SS7_PVAR_ETSI_00 | ETSI ETS 300 008 2000
        SS7_PVAR_JTTC_94 | JTTC JQ.700-Series 1994

    popt
        Contains a bit vector which contains a bitwise OR of the following flags. When the resepective bit is set it indicates that the option is in effect.

        SS7_POPT_MPLEV | Multiple prio/cong levels
        SS7_POPT_PCR | Preventative cyclic retrans
        SS7_POPT_HSL | High speed links
        SS7_POPT_XSN | Extended sequence numbers
        SS7_POPT_ALL | All options

xxx_IOCGCONFIG, xxx_IOCSCONFIG
    Used to get or set the configuration variables associated with the protocol for a specific LMI driver or module. There are no common configuration fields. See the specific driver man page for details.

xxx_IOCTCONFIG, xxx_IOCCCONFIG
    Used to test and commit a configuration using SNMP setup/commit semantics for a specific LMI driver or module. There are no common configuration fields. See the specific driver man page for details.

xxx_IOCGSTATEM
    Get state machine state variables, flags, timer-values and other protocol state machine attributes for a particular protocol driver or module. There are no common state machine fields. See the specific driver man page for details.

xxx_IOCCMRESET
    Perform a master reset on the state machine. This returns the state machine to Power-On conditions. This control returns the same information as a xxx_IOCGSTATEM call. There are no common state machine fields. See the specific driver man page for details.

xxx_IOCGSTATSP, xxx_IOCSSTATSP
    Used to get or set the statistics collection interval for the collection of statistics from the LMI driver or module. The three common fields form a common header for all statistics period information and are contains in the lmi_sta_t structure as follows:

    typedef struct lmi_sta {
        lmi_ulong   object_id;  /* object id for stats      */
        lmi_ulong   colperiod;  /* collection period        */
        lmi_ulong   timestamp;  /* timestamp end of period  */
    } lmi_sta_t;

    object_id
        Contains the object id of the statistics.

    colperiod
        Contains the collection period which is being set for specified statistics. The collection period is in jiffies (1/HZ seconds) and indicates the aggregation period for specified statistics.

    timestamp
        Contains a timestamp (secconds since epoch) which indicates the time boundary at which at least on collection period occured in the past. This value can be used to determine the system clock time at which the next collection interval is to occur.

xxx_IOCGSTATS, xxx_IOCSSTATS
    Gets or sets statistics which have been collected for the LMI driver or module in the current (or just previous but not notified) collection interval. The common field of all statistics structures is the header field which contains the timestamp of the collection interval for which the current statistics apply.

xxx_IOCGNOTIFY, xxx_IOCSNOTIFY, xxx_IOCCNOTIFY
    Gets, sets or clears notifications from the LMI driver or module. There are no common notification fileds. See the specific driver man page for more details.

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 Rec. Q.702 Signalling Data Link
[Q703] | ITU-T Rec. Q.703 Signalling Link
[Q704] | ITU-T Rec. Q.704 Message Transfer Part
[Q711] | ITU-T Rec. Q.711 Signalling Connection Control Part
[Q767] | ITU-T Rec. Q.767 ISDN User Part
[Q77?] | ITU-T Rec. Q.77? Transaction Capabilities Appl. 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.