SLI

Section: Linux STREAMS Programmer's Manual (7)
Updated: $Date: 2008-11-01 06:55:04 $
Index Return to Main Contents
 

NAME

link - Signalling System No. 7 Level 2 (Link) Protocol  

SYNOPSIS

#include <ss7/sli.h>
#include <ss7/sli_ioctl.h>

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

 

DESCRIPTION

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:

LOCAL MANAGEMENT INTERFACE
A local management interface which utilizes M_PROTO and M_PCPROTO messages which can be exchanged using the putmsg(2) and getmsg(2) functions on the stream head once the driver is opened. This interface controls local management (STREAMS configuration functions) which are normally used by the SS7 configuration daemon ss7d(8) on the driver before linking it to an slsi(7) multiplexor. This interface is described in the section "LOCAL MANAGEMENT INTERFACE".

PRIMITIVE INTERFACE
A protocol primitive interface which utilizes M_DATA, M_PROTO and M_PCPROTO messaages which can be exchanged with the stream head using putmsg(2) and getmsg(2) functions on the stream head, or which may be exchanged with the driver by upstream pushed or linked modules. This interface exchanges SS7 protocol primitives between the signalling link and the signalling link set, but may be used for Ferry-Clip testing or specialized applications (e.g. user space SIGTRAN M2UA inetworking functions). This interface is described in the section "PRIMITIVE INTERFACE".

IOCTL INTERFACE
An ioctl interface which utilizes ioctl(2) or an I_STR ioctl from streamio(2) from a stream head for a stream to the driver. This interface controls specific aspects of the signalling link driver which are outside the scope of the SS7 protocol such as interface configuration and is normally used by the SS7 configuration daemon ss7d(8) or upstream modules during driver operation. This interface is described in the section "IOCTLS".

 

LOCAL MANAGEMENT INTERFACE

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:

SL_STYLE1
A Style 1 signalling link has it's signalling data terminal (SDT) and signalling data link (SDL) implicitly associated with it at open time. These signalling links open in the SL_DISABLED state and do not require an SL_ATTACH_REQ local management primitive to attach them to an SDT and SDL.
SL_STYLE2
A Style 2 signalling link opens in the SL_UNATTACHED state and requires that the SDT or SDL (or both) be explicitly attached to the signalling link after the device is opened with an SL_ATTACH_REQ primitive.

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:

SL_UNATTACHED
The interface is not attached. It is not attached to either a Signalling Data Terminal (SDT) or a Signalling Data Link (SDL). This state is only applicable for Style 2 modules and device drivers which must be explicitly attached to the SDT/SDL. Style 1 drivers open in the SL_DISABLED state and cannot be detached.
SL_UNUSABLE
The interface is unusabled. An the module has been attached to an SDT/SDL which is not usable.
SL_DISABLED
The interface has been attached but has not yet been enabled for use. The device must be enabled with an SL_ENABLE_REQ before data or protocol primitives can be exchanged across the interface.
SL_ENABLE_PENDING
An enable has been initiated on the interface but the provider must wait until an event occurs before the provider can be considered enabled. The provider will respond with an SL_ENABLE_CON once the enabling is successful, or an SL_ERROR_IND if it has not.
SL_ENABLED
The device is enabled and ready for use.
SL_DISABLE_PENDING
A disable has been initiated on the interface but the provider must wait until an event occurs before the provider can be considered disabled. The provider will respond with an SL_DISABLE_CON once the disabling is successful, or
 

SL_INFO_REQ, SL_INFO_ACK

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;
sl_version
Provides the version of the SLI specification to which this module conforms. The version number is encoded as one byte per version number. The current (and only) version of the SLI specification is 1.0.0.0 or 0x01000000. The member is in host byte-order.
sl_state
Provides the state of the interface.
sl_min_sdu, sl_max_sdu
Indicate the minimum and maximum signal data unit size which the signalling link will accept for transmission. These sizes are not negotiated but are based on the signalling data link format which is used by the signalling link.
sl_header_len
Indicates the amount of buffer space preceding the signal unit the the data block must be reserved to permit the addition of the SS7 Level 2 (Link) header without copying the buffer. This size is again dependent on the signalling data link format which is used by the signalling link.
sl_ppa_style
Indicates whether the signalling link is a Style 1 or 2 driver.
sl_ppa_addr
Only required for the Style 2 driver and provides for the PPA (Physical Point of Attachment) address in the sl_info_ack_t structure in the SL_INFO_ACK message. The length, format and contents of this address is opaque to the SLI but is recognized by the underlying device drivers. For the format of this address, consult the documentation for the specific driver.
sl_bitrate
Always valid on a Style 1 device, might only be valid after a Style 2 device has been attached. This is the bitrate of the Signalling Data Link (SDL) to which the device is attached. It is given in integer bits per second (bps). This value is useful for upper-level programs to index or calculate the appropriate value for configuration timers and thresholds.

 

SL_CONFIG_REQ, SL_CONFIG_ACK, SL_ERROR_ACK

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;
sl_config
A structure which contains all of the SS7 signalling link configuration information (see section "CONFIGURATION"). If any member of the sl_config structure is set to all ones (i.e. 0xffffffff), then that value will not be affected by the configuration request. Only values which are other than 0xffffffff will be altered.

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;
sl_config
Identical to that of the SL_CONFIG_ACK; however, it includes the actual values of the configuration parameters after changing specified members in the SL_CONFIG_ACK. Members of the sl_config structure which had don't care values (0xffffffff) assigned will be replaced by the actual values in the SL_CONFIG_ACK. Note that the values of all parameters can be interrogated by setting all of the members of sl_config to 0xffffffff in an SL_CONFIG_REQ.

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.

 

SL_ATTACH_REQ, SL_ATTACH_ACK, SL_ERROR_ACK

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.

 

SL_DETACH_REQ, SL_OK_ACK, SL_ERROR_ACK

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.

 

SL_ENABLE_REQ, SL_ENABLE_CON, SL_ERROR_ACK

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:

SL_INIT_POWEROFF
The signalling link with be brought up in the SL_STATE_POWER_OFF state. The signalling link will not be powered on until it receives the first SL_LSC_START protocol command from upstream.
SL_INIT_OOS
The signalling link will be brought up in the SL_STATE_OUT_OF_SERVICE state.
SL_INIT_PROC_OUTAGE
The signalling link will be brought up in the SL_PROCESSOR_OUTAGE state.
SL_INIT_AUTOSTART
The signalling link will be brought up in the SL_OUT_OF_SERVICE state, but will be automatically given the SL_LSC_START protocol command necessary to start initial alignment of the link.

 

SL_DISABLE_REQ, SL_DISABLE_CON, SL_ERROR_ACK

 

PRIMITIVE INTERFACE

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:

 

SL_PDU_REQ, SL_PDU_IND

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.

 

SL_EMERGENCY_REQ, SL_EMERGENCY_CEASES_REQ

These requests are sent to request that the link invoke emergency (or normal) procedures with regard to initial alignment as required.

 

SL_START_REQ, SL_STOP_REQ, SL_IN_SERVICE_IND, SL_OUT_OF_SERVICE_IND

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:

SL_FAIL_UNSPECIFIED
The link has failed because of some condition outside of the context of the state machines and for an unspecified reason.
SL_FAIL_CONG_TIMEOUT
T6 has timed out indicating that the link was in receive congestion for an excessive period of time.
SL_FAIL_ACK_TIMEOUT
T7 has timed out indicating that an excessive delay of acknowledgement has occured.
SL_FAIL_ABNORMAL_BSNR
Several abnormal BSNR (Backward Sequence Number Received) values were received indicaitng loss of sequence number synchronization.
SL_FAIL_ABNORMAL_FIBR
Several abnormal FIBR (Forward Indicator Bit Received) values were received indicating loss of indicator bit synchronization.
SL_FAIL_SUERM
The SUERM has detected an excessive error rate and placed the link out of service.
SL_FAIL_ALIGNMENT_NOT_POSSIBLE
IAC (Initial Alignment Control) has failed to align the link for service (i.e. several proving periods have failed).
SL_FAIL_RECEIVED_SIO
The other end of the link has failed as indicated by receipt of an SIO.
SL_FAIL_RECEIVED_SIN
The other end of the link has failed as indicated by receipt of an SIN.
SL_FAIL_RECEIVED_SIE
The other end of the link has failed as indicated by receipt of an SIE.
SL_FAIL_RECEIVED_SIOS
The other end of the link has failed as indicated by receipt of an SIOS.
SL_FAIL_T1_TIMEOUT
T1 had timed out indicating that the other end of the link, while passing initial alignment procedures, is unable to place the link inservice (didn't send FISU/MSU).

 

SL_RETREIVE_BSNT_REQ, SL_BSNT_IND

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, SL_RETREIVED_MESSAGE_IND, SL_RETREIVAL_COMPLETE_IND

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;

 

SL_CLEAR_BUFFERS_REQ, SL_RB_CLEARED_IND, SL_RTB_CLEARED_IND

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.

 

SL_LOCAL_PROCESSOR_OUTAGE_REQ, SL_RESUME_REQ

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.

 

SL_CONGESTION_DISCARD_REQ, SL_CONGESTION_ACCEPT_REQ, SL_NO_CONGESTION_REQ

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.

 

IOCTLS

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.

 

SL_IOCSIFMODE, SL_IOCGIFMODE

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:

SL_MODE_DCE
Indicates a V.35 interface in Data Control Equipment mode. This defines the sense and direction of the various leads on the V.35 interface. This is the normal operating mode when connecting a V.35 interface from the host to a V.35 modem or channel bank.
SL_MODE_DTE
Indicates a V.35 interface in Data Terminal Equipment mode. This defines the sense and direction of the various leads on the V.35 interface.
SL_MODE_LOOP
Indicates a V.35 or E1/T1/J1 channel in loopback mode. In loopback mode all received bits on the Rx lead are looped back to the Tx lead.
SL_MODE_JACK
Indicates a V.35 interface in loopback jack mode. In this mode, a loopback jack is used to loop Tx bits back to Rx bits. This mode sets the sense of other leads and clocking to permit use of a loopback jack.
SL_MODE_ECHO
Indicates a V.35 interface in echo mode. In this mode all bits transmitted on the Tx lead are looped back to the Rx lead.
SL_MODE_BOTH
Indicates a V.35 interface into both loopback and echo modes. This is not too useful.

If arg is inappropriate for the interface type, the the ioctl returns EINVAL to the caller.

 

SL_IOCSIFCLOCK, SL_IOCGIFCLOCK

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:

SL_CLOCK_EXT
Indicates a V.35 interface in external clocking mode. This means that the interface will use the external clock leads for synchronizing the Tx bitstream as well as for generating the Rx bitstream.
SL_CLOCK_INT
Indicates a V.35 interface in internal clocking mode. This means that the interface will use and internal clock source to syncrhonize both the Rx and Tx bitstreams.
SL_CLOCK_DPLL
Indicates a V.35 interface in digital phase locked loop mode. This means that the interface will use a DPLL syncrhonized to the Tx bitstream to regenerate an internal clock for both Tx bitstream sampling as well as Rx bitstream pulse generation.
SL_CLOCK_SLAVE
Indicates an E1/T1/J1 interface in slave mode. This means that the local clock will be derived from the Rx stream and used to sample both Rx and generate Tx bitstreams. This applies to then entire E1/T1/J1 interface (not just this channel).
SL_CLOCK_MASTER
Indicates an E1/T1/J1 interface in master mode. This means that a local clock will be used to sample the Rx stream as well as generate Tx timings. This applies to the entire E1/T1/J1 interface (not just the channel).
SL_CLOCK_LOOP
Indicates an E1/T1/J1 interface in loop mode. This means that a local clock will be syncrhonized to the Rx stream and regenerated (using a phase locked loop) to sample the Rx stream as well as generate Tx stream timings. This applies to the entire E1/T1/J1 interface (not just the channel).

If arg is inappropriate for the interface type, the ioctl returns EINVAL to the caller.

 

SL_IOCSIFLEAD, SL_IOCGIFLEAD

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.

SL_LEAD_DTR
Data-terminal-ready lead. This lead can be set or get and indicates the (desired) state of the DTR lead on the V.35 interface.
SL_LEAD_RTS
Request-to-send lead. This lead can be set or get and indicates the (desired) state of the RTS lead on the V.35 interface.
SL_LEAD_DCD
Data-carrier-detect lead. This lead can only be read and indicates the state of the DCD lead on the V.35 interface.
SL_LEAD_CTS
Clear-to-send lead. This lead can only be read and indicates the state of the CTS lead on the V.35 interface.
SL_LEAD_DSR
Data-set-ready lead. This lead can only be read and indicates the state of the DSR lead on the V.35 interface.

 

SL_IOCCBRKTXLINE, SL_IOCCCONTXLINE

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.

 

SL_IOCCIFSTATS

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.

 

SL_IOCSIFSTATSP

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.

 

SL_IOCGIFSTATS

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.

 

SL_IOCSCONFIG, SLIOCGCONFIG

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

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;
The members in this structure are interpreted as follows:
pvar - (Protocol Variant)
This determines the protocol variant which will be used for the Signalling Link. When the protocol variant is set, all configuration parameters, options and state machine procedures must conform to the Signalling Link sections of the applicable standards. Modifications to this configuration can be made by changing other parameters in the configuration (particularly popt). When the value of pvar is changed, default values for the rest of the configuration members will be used if not specified.

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:

SS7_PVAR_ITUT_88
Conforming to ITU-T Recommendation Q.700 through Q.704 (Blue Book).
SS7_PVAR_ITUT_93
Conforming to ITU-T Recommendation Q.700 through Q.704 (White Book).
SS7_PVAR_ITUT_96
Conforming to ITU-T Recommendation Q.700 through Q.704 (Grey Book).
SS7_PVAR_ITUT_00
Conforming to ITU-T Recommendation Q.700 through Q.704 (Black Book).
SS7_PVAR_ANSI_88
Conforming to ANSI T1.111-1988 sections T1.111.1 through T1.111.3.
SS7_PVAR_ANSI_92
Conforming to ANSI T1.111-1992 sections T1.111.1 through T1.111.3.
SS7_PVAR_ETSI_88
Conforming to ETSI technical specification ETS 300 008-1 1988.
SS7_PVAR_ETSI_93
Conforming to ETSI technical specification ETS 300 008-1 1993.
SS7_PVAR_ETSI_96
Conforming to ETSI technical specification ETS 300 008-1 1996.
SS7_PVAR_ETSI_00
Conforming to ETSI technical specification ETS 300 008-1 2000.
SS7_PVAR_JTTC_94
Conforming to JTTC technical specifications JT-Q.700 through JT-Q.704, 1994.

popt - (Protocol Options)
This determines which options are available to modify the main specification as determined by the pvar configuration member. The popt member is a bit-wise OR of the following option bitmasks:

SL_POPT_MPLEV
The link is set for national options for multiple congestion levels. This affects the interpretation of the transmission congestionn levels described below. When this bit is set, it indicates the use of multiple congestion levels, when cleared it indicates a single congestion level.

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.

SL_POPT_PCR
When this bit is set, the link will use the PCR (Preventative Cyclic Retransmission) versions of the TXC (Transmission Control) and RC (Reception Control) state machine modules and procedures within the SS7 Level 2 specifications.

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.

SL_POPT_HSL
When this bit is set, the link will use the High-Speed Link (HSL) EIM (Errorred Interval Monitor) in place of the SUERM for error rate montoring on the link while the link is in service. When this bit is enabled, the SUERM configuration parameters are meaningless and the EIM configuration parameters are meaningful. Otherwise, normal SUERM procedures apply and the SUERM configuration take precedence over EIM configuration.

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.

SL_POPT_XSN
When this bit is set, the link will use the Extended Sequence Numbers and Length Indicator of Q.703 Annex A.
t1, t2, t2l, t2h, t3, t4n, t4e, t5, t6, t7, t8
These members provide the timeout values (in ticks or jiffies) for the various SS7 Level 2 drivers as explained in the pertinent specifications. Minimum and maximum values for these timers is enforced. Min and max values are determined based on the protocol variant (pvar) and the pertinent specifications.

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.

rb_abate, rb_accept, rb_discard
These members provide the abate, accept and discard levels for receive congestion according to the "implementation dependent" receive congestion function specified for SS7 Level 2 in the pertinent specifications. In this (STREAMS) implementation, thes values represent the number of backlogged received MSUs at which the corresponding threshold will be passed. In addition, the driver uses STREAMS based flow control to determine thresholds in addition to these values. When the upstream module is flow-controlled, the accept threshold is passed. When the driver is flow-controlled, the discard threshold is passed. When the upstream module is no longer flow controlled, congestion abates.

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.

tb_abate_1, tb_onset_1, tb_discd_1, tb_abate_2, tb_onset_2, tb_discd_2, tb_abate_3, tb_onset_3, tb_discd_3
Allow the configuration on abatement, onset and discard thresholds for each congestion level. The second and third levels are only meaningful if the SL_POPT_MPLEV protocol option is set, otherwise, only the first level configuration setting are meaningful. Note that the STREAMS implementation uses the byte occupancy of both the transmit buffer (TB) and retransmit (RTB) buffer in its consideration of transmit congestion. These thresholds are in bytes.
tb_abate_1, tb_abate_2, tb_abate_3
These are the transmission congestion thresholds at which each corresponding congestion level will abate. They are expressed in units of MSU bytes availabl for transmission and retransmission. If SL_PROT_MPLEV is clear, only the first level value is significant: the remaining two values are ignored by the driver.
tb_onset_1, tb_onset_2, tb_onset_3
These are the transmission congestion onset thresholds (at which a TFC message will be sent if TFC option is enabled at L3).
tb_discd_1, tb_discd_2, tb_discd_3
These are the transmission congestiond discard thresholds (at which an MSU for transmission of a lower priority will be discarded).

N1, N2
These are the PCR (Preventative Cyclic Retransmission) thresholds. The N1 threshold is given in number of messages and represents the number of messages in the retransmission buffer which will trigger a forced retransmission cycle. The N2 threshold is given in number of octets and represents the number of octets in the retransmission buffer which will trigger a forced retransmission cycle. These configuration members are only meaningful if the SL_POPT_PCR bit is set in the popt member.

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.

Tie, Tin, M, T, D, N, Te, De, Ue
Configuration parameters are described in sdti(7). T, D, N only have an effect if the SL_POPT_HSL option is disabled. Te, De, Ue, only have an effect if the SL_POPT_HSL option is enabled.
Tin, Tie
These are the AERM (Alignment Error Rate Monitor) thresholds for normal and emergency alignment. They are unitless integer values. These values are normally set to Tin = 4 and Tie = 1 according to specifications.
M
This is the number of proving cycles that the IAC (Initial Alignement Control) will perform during normal alignment. This value is normally set to 5 according to specifications.
T, D, N
This is the error threshold (T), the error rate parameter (D) and the number of octets per SU error indication in octet counting mode (N). These are unitless values and must normally be set to 32 or 64, 256, and 16 respectively to meet specifications.
Te, De, Ue
These are the error threshold (Te), the downcount (De) and upcount (Ue) of the EIM (Errored Interval Monitor). These are unitless values and are provided as integer values that are 1000 times the decimal values given in the specifications. Proscribed values depend on the rate of the high-speed link.

 

ERROR HANDLING

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;

 

ERRORS

Error numbers and reasons which may be returned in the SL_ERROR_ACK or SL_ERROR_IND primitives are as follows:

ERROR NUMBER
The following error numbers may be returned in the sl_errno member of the SL_ERROR_ACK or SL_ERROR_IND primitive:
SL_BADDISPOSAL

SL_BADFRAME

SL_BADPPA

SL_BADPRIM

SL_DISC

SL_EVENT

SL_FATALERR

SL_INITFAILED

SL_NOTSUPP

SL_OUTSTATE

SL_PROTOSHORT

SL_SYSERR

SL_WRITEFAIL

ERROR EXPLANATIONS
The followin error reasons (explanations) may be returned in the sl_reason member of the SL_ERROR_ACK or SL_ERROR_IND primitive:
SL_FORMAT

SL_OVERRUN

SL_BUSY

SL_QUIESCENT

SL_DSRTIMEOUT

SL_LOSTCTS

 

SEE ALSO

streamio(2), putmsg(2), getmsg(2), ioctl(2), sdti(7), slsi(7), mtpi(7), ss7d(8).  

CAVEATS

 

AUTHOR

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

HISTORY

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

REFERENCES

 

COPYRIGHT

Copyright (C) 2000 Brian Bidulock. All Rights Reserved.

PUBLIC LICENSE

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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
LOCAL MANAGEMENT INTERFACE
SL_INFO_REQ, SL_INFO_ACK
SL_CONFIG_REQ, SL_CONFIG_ACK, SL_ERROR_ACK
SL_ATTACH_REQ, SL_ATTACH_ACK, SL_ERROR_ACK
SL_DETACH_REQ, SL_OK_ACK, SL_ERROR_ACK
SL_ENABLE_REQ, SL_ENABLE_CON, SL_ERROR_ACK
SL_DISABLE_REQ, SL_DISABLE_CON, SL_ERROR_ACK
PRIMITIVE INTERFACE
SL_PDU_REQ, SL_PDU_IND
SL_EMERGENCY_REQ, SL_EMERGENCY_CEASES_REQ
SL_START_REQ, SL_STOP_REQ, SL_IN_SERVICE_IND, SL_OUT_OF_SERVICE_IND
SL_RETREIVE_BSNT_REQ, SL_BSNT_IND
SL_RETREIVAL_REQUEST_AND_FSNC_REQ, SL_RETREIVED_MESSAGE_IND, SL_RETREIVAL_COMPLETE_IND
SL_CLEAR_BUFFERS_REQ, SL_RB_CLEARED_IND, SL_RTB_CLEARED_IND
SL_LOCAL_PROCESSOR_OUTAGE_REQ, SL_RESUME_REQ
SL_CONGESTION_DISCARD_REQ, SL_CONGESTION_ACCEPT_REQ, SL_NO_CONGESTION_REQ
IOCTLS
SL_IOCSIFMODE, SL_IOCGIFMODE
SL_IOCSIFCLOCK, SL_IOCGIFCLOCK
SL_IOCSIFLEAD, SL_IOCGIFLEAD
SL_IOCCBRKTXLINE, SL_IOCCCONTXLINE
SL_IOCCIFSTATS
SL_IOCSIFSTATSP
SL_IOCGIFSTATS
SL_IOCSCONFIG, SLIOCGCONFIG
CONFIGURATION
ERROR HANDLING
ERRORS
SEE ALSO
CAVEATS
AUTHOR
HISTORY
REFERENCES
COPYRIGHT

This document was created by man2html, using the manual pages.
Time: 23:32:01 GMT, January 07, 2001