SDLI

Section: OpenSS7 SS7 Stack Signalling Data Link Interface (SDLI) (7)
Updated: 2008-10-31
Index Return to Main Contents

NAME

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

SYNOPSIS

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

int fd = open (``/dev/sdl'', flags);
int 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(2) 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_errorsrx_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.

BUGS

Too many to mention.

HISTORY

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

REFERENCES

[1]: ITU-T Recommendation Q.702, Signalling System No. 7 --- Signalling Data Link, March 1993, (Geneva), ITU, ITU-T Telecommunication Standardization Sector of ITU. (Previously "CCITT Recommendation") <http://www.itu.int/rec/T-REC-Q.702/>
[2]: ITU-T Recommendation Q.703, Signalling System No. 7 --- Signalling Link, March 1993, (Geneva), ITU, ITU-T Telecommunication Standardization Sector of ITU. (Previously "CCITT Recommendation") <http://www.itu.int/rec/T-REC-Q.703/>
[3]: ITU-T Recommendation Q.704, Message Transfer Part --- Signalling Network Functions and Messages, March 1993, (Geneva), ITU, ITU-T Telecommunication Standardization Sector of ITU. (Previously "CCITT Recommendation") <http://www.itu.int/rec/T-REC-Q.704/>