fd = open("/dev/sl", flags);
ret = ioctl(fd, cmd, ... /* arg */ );
This man page describes the STREAMS interface which is used to configure and exchange data with SS7 Signalling Link Interfaces (SLI) for all SS7 link devices conforming to the OpenSS7 Signalling Link Interface specification.
SLI drivers are normally linked using streamio(7) I_LINK ioctl under a Signalling Link Set (SLS) STREAMS multiplexer conforming to the Signalling Link Set Interface specification, slsi(7), by the SS7 configuration daemon ss7d(8). Nevertheless, this interface is available to user level programs for the purpose of Ferry-Clip testing and conformance testing of SS7 Level 2.
The SLI interface consists of three components:
The OpenSS7 Signalling Link Interface (SLI) defines M_PROTO or M_PCPROTO protocol primtives which can be sent using putmsg(2) or received using getmsg(2). This interface is normally used only by the ss7d(8) during STREAMS configuration, or by the upstream protocol modules during streamio(7) I_LINK and I_UNLINK operations, but for testing or special applications (e.g. M2UA) it is possible for a user level program to use this interface directly on an open SLI driver stream head.
There are two styles of interface as follows:
From the perspective of local management, the interface can be in a number of states. Some local management primitives are applicable in only one state. The interface can be moved through the states with local management primitives.
The management states of the interface are as follows:
Request and returns information about the SLI driver which is of interest to local configuration management (i.e. the ss7d(8)). These requests are normally performed by the ss7d(8) on the open streamhead for the SLI driver before linking it beneath the Level 3 multiplexors.
The SL_INFO_ACK returns an sl_info_ack_t structure as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_INFO_ACK */
sl_ulong sl_version;
sl_ulong sl_state;
sl_ulong sl_max_sdu;
sl_ulong sl_min_sdu;
sl_ulong sl_header_len;
sl_ulong sl_ppa_style;
sl_uchar sl_ppa_addr[8];
sl_ulong sl_bitrate;
} sl_info_ack_t;
Request that the SS7 Level 2 configuration parameters, timeouts and thresholds be configured as specified in the sl_config_req_t structure defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_CONFIG_REQ */
sl_conf_t sl_config;
} sl_config_req_t;
The SL_CONFIG_ACK indicates that the previous SL_CONFIG_REQ was successful and uses the sdt_config_ack_t struct defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_CONFIG_ACK */
sl_conf_t sl_config;
} sl_config_ack_t;
If the configuration request was unsuccessful, the provider returns a SL_ERROR_ACK which contains the errno and reason as described in the section ERRORS.
Requests that a Style 2 SLI be attached to a Siganlling Data Terminal (SDT) and Signalling Data Link (SDL). This request uses an sl_ppa_addr which specifies the PPA (Physical Point of Attachment) of the SDL and the logical identifier of the SDT (if necessary) to which the SL should be attached. This is an opaque address to the interface and is only meaningful to a specific driver implementation.
The SL_ATTACH_REQ primitive is only valid in the SL_UNATTACHED state of the interface and takes an sl_attach_req_t structure defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_ATTACH_REQ */
sl_uchar sl_ppa_addr[8];
} sl_attach_req_t;
When successful, an SL_OK_ACK is returned, otherwise an SL_ERROR_ACK is returned with the sl_errno and sl_reason set to one of the values in Section ERRORS.
Requests that a Style 2 SLI be detached from its Signalling Data Terminal (SDT) and, possibly, its Signalling Data Link (SDL). This request is only valid from the SL_ATTACHED state of the interface and takes an sl_detach_req_t structure defined in <ss7/sdti.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_DETACH_REQ */
} sl_detach_req_t;
When successful, an SL_OK_ACK is returned, otherwise an SL_ERROR_ACK is returned with the sl_errno and sl_reason set to one of the values in Section ERRORS.
Requests that an interface be enabled for operation. This request is only valid from the SL_DISABLED state of the interface and takes an sl_enable_req_t structure defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_ENABLE_REQ */
sl_ulong sl_init;
} sl_enable_req_t;
The sl_init member specifies the initial state of the signalling link when the interface is enabled. The signalling link can be initialized in any of the following states:
The OpenSS7 Signalling Link Interface (SLI) defines M_PROTO or M_PCPROTO protocol primitives which can be sent using putmsg(2) or received using getmsg(2). This interface is normally used only for module to module communications within the STREAM SS7 stack, but for testing or special application purposes, it is possible to open a module implementing the Signalling Link Interface and exchange these messages directly with a user level program.
Some primitives require a data (M_DATA) part when indicated. Many primitives do not have arguments in the control (M_PROTO or M_PCPROTO) part and the control part only contains the sl_primitive. Where additional arguments are required in the control part, those arguments and the control part datastructure are indicated.
Downstream primitives (requests) can be sent using putmsg(2). No response is provided to properly formatted primitives outside of the scope of the protocol (i.e. no SL_OK_ACK). Improperly formatted primitives receive the errors described in under ERRORS. All downstream messages must be sent as priority messages (M_PCPROTO) with the exception of SL_PDU_REQ which must be sent as a normal (M_PROTO) message or as a data only (M_DATA) message. The only message which contains a data (M_DATA) part is the SL_PDU_REQ message. Any data part in the other request primitives will be ignored.
Upstream primitives (indications) are sent from the Signalling Link Interface provider to the user of the module. These are normally priority (M_PCPROTO) messages with the exception of SL_PDU_IND, SL_RETREIVED_MESSAGE_IND and SL_RETREIVAL_COMPLETE_IND messages. A number of these primtives are provided in response to the downstream primtives as described below.
Protocol primitives are as follows:
This request and indication provide an MSU (Message Signal Unit) for transmission in the data (M_DATA) part of the message. The MSU must be (is) padded in front by sl_header_len bytes (see SL_INFO_REQ) to permit the addition (removal) of the L2 header without having to copy the data block. The SL_PDU_IND is not normally used by the driver, received MSUs are normally transfered upstream using M_DATA message blocks. MSUs may also be transferred downstream using M_DATA message blocks.
These requests are sent to request that the link invoke emergency (or normal) procedures with regard to initial alignment as required.
The SL_START_REQ request is sent to request that the link initiate initial alignment procedures and attempt to go into service. If the initial alignment procedure fails, the link will respond with a SL_OUT_OF_SERVICE_IND indication giving the reason for failure. If successful, a SL_IN_SERVICE_IND indication will result.
The SL_STOP_REQ request is sent to request that the link be placed out of service and start idling SIOS on the link. The link will later respond with a SL_OUT_OF_SERVICE_IND indication once it has successfully been placed out of service.
The SL_OUT_OF_SERVICE_IND can also be sent at any time to indicate a link failure and the reason for failure in the contained argument. The indication control (M_PCPROTO) part has the following structure:
typedef struct {
sl_ulong sl_primitive; /* SL_OUT_OF_SERVICE */
sl_ulong sl_reason; /* reason for failure */
} sl_out_of_service_t;
The sl_reason member indicates the reason for failure of the link and can take on one of the following values:
This requests the value of the current BSNT (Backwards Sequence Number on the Transmit side) for performing changeover procedures. When successful, the link will respond with a SL_BSNT_IND containing the value of the BSNT (sl_bsnt) in its control part according to the following structure:
typedef struct {
sl_ulong sl_primitive; /* SL_BSNT_IND */
sl_ulong sl_bsnt;
} sl_bsnt_ind_t;
SL_RETREIVAL_REQUEST_AND_FSNC_REQ requests that the link acknowledge MSUs in the retransmission buffer up to FSNC (Forward Sequence Number for Changeover) and provide the RTB and TB contents back to the requester during normal changeover procedures at Level 3. When successful, the link will respond with a sequence of SL_RETREIVED_MESSAGE_IND indications, each with one retrieved message in the data (M_DATA) part of the indication. This sequence will continue until the link has provided the entire contents of the RTB (Retransmission Buffer) followed by the contents of the TB (Transmission Buffer). At the end of the sequence, the link will reply with the SL_RETREIVAL_COMPLETE_IND indication.
The SL_RETREIVAL_REQUEST_AND_FSNC_REQ primitive contains a parameter (the sl_fsnc) per the following structure:
typedef struct {
sl_ulong sl_primitive;
sl_ulong sl_fsnc;
} sl_retreival_req_and_fsnc_t;
The SL_CLEAR_BUFFERS_REQ requests that the link's buffers be cleared in response to emergency changeover procedures at Level 3. When successful, the link will respond with a SL_RB_CLEARED_IND and a SL_RTB_CLEAR_IND indicating that the corresponding buffers have been cleared.
This requests that a local processor outage (recovery) condition be indicated to the link. This is based on an implementation dependent function. Normally, the link will consider a local processor outage (recovery) condition to have occured should the driver be unlinked or closed (linked or opened) while still in the operational condition. This primitive can be used in testing to simulate processor outage (recovery) conditions for conformance testing and may be used by the ss7 configuration daemon when reconfiguring the stream. These primitives are never acknowledged.
These congestion primitives may be used for Ferry-Clip conformance testing, however, the link normally detects receive congestion on its own utilizing the STREAMS flow-control capabilities. Once the upstream becomes flow-controlled the link driver internally generates the congestion accept primitive and places received MSUs on its own queue. Once the driver passes it's own high-water mark on keeping backlogged MSUs, the congestion discard primitive is generated internally. Once the upstream is no longer flow-controlled, the no congestion primitive is generated internally.
The SL_CONGESTION_DISCARD_REQ request indicates that Level 3 has detected that receive congestion has progressed to the point that discarding received MSUs is necessary. The SL_CONGESTION_ACCEPT_REQ request indicates that Level 3 has detected that receive congestion has progressed to the point that signalling busy to the distant signalling data terminal is required for receive flow control. The SL_NO_CONGESTION_REQ request indicates that Level 3 has detected that receive congestion is no longer present.
OpenSS7 supports some standard ioclts to configure SS7 Signalling Link Interface device drivers. They must be used on a stream which is attached to the device to which the ioctl applies.
If an ioctl is indicated as privileged, then using it requires sufficient access credentials. If this is not the case, EPERM will be returned.
Sets or gets the mode of the interface. Some of these modes are applicable to V.35 interfaces only, some are applicable to E1/T1/J1 interfaces only. arg indicates modes of the interface which can be one of the following:
If arg is inappropriate for the interface type, the the ioctl returns EINVAL to the caller.
Sets or getst the clocking mode of the interface. Some of these modes are applicable to V.35 interfaces only, some are applicable to E1/T1/J1 interfaces only. arg indicates clocking modes of the interface which can be one of the following:
If arg is inappropriate for the interface type, the ioctl returns EINVAL to the caller.
Sets or gets the state of the leads of a V.35 interface. arg is a bitmask indicating the the state of the leads on a get and the state in which to place the lead for a get. Some leads cannot be set by SL_IOCSIFLEAD but only read with SL_IOCGIFLEAD. arg is a bitwise or of the following bitmasks, where a one in the mask position indicates a lead which is `true' and a zero in the mask position indicates a lead which is `false' regardless of whether the lead is high-true or low-true.
These ioctls simulate breaking and reconnecting the transmit line. These are for the purpose of automated testing only (Q.781 conformance tests require the ability to break and reconnect the Tx channel as part of the testing) and provides a means to automatically break and reconnect the Tx line. These ioctls should not be used during normal operation of the link. The arg is ignored for these ioctls.
Clears the interface statistics. This resets the statistics counts to zero. In addition, the arg argument to the ioctl indicates a number of clock ticks at which the statistics accumulators should be synchronized. This is normally the number of ticks on the UNIX system clock at the time that the last 30 minute interval occured. The statistics accumulators in the driver will use this value to determine when the next accumulation interval should start.
Sets the duration of the accumulation period to arg. The accumulation period is the duration of time for which counts will be allowed to increase. After this period has expired (in syncrhonization with the value provided in SL_IOCCSTATS, above) the counts will be collected and the running counts reset to zero for the next period. Typically, this period should be set to 5 minutes or 30 minutes in accordance with ITU-T Recommendation Q.752, but can be set to any value. Setting this value too low could have an impact on system performance. A value of zero (0) defeat periodic accumulation and all accumlators will have counts which reflect the number of occurences since the last time that the statistics counts were reset with SL_IOCCSTATS.
Get the interface statistics for the last (expired) accumulation period when the accumulation period is non-zero; otherwise, it return the current interface statistics. When accumulation period is non-zero, is is the responsibility of the interface user to collect statistics in a timely manner.
Sets or gest the configuration information for the signalling link. Both set and get takes a pointer to a sl_config_t structure. For setting the configuration, the caller must complete this structure which the driver uses to set the appropriate configuration parameters. Both the set and get return the resulting (current) configuration to the struct pointed to by arg.
The structure type sl_config_t is defined in the section "CONFIGURATION".
Configuration of the SLI uses the sl_conf_t structure defined in <ss7/sli.h> as follows:
Any value which is set to 0xffffffff will not affect the current or default configuration. By setting values to 0xffffffff it is possible to affect only a select few of the members for modification in the configuration. If the protocol variant (pvar) is changed from the current settings, any members set to 0xffffffff will take on the default values for the new protocol variant.
typedef struct sl_conf {
sl_ulong pvar; /* protocol variant */
sl_ulong popt; /* protocol options */
sl_ulong t1; /* timer t1 */
sl_ulong t2; /* timer t2 */
sl_ulong t2l; /* timer t2 low */
sl_ulong t2h; /* timer t2 high */
sl_ulong t3; /* timer t3 */
sl_ulong t4n; /* timer t4 nomal */
sl_ulong t4e; /* timer t4 emerg */
sl_ulong t5; /* timer t5 */
sl_ulong t6; /* timer t6 */
sl_ulong t7; /* timer t7 */
sl_ulong t8; /* timer t8 */
sl_ulong rb_abate; /* RB cong abate */
sl_ulong rb_accept; /* RB cong accept */
sl_ulong rb_discard; /* RB cong discard */
sl_ulong tb_abate_1; /* lev 1 TB abate */
sl_ulong tb_onset_1; /* lev 1 TB onset */
sl_ulong tb_discd_1; /* lev 1 TB discard */
sl_ulong tb_abate_2; /* lev 2 TB abate */
sl_ulong tb_onset_2; /* lev 2 TB onset */
sl_ulong tb_discd_2; /* lev 2 TB discard */
sl_ulong tb_abate_3; /* lev 3 TB abate */
sl_ulong tb_onset_3; /* lev 3 TB onset */
sl_ulong tb_discd_3; /* lev 3 TB discard */
sl_ulong N1; /* PCR msg thresh */
sl_ulong N2; /* PCR octet thresh */
sl_ulong Tie; /* AERM emerg thres */
sl_ulong Tin; /* AERM norm thres */
sl_ulong M; /* IAC proving */
sl_ulong T; /* SUERM threshold */
sl_ulong D; /* SUERM rate parm */
sl_ulong N; /* octets/SU error */
sl_ulong Te; /* EIM threshold */
sl_ulong De; /* EIM downcount */
sl_ulong Ue; /* EIM upcount */
} sl_conf_t;
Additional protocol variants may be added in the future, but the currently defined protocol variants are as follows:
It can be one of the following values:
When this bit is set, it indicates that the multiple priority/congestion levels option is enabled. This enables the multiple level of transmit congestion as well.
When this bit is clear, it indicates that only one level of priority and congestion are provided. In this case, only the tb_abate_1, tb_onset_1, and tb_discd_1 transmission congestion parameters are meaningful below.
When this bit is set, the signalling link will transmit using PCR (Preventative Cyclic Retransmission) and the configuration members N1 and N2 will be used as PCR thresholds.
When this bit is clear, it means that the signalling link will use the Basic transmission control (TXC) and Reception Control (RC) state machines and configuration members N1 and N2 have no effect.
When this bit is set, the signalling link will be configured as a HSL (High Speed Link). This means that the EIM (Errored Interval Monitor) will be used in placed of the SUERM (Signal Unit Error Rate Monitor) utilizing the procedures of Q.703 Annex A and configuration members Te, De, Ue, t8 have meaning and T, D and N have no effect.
When this bit is clear, it indicates that the normal (SUERM) error rate monitor should be used and the configuration members T, D, N have meaning and Te, De, Ue and t8 have no effect.
These timeout settings provide the ability to define the timeout values for each of these standard SS7 Level 2 (Link) timers. Timeouts t2L and t2h are not currently implemented and have no effect. Timeout t8 is only for the Errored Interval Monitor (EIM) and has no effect unless the SL_OPT_HSL option is enabled.
Allow the configuration of the number of messages backlogged on the upstream path that will trigger these congestion levels. Note also that the STREAMS drivers use an indication from L3 and the ability to allocate a receive buffer in its consideration of receive congestion.
Allow the configuration of Preventative Cyclic Retransmission (PCR) forced retransmission thresholds. The N1 threshold is in number of messages and the N2 threshold is in number of octets (bytes). These configuration members only have an effect if the option SL_POPT_PCR is enabled.
When successful, a local management primitive will return an acknowledgement which is paired with the request. A number of local management primitives are paired with the SL_OK_ACK primitive which is returned on success. The format of the SL_OK_ACK primitive uses the sl_ok_ack_t structure defined in <ss7li.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_OK_ACK */
sl_ulong sl_state;
sl_ulong sl_correct_primitive;
} sl_ok_ack_t;
The sl_state member returnes the current state of the interface. The local management states of the interface are described in LOCAL MANAGEMENT PIMRIITVES. The sl_correct_primitive member returns the primitive identifier of the primitive which was successful.
When the local management primitive operation is unsuccessful, the SL provider returns a SL_ERROR_ACK acknowledgement indicating the primitive in error (sl_error_primitive), the state of the interface (sl_reason) of the error encountered. The format of the SDT_ERROR_ACK primtiive uses the sl_error_ack_t structure defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_ERROR_ACK */
sl_ulong sl_state;
sl_ulong sl_error_primitive;
sl_ulong sl_errno;
sl_ulong sl_reason;
} sl_error_ack_t;
The SLI is also capable of indicating an error condition which is not related to a specific request. When such an error condition is encountered, the interface returns a SL_ERROR_IND primitive indicating the state of the interface (sl_state) and the error number (sl_errno) and explanation (sl_reason) of the error encountered. The format of the SL_ERROR_IN primitive uses the sl_error_ind_t structure defined in <ss7/sli.h> as follows:
typedef struct {
sl_ulong sl_primitive; /* SL_ERROR_IND */
sl_ulong sl_state;
sl_ulong sl_errno;
sl_ulong sl_reason;
} sl_error_ind_t;
Brian F. G. Bidulock, <bidulock@openss7.org>.
Copyright (C) 2000 Brian Bidulock. All Rights Reserved.
This license is provided without fee, provided that the above copyright notice and this public license must be retained on all copies, extracts, compilations and derivative works. Use or distribution of this work in a manner that restricts its use except as provided here will render this license void.
The author(s) hereby waive any and all other restrictions in respect of their copyright in this software and its associated documentation. The authors(s) of this software place in the public domain any novel methods or processes which are embodied in this software.
The author(s) undertook to write it for the sake of the advancement of the Arts and Sciences, but it is provided as is, and the author(s) will not take any responsibility in it.