SDLI(7)

NAME
sdli - Signalling System No. 7 Signalling Data Link (SDL) Interface

SYNOPSIS
#include <ss7/sdli.h>
#include <ss7/sdli_ioctl.h>

fd = open ("/dev/sdl", 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 Link Interface (SDLI) for all SS7 devices conforming to the OpenSS7 Signalling Data Link Interface (SDLI) specification.

  LOCAL MANAGEMENT INTERFACE

SDLI drivers are normally linked using streamio(2) I_PUSH ioctl commands under a Signalling Data Terminal (SDT) STREAMS module conforming to the Signalling Data Terminal Interface (SDTI) specification sdti(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 Link.

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

SDLI 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

SDLI 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 SDL 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

SDLI 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 Data Terminal (SDT) and the Signalling Data Link (SDL), but may also be used for ferry-clip conformance testing or diagnostics.

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

  PROTOCOL MANAGEMENT INTERFACE

SDLI 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 SDLI is described in detail in section PROTOCOL MANAGEMENT INTERFACE below.

PROTOCOL SERVICE INTERFACE

Protocol service interface commands are from the stream head to the SDL driver using putmsg(2) and getmsg(2) commands as follows:
    fd = open("/dev/sdl");
    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 SDL_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 sdl_primitive field which is set to the value of the primitive.

SDL_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.

SDL_DAEDT_START_REQ
    Start the DAEDT state machine.

SDL_DAEDR_START_REQ
    Start the DAEDR 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 sdl_primitive field which is set to the value of the primitive.

SDL_DAEDR_RECEIVED_BITS_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. This primitive indicates additional information in the sdl_daedr_received_bits_ind_t structure as follows:

    typedef struct {
        sdl_ulong   sdl_primitive;  /* SDL_DAEDR_RECEIVED_BITS_IND */
        sdl_ulong   sdl_count;
    } sdl_daedr_received_bits_ind_t;

    sdl_primitive
        Contains the primitive which is set to SDL_DAEDR_RECEIVED_BITS_IND.

    sdl_count
        Contains the count of the number of consecutive times that this signal unit was received since the last indication.

SDL_DAEDR_CORRECT_SU_IND
    Correct Signal Unit received indication. This primitive indicates additional information in the sdl_daedr_correct_su_ind_t structure as follows:

    typedef struct {
        sdl_ulong   sdl_primitive;  /* SDL_DAEDR_CORRECT_SU_IND */
        sdl_ulong   sdl_count;
    } sdl_daedr_correct_su_ind_t;

    sdl_primitive
        Contains the primitive which is set to SDL_DAEDR_CORRECT_SU_IND.

    sdl_count
        Contains the count of the number of correct signal units received since the last indication.

SDL_DAEDR_SU_IN_ERROR_IND
    Signal Unit received in error indication.

PROTOCOL MANAGEMENT INTERFACE

Protocol management interface comands are from the stream head to the SDL driver using streamio(8) I_STR commands as follows:
    fd = open("/dev/sdl");
    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 SDL provider.

The ic_cmd contains one of the following options commands:

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

SDL_IOCSOPTIONS
    Sets the protocol variant pvar and protocol options popt to the Signalling Data Link 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 Link 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 Link 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 SDL provider.

The ic_cmd contains one of the following configuration commands:

SDL_IOCGCONFIG
    Gets the protocol configuration of the Signalling Data Link into the provided sdl_config structure.

SDL_IOCSCONFIG
    Sets the protocol configuration of the Signalling Data Link from the provided sdl_config structure.

SDL_IOCTCONFIG
    Tests the protocol configuration as provided in the sdl_config structure against the Signalling Data Link for consistency and validity. Also locks the configuration of the SDL provider awaiting a commit.

SDL_IOCCCONFIG
    Commits the protocol configuration as provided in the sdl_config structure to the Signalling Data Link. Also unlocks the configuration of the SDL provider.

ic_dp points to a sdl_config structure which represents the Signalling Data Link protocol configuration as follows:

    typedef struct sdl_config {
        sdl_ulong   N; /* octets per su in OCM */
        sdl_ulong   m; /* maximum SIF size     */
    } sdl_config_t;

    N   Contains the number of octets which are considered an SU during octet-counting mode.

    m   Contains the maximum SIF size in octets for the link. This is normally set to 272. 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 SDL provider.

The ic_cmd contains one of the following state commands:

SDL_IOCGSTATEM
    Gets the protocol state machine variables of the Signalling Data Link into the provided sdl_statem structure.

SDL_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 Link into the provided sdl_statem structure.

ic_dp points to a sdl_statem structure which represents the Signalling Data Link protocol state as follows:

    typedef struct sdl_statem {
        sdl_ulong   daedt_state;
        sdl_ulong   daedr_state;
        sdl_ulong   octet_counting_mode;
    } sdl_statem_t;

    daedt_state
        Contains the Delimitation Alignment and Error Detection for the Transmit side (DAEDT) current state. This state is either 0 for idle, or non-zero for active.

    daedr_state
        Contains the Delimitation Alignment and Error Detection for the Receive side (DAEDR) current state. This state is either 0 for idle, or non-zero for active.

    octet_counting_mode
        Contains a flag which indicates whether the receiver is in octet counting mode or not.

  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 SDL provider.

ic_cmd contains one of the following collection commands:

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

SDL_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 Link 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 SDL provider.

ic_cmd contains one of the following statistics commands:

SDL_IOCGSTATS
    Get the protocol statistics of the Signalling Data Link for the current collection period into the provided sdl_stats structure.

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

ic_dp points to a sdl_stats structure which represents the Signalling Data Link protocol statistics as follows:

    typedef struct sdl_stats {
        lmi_ulong   header;
        sdl_ulong   rx_bytes;
        sdl_ulong   tx_bytes;
        sdl_ulong   rx_sus;
        sdl_ulong   tx_sus;
        sdl_ulong   rx_overruns;
        sdl_ulong   tx_underruns;
        sdl_ulong   rx_aborts;
        sdl_ulong   tx_aborts;
        sdl_ulong   rx_buffer_overflows;
        sdl_ulong   tx_buffer_overflows;
        sdl_ulong   rx_sus_in_error;            /* Q.752 Table 1.8  5,30 min */
        sdl_ulong   tx_sus_in_error;
        sdl_ulong   rx_sync_transitions;
        sdl_ulong   rx_bits_octet_counted;
        sdl_ulong   rx_crc_errors;
        sdl_ulong   rx_frame_errors;
        sdl_ulong   rx_frame_overflows;
        sdl_ulong   rx_frame_too_long;
        sdl_ulong   rx_frame_too_short;
        sdl_ulong   rx_residue_errors;
        sdl_ulong   lead_cts_lost;
        sdl_ulong   lead_dcd_lost;
        sdl_ulong   carrier_lost;
    } sdl_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, lead_dcd_lost, lead_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:

SDL_IOCGNOTIFY
    Gets the protocol notification bitmask of the Signalling Data Link into the provided sdl_notify structure.

SDL_IOCSNOTIFY
    Sets protocol notification for the Signalling Data Link events identified by set bits in the provided sdl_notify structure.

SDL_IOCCNOTIFY
    Clears protocol notification for the Signalling Data Link events identified by set bits in the provided sdl_notify structure.

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

    typedef struct sdl_notify {
        sdl_ulong   sdl_notifications;
    } sdl_notify_t;

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

        SDL_EVT_LOST_SYNC | Received lost flag sync.
        SDL_EVT_SU_ERROR | SU received in error.
        SDL_EVT_TX_FAIL | Transmitter failure.
        SDL_EVT_RX_FAIL | Receiver failure.

SEE ALSO

devi(7), getmsg(2), ioctl(2), lmi(7), mtpi(7), putmsg(2), read(2), sdti(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.