SDTI(7)

NAME
sdti - Signalling System No. 7 Signalling Data Terminal (SDT) Interface

SYNOPSIS
#include <ss7/sdti.h>
#include <ss7/sdti_ioctl.h>

fd = open ("/dev/sdt", flags);
ret = ioctl(fd, cmd, ... /* arg */ );

DESCRIPTION
This man page describes the STREAMS interface which is used to configure and exchange data with an SS7 Signalling Data Terminal Interface (SDTI) for all SS7 devices conforming to the OpenSS7 Signalling Data Terminal Interface (SDTI) specification.

  LOCAL MANAGEMENT INTERFACE

SDTI drivers are normally linked using streamio(2) I_PUSH ioctl commands under a Signalling Link (SL) STREAMS module conforming to the Signalling Link Interface (SLI) specification sli(7) such as sl(8), by the SS7 Configuration Daemon ss7d(8). Yet, this interface is available for the purpose of ferry-clip conformance and diagnostic testing of the SS7 Signalling Data Terminal.

SDTI Stype 1 and Style 2 drviers may be configured to autopush the sl(8) module and appear as sli(7) drivers. Not all SS7 drivers need be written to the SDT interface: drivers may be written to the sli(7), slsi(7) and even mtpi(7) interfaces.

SDTI 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 interfae controls local management (STREAMS configuration functions) which are normally used by the SS7 Configuration Daemon ss7d(8) on the driver interface before pushing an sl(8) module onto the stream head.

The Local Management Interface (LMI) is common to all OpenSS7 drivers and modules and is described in detail in lmi(7).

  DEVICE CONTROL INTERFACE

SDTI provides a device control interface which utilizes ioctl(2) transparent calls or an I_STR ioctl under streamio(2) from a stream head to the driver. The device control interface controls aspects of the SDT driver device which are outside the scope of the SS7 protocol. These controls are normally issued by the SS7 Configuration Daemon ss7d(8) on the driver interface or multiplexor control channel before or after the protocol stack has been assembled.

The device control interface (DEVI) is common to all OpenSS7 drivers and modules and is described in detail in devi(7).

  PROTOCOL SERVICE INTERFACE

SDTI provides a protocol service interface which uses M_DATA, M_PROTO and M_PCPROTO STREAMS messages which can be exchanged with write(2), read(2), putmsg(2) or getmsg(2) system calls on the stream head, or which can be exchanged with the driver by upstream pushed or linked modules. The protocol service interface exchanges SS7 protocol service primitives between the Signalling Link (SL) and the Signalling Data Terminal (SDT), but may also be used for ferry-clip conformance testing or diagnostics.

The protocol service interface for SDTI is described in detail in section PROTOCOL SERVICE INTERFACE, below.

  PROTOCOL MANAGEMENT INTERFACE

SDTI provides a protocol mangement interface which uses M_CTL messages between modules or M_IOCTL messages from a stream head. This interface uses the controls defined in the Local Management Interface (LMI) as detailed under INPUT OUTPUT CONTROL INTERFACE in lmi(7). The protocol management interface provides protocol configuration, state inquiry, statistics and event management (SNMP functions). This interface is normally used by the SS7 Configuration Daemon ss7d(8) on the stream after opening or during operation.

The protocol service interface for SDTI is described in detail in section PROTOCOL MANAGEMENT INTERFACE below.

PROTOCOL SERVICE INTERFACE

Protocol service interface commands are from the stream head to the SDT driver using putmsg(2) and getmsg(2) commands as follows:
    fd = open("/dev/sdt");
    ret = putmsg(fd, ctlptr, dataptr, flags);
    ret = getmsg(fd, ctlptr, dataptr, flags);

Downstream messages are sent from the stream head using putmsg(2); upstream messages are received at the stream head using getmsg(2).

flags is either RS_HIPRI or not indicating a M_PCPROTO or an M_PROTO message respectively. ctlptr and dataptr are pointers to a strbuf structure which contains the following members:
    struct strbuf {
        int     maxlen;     /* not used       */
        int     len;        /* length of data */
        void    *buf;       /* ptr to buffer  */
    };

buf contains a pointer to a SDT_primitive union which contains one of the following primitives and structures:

  Downstream Primitives

Downstream primitives are sent from the stream head to the protocol state machines using putmsg(2) system calls as described above. Except where otherwise noted, buf contains only the sdt_primitive field which is set to the value of the primitive.

SDT_DAEDT_TRANSMISSION_REQ
    Transmit data. This primitive must be sent with an accompanying M_DATA block which is pointed to by the dataptr in a putmsg(2) or is the buffer which is the argument of a write(2) on the stream file descriptor.

SDT_DAEDT_START_REQ
    Start the DAEDT state machine.

SDT_DAEDR_START_REQ
    Start the DAEDR state machine.

SDT_AERM_START_REQ
    Start the AERM state machine.

SDT_AERM_STOP_REQ
    Stop the AERM state machine.

SDT_AERM_SET_TI_TO_TIN_REQ
    Set the AERM proving period to normal proving.

SDT_AERM_SET_TI_TO_TIE_REQ
    Set the AERM proving period to emergency proving.

SDT_SUERM_START_REQ
    Start the SUERM state machine.

SDT_SUERM_STOP_REQ
    Stop the SUERM state machine.

  Upstream Primitives
Upstream primitives are collected at the stream head from the protocol state machines using getmsg(2) system calls as described above. Except where otherwise noted, buf contains only the sdt_primitive field which is set to the value of the primitive.

SDT_RC_SIGNAL_UNIT_IND
    Receive data. This primitive is received with an accompanying M_DATA block which is pointed to by the dataptr in a getmsg(2) or is the buffer which is returned from a read(2) on the stream file descriptor.

SDT_RC_CONGESTION_ACCEPT_IND
    Congestion accept indication.

SDT_RC_CONGESTION_DISCARD_IND
    Congestion discard indication.

SDT_RC_NO_CONGESTION_IND
    Congestion ceases indication.

SDT_IAC_CORRECT_SU_IND
    Correct Signal Unit received indication.

SDT_IAC_ABORT_PROVING_IND
    Proving aborted indication.

SDT_LSC_LINK_FAILURE_IND
    Link failure indication.

PROTOCOL MANAGEMENT INTERFACE

Protocol management interface comands are from the stream head to the SDT driver using streamio(8) I_STR commands as follows:
    fd = open("/dev/sdt");
    ret = ioctl(fd, I_STR, arg);

Where arg is a pointer to a strioctl structure which contains the following members:

    struct strioctl {
        int     ic_cmd;
        int     ic_timout;
        int     ic_len;
        char    *ic_dp;
    };

ic_cmd can be one of the protocol management interface commands described in the following subsections:

  Protocol Options

Protocol management controls which affect protocol options are used by local management to set protocol variants and protocol options inherent to the SDT provider.

The ic_cmd contains one of the following options commands:

SDT_IOCGOPTIONS
    Gets the protocol variant pvar and protocol options popt assigned to the Signalling Data Terminal into the provided lmi_option structure.

SDT_IOCSOPTIONS
    Sets the protocol variant pvar and protocol options popt to the Signalling Data Terminal as provided in the lmi_option structure.

ic_dp points to a lmi_option structure which represents the protocol variant and options parameters as follows:

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

    pvar
        Specifies the protocol variant to be used for the Signalling Data Terminal and may be one of the following values:

        SS7_PVAR_ITUT_88 | ITU-T Q.703 1988 (Blue Book)
        SS7_PVAR_ITUT_93 | ITU-T Q.703 1993 (Grey Book)
        SS7_PVAR_ITUT_96 | ITU-T Q.703 1996 (White Book)
        SS7_PVAR_ITUT_00 | ITU-T Q.703 2000 (? Book)
        SS7_PVAR_ANSI_88 | ANSI T1.113-1988
        SS7_PVAR_ANSI_92 | ANSI T1.113-1992
        SS7_PVAR_ANSI_96 | ANSI T1.113-1996
        SS7_PVAR_ANSI_00 | ANSI T1.113-2000
        SS7_PVAR_ETSI_88 | ETSI 300 008-1 1988
        SS7_PVAR_ETSI_93 | ETSI 300 008-1 1993
        SS7_PVAR_ETSI_96 | ETSI 300 008-1 1996
        SS7_PVAR_ETSI_00 | ETSI 300 008-1 2000
        SS7_PVAR_JTTC_94 | JTTC JQ.703 1994

    popt
        Specifies the protocol options to be used for the Signalling Data Terminal and may be a bitwise OR of any of the following values:

        SS7_POPT_MPLEV | Multi Priority/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

  Protocol Configuration

Protocol management controls which affect protocol configuration are invoked by local management to configure or request configuration information from the SDT provider.

The ic_cmd contains one of the following configuration commands:

SDT_IOCGCONFIG
    Gets the protocol configuration of the Signalling Data Terminal into the provided sdt_config structure.

SDT_IOCSCONFIG
    Sets the protocol configuration of the Signalling Data Terminal from the provided sdt_config structure.

SDT_IOCTCONFIG
    Tests the protocol configuration as provided in the sdt_config structure against the Signalling Data Terminal for consistency and validity. Also locks the configuration of the SDT provider awaiting a commit.

SDT_IOCCCONFIG
    Commits the protocol configuration as provided in the sdt_config structure to the Signalling Data Terminal. Also unlocks the configuration of the SDT provider.

ic_dp points to a sdt_config structure which represents the Signalling Data Terminal protocol configuration as follows:

    typedef struct sdt_config {
        sdt_ulong   t8;  /* T8 timeout                       */
        sdt_ulong   Tin; /* AERM normal proving threshold    */
        sdt_ulong   Tie; /* AERM emergency proving threshold */
        sdt_ulong   T;   /* SUERM error threshold            */
        sdt_ulong   D;   /* SUERM error rate parameter       */
        sdt_ulong   Te;  /* EIM error threshold              */
        sdt_ulong   De;  /* EIM correct decrement            */
        sdt_ulong   Ue;  /* EIM error increment              */
    } sdt_config_t;

    t8  Contains the T8 timeout value (in jiffies) for the T8 timer used with the optional Errored Interval Monitor (EIM) procedure of ITU-T Q.703 Annex A.

    Tin Contains the T4 timeout value (in jiffies) for the normal proving period.

    Tie Contains the T4 timeout value (in jiffies) for the emergency proving period.

    T   Contains the Signal Unit Error Rate Monitor (SUERM) threshold value.

    D   Contains the Signal Unit Error Rate Monitor (SUERM) downcount value.

    Te  Contains the threshold value for use with the Errored Interval Monitor (EIM) procedure of ITU-T Q.703 Annex A.

    De  Contains the downcount value for use with the Errored Interval Monitor (EIM) procedure of ITU-T Q.703 Annex A.

    Ue  Contains the upcount value for use with the Errored Interval Monitor (EIM) procedure of ITU-T Q.703 Annex A.

  Protocol State

Protocol management controls which affect protocol state are invoked by local management to request information about the state of the protocol state machines in the SDT provider.

The ic_cmd contains one of the following state commands:

SDT_IOCGSTATEM
    Gets the protocol state machine variables of the Signalling Data Terminal into the provided sdt_statem structure.

SDT_IOCCMRESET
    Performs a master reset on the protocol state machines and returns the power-on settings of the state machine variables of the Signalling Data Terminal into the provided sdt_statem structure.

ic_dp points to a sdt_statem structure which represents the Signalling Data Terminal protocol state as follows:

    typedef struct sdt_statem {
        sdt_ulong aerm_state;           /* AERM  state variable      */
        sdt_ulong   aborted_proving;    /* AERM  aborted proving     */
        sdt_long    Ca;                 /* AERM  error counter       */
        sdt_ulong   Ti;                 /* AERM  threshold           */
        sdt_ulong suerm_state;          /* SUERM state variable      */
        sdt_long    Cs;                 /* SUERM error counter       */
        sdt_ulong   Ns;                 /* SUERM su counter          */
        sdt_ulong eim_state;            /* EIM   state variable      */
        sdt_long    Ce;                 /* EIM   counter             */
        sdt_ulong   su_received;        /* EIM   su received flag    */
        sdt_ulong   interval_error;     /* EIM   interval error flag */
        sdt_ulong daedt_state;          /* DAEDT state variable      */
        sdt_ulong daedr_state;          /* DAEDR state variable      */
        sdt_ulong   octet_counting_mode;/* receivers freewheeling    */
    } sdt_statem_t;

    aerm_state, aborted_proving, Ca, Ti
        Contains the Alignment Error Rate Monitor (AERM) current state aerm_state; a flag indicating whether proving has been aborted aborted_proving; the current AERM count Ca, and current AERM threshold Ti.

    suerm_state, Cs, Ns
        Contains the Signal Unit Error Rate Monitor (SUERM) current state suerm_state; the current SUERM count Cs, and the number of errored periods Ns.

    eim_state, Ce, su_received, interval_error
        Contains the Errored Interval Monitor (EIM) current state eim_state; the current EIM count Ce, a flag indicating whether a Signal Unit was received in the current interval su_received; and a flag indicating whether an error occured in the current interval interval_error.

    daedt_state
        Contains the Delimitation Alignment and Error Detection Transmit (DAEDT) current state.

    deadr_state, octet_counting_mode
        Contains the Delimitation Alignment and Error Detection Receiving (DAEDR) current state; and a flag indicating whether the DAEDR is in octet counting mode octet_counting_mode.

  Protocol Data Collection

Protocol management controls which affect protocol measurement data collection are invoked by local management to request and alter collection periods for data collection within the SDT provider.

ic_cmd contains one of the following collection commands:

SDT_IOCGSTATSP
    Get the protocol measurement collection period information of the identified object_id into the provided lmi_sta structure.

SDT_IOCSSTATSP
    Set the protocol measurement collection period information of the identified object_id using the provided lmi_sta structure.

ic_dp points to a lmi_sta structure which represnts the Signalling Data Terminal collection periods 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 idenitfier for the managed object to which the collection information applies.

    colperiod
        Contains the collection period (in jiffies). The managed object measurement data must be collected and notified once for each collection period interval.

    timestamp
        Contains a timestamp (in seconds since epoch) which identifies the system time at which a collection period ends. This value is used in conjunction with the collection period to calculate the time of the next collection interval.

  Protocol Statistics

Protocol management controls which affect protocol statistics are invoked by local management to request information about statistics pertaining to the SDT provider.

ic_cmd contains one of the following statistics commands:

SDT_IOCGSTATS
    Get the protocol statistics of the Signalling Data Terminal for the current collection period into the provided sdt_stats structure.

SDT_IOCCSTATS
    Clear the protocol statisics of the Signalling Data Terminal for the current collection period and return the statistics which were accumulated to the point of clearing during the current interval sdt_stats structure.

ic_dp points to a sdt_stats structure which represents the Signalling Data Terminal protocol statistics as follows:

    typedef struct sdt_stats {
        lmi_sta_t   header;
        sdt_ulong   tx_bytes;
        sdt_ulong   tx_sus;
        sdt_ulong   tx_underruns;
        sdt_ulong   tx_aborts;
        sdt_ulong   tx_buffer_overflows;
        sdt_ulong   tx_sus_in_error;
        sdt_ulong   rx_bytes;
        sdt_ulong   rx_sus;
        sdt_ulong   rx_overruns;
        sdt_ulong   rx_aborts;
        sdt_ulong   rx_buffer_overflows;
        sdt_ulong   rx_sus_in_error;
        sdt_ulong   rx_sync_transitions;
        sdt_ulong   rx_bits_octet_counted;
        sdt_ulong   rx_crc_errors;
        sdt_ulong   rx_frame_errors;
        sdt_ulong   rx_frame_overflows;
        sdt_ulong   rx_frame_too_long;
        sdt_ulong   rx_frame_too_short;
        sdt_ulong   rx_residue_errors;
        sdt_ulong   carrier_cts_lost;
        sdt_ulong   carrier_dcd_lost;
        sdt_ulong   carrier_lost;
    } sdt_stats_t;

    header
        Contains the timestamp for the current collection interval for which statistics are being reported.

    tx_bytes, tx_sus, tx_underruns, tx_aborts, tx_buffer_overflows, tx_sus_in_error
        Contains transmitter statistics for the current collection interval.

    rx_bytes, rx_sus, rx_overruns, rx_aborts, rx_buffer_overflows, rx_sus_in_error, rx_sync_transitions, rx_bits_octet_counted, rx_crc_errors, rx_frame_errors, rx_frame_overflow, rx_frame_too_long, rx_frame_too_short, rx_residue_errors
        Contains receiver statistics for the current collection interval.

    carrier_cts_lost, carrier_dcd_lost, carrier_lost
        Contains interface statistics for the current collection interval.

  Protocol Events

Protocol management controls which affect notification of events to local management are invoked by local management to request information about notifications which have been requested as well as to set notification by event.

The ic_cmd contians one of the following notify commands:

SDT_IOCGNOTIFY
    Gets the protocol notification bitmask of the Signalling Data Terminal into the provided sdt_notify structure.

SDT_IOCSNOTIFY
    Sets protocol notification for the Signalling Data Terminal events identified by set bits in the provided sdt_notify structure.

SDT_IOCCNOTIFY
    Clears protocol notification for the Signalling Data Terminal events identified by set bits in the provided sdt_notify structure.

ic_dp points to a sdt_notify structure which represents the Signalling Data Terminal protocol event notifications as follows:

    typedef struct sdt_notify {
        sdt_ulong   sdt_mask;
    } sdt_notify_t;

    sdt_mask
        Contains a bit mask with bits set for each Signalling Data Terminal event for which notification has been requested. May also contain set bits for events for which notification should be set (SDT_IOCSNOTIFY) or cleared (SDT_IOCCNOTIFY). The mask is the bitwise OR of any of the following values:

        SDT_EVT_TX_FAIL | Transmitter failure.
        SDT_EVT_RX_FAIL | Receiver failure.
        SDT_EVT_CARRIER | Carrier failure.

SEE ALSO

devi(7), getmsg(2), ioctl(2), lmi(7), mtpi(7), putmsg(2), read(2), sdli(7), sl(8), sl(8), sli(7), slsi(7), ss7d(8), streamio(2), write(2)

BUGS

Too many to mention.

AUTHOR

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

HISTORY

This STREAMS interface for SS7 is an original 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

COPYRIGHT NOTICE

Copyright © 1997-2001 Brian Bidulock. All Rights Reserved.

PERMISSION NOTICE

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 copyring, 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 damage 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.