SDTI

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

---

 

NAME

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

SYNOPSIS

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

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

 

DESCRIPTION

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

SDTI drivers are nomally linked using streamio(7) I_PUSH ioctl under a Signalling Link (SL) STREAMS module conforming to the Signalling Link Interface specification, sli(7) such as sl(8), 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.

SDTI Style 1 or 2 drivers may be configured to autopush the sl(8) module and appear as sli(7) drivers. Not all SS7 drivers are written to the SDT interface: drivers may be written to the sli(7) or slsi(7) interfaces.

SDTI drivers which are included in the OpenSS7 release include:

acb56(8)

An SDTI compliant signalling data terminal driver for the SeaLevel ACB56 card.

soip(8)

An SDTI compliant signalling data terminal emulator over UDP for SS7/IP.

m2tp(8)

An SDTI compliant signalling data terminal emulator for MTP Level 2 Tunneling Protocol (M2TP) for SS7/SCTP.

The SDTI 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 pushing an sl(8) module onto the stream head. 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 data terminal, but may be used for Ferry-Clip testing or specialized applications (e.g. user space M2TP 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_PUSH and I_POP operations, but for testing or special applications (e.g. M2TP) it is possible for a user level program to use this interface directly on an open SDTI driver stream head.  

PPA Style

The SDT Provider can support one of two styles of PPA (Physical Point of Attachment). These styles are as follows:

SDT_STYLE1

A Style 1 driver is a driver whose SDL (Signalling Data Link) is associated with the stream head at open time. These drivers open in the SDT_DISABLED state and do not require a SDT_ATTACH_REQ local management primitive to associate them with an SDL. Style 1 drivers do not require PPA addresses.

SDT_STYLE2

A Style 2 driver is a driver whose SDL must be attached to the stream after open. These drivers open in the SDT_UNATTACHED state and must be attached with a SDT_ATTACH_REQ local management primitive before they can be enabled. Style 2 drivers require a PPA address to indicate the PPA (Physical Point of Attachment) address to which the stream has been attached. The PPA Address is an opaque address which is meaningful only to a specific driver implementation of the SDTI.

 

Local Management States

From the perspective of local management, the SDT provider can be in a number of management states. Some local management primitives are applicable in only on state. The SDT provider can be moved through the states with local management primitives.

The management states of the SDT provider are as follows:

SDT_UNATTACHED

The interface is not attached. It is not attached to a Signalling Data Link (SDL). This state is only applicable to Style 2 device drivers which must be explicitly attached to the SDL. Style 1 drivers open in the SD_DISABLED state an cannot be detached.

SDT_UNUSABLE

The interface is unusable. This may be due to the attached SDL being no longer usable or the device being rendered unusable due to some other reason (i.e. removal from the system).

SDT_DISABLED

The interface has been attached but has not yet been enabled for use. The device must be enabled with a SDT_ENABLE_REQ local management primitive before data or protocol primitives can be exchanged across the interface.

SDT_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 SDT_ENABLE_CON once the enabling is successful, or an SDT_ERROR_IND if it has not.

SDT_ENABLED

The device is enabled and ready for use.

SDT_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 a SDT_DISABLE_CON once the disabling is successful, or an SDT_ERROR_IND if it has not.

 

Local Management Primitives

Local management primitives can be exchanged with the device driver as M_PROTO or M_PCPROTO primitives using the putmsg(2) or getmsg(2) system calls on the stream head. This interface is normally used only by the SS7 Configuration Daemon ss7d(8) during STREAMS configuration, or by the upstream protocol modules during streamio(7) I_PUSH and I_POP operations, but for testing or special applications, it is possible for a user level program to use this interface directly on an open SDTI driver stream head.

It should be noted that only M_PROTO local management primitives will be deferred during congestion of the SDT provider. Local management primitives sent as M_PCPROTO will receive a SDT_ERROR_ACK in response should it not be possible to execute them immediately.

Local management primitives provided by SDTI are as follows:

SDT_INFO_REQ, SDT_INFO_ACK

Request and returns information about the SDTI 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 SDTI driver before pushing it beneath the Level 2 module.

The SDT_INFO_REQ takes an sdt_info_req_t structure as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_INFO_REQ */
} sdt_info_req_t;

The SDT_INFO_ACK returns an sdt_info_ack_t structure as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_INFO_ACK */
    sdt_ulong   sdt_version;
    sdt_ulong   sdt_state;
    sdt_ulong   sdt_max_sdu;
    sdt_ulong   sdt_min_sdu;
    sdt_ulong   sdt_ppa_style;
    sdt_uchar   sdt_ppa_addr[8];
    sdt_ulong   sdt_bitrate;
    sdt_conf_t  sdt_config;
} sdt_info_ack_t;

sdt_version

Provides the version of the SDTI interface specification to which the driver conforms with one byte per version number. The current (and only) version of the SDTI is 1.0.0.0. or 0x01000000 in host order.

sdt_min_sdu, sdt_max_sdu

Reflect the minimum and maximum frame sizes which may be transferred to and from the interface. In SS7 this is not a negotiated value: it is determined by the type of SDL (Signalling Data Link) which is provided by the interface.

sdt_ppa_style, std_ppa_addr

Indicate the style of driver as follows:

SDT_STYLE1

A Style 1 driver is a driver whose SDL (Signalling Data Link) is associated with the stream head at open time. These drivers open in the SDT_DISABLED state and do not require an SDT_ATTACH_REQ to associate them with a Signalling Data Link. For Style 1 drivers, the sdt_ppa_addr member is meaningless.

SDT_STYLE2

A Style 2 driver is a driver whose SDL must be attached to the stream after open. These drivers open in the SDT_UNATTACHED state and must be attached with an SDT_ATTACH_REQ local management primitive before they can be enabled. The sdt_ppa_addr member indicate which PPA (Physical Point of Attachment) address to which the stream has been attached. The PPA is an opaque address which is meaningful to a specific driver.

sdt_bitrate

Indicates the bit rate on the line in bits per second (bps). This value may be used by the ss7d(8) to calculate the durations of timers and other bitrate-dependent parameters.

sdt_config

Contains SS7 Initial Alignment Control (IAC), Alignment Error Rate Monitor (AERM), Signal Unit Error Rate Monitor (SUERM) and Errored Interval Monitor (EIM) parameters and thresholds. These values determine the operating characteristics of these SS7 Level 2 state machines and are normally set by the ss7d(8) using the SDT_CONFIG_REQ primitive.

SDT_CONFIG_REQ, SDT_CONFIG_ACK, SDT_ERROR_ACK

Request that the SS7 Level 2 configuration parameters and thresholds be configured as specified in the sdt_config_req_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_CONFIG_REQ */
    sdt_conf_t  sdt_config;
} sdt_config_req_t;

The members of sdt_config are SS7 Initial Alignment Control (IAC), Alignment Error Rate Monitor (AERM) and Signal Unit Error Rate Monitor (SUERM) parameters and thresholds. These values determine the operating characteristics of these SS7 Level 2 state machines. Their current values may be examined with the SDT_INFO_REQ primitive.

The SDT_CONFIG_ACK indicates that the previous SDT_CONFIG_REQ was successful and uses the sdt_config_ack_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_CONFIG_ACK */
} sdt_config_ack_t;

SDT_ATTACH_REQ, SDT_OK_ACK, SDT_ERROR_ACK

Requests that a Style 2 SDTI be attached to a Signalling Data Link (SDL). This request uses an sdt_ppa_addr which specifies the PPA (Physical Point of Appearance) of the SDL to which the SDT should be attached. This is an opaque address to the interface and is only meaningful to a specific driver implementation.

The SDT_ATTACH_REQ primitive is only valid from the SDT_UNATTACHED state of the interface and takes an sdt_attach_req_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_ATTACH_REQ */
    sdt_uchar   sdt_ppa_addr[8];
} sdt_attach_req_t;

When successful an SDT_OK_ACK is returned, otherwise an SDT_ERROR_ACK is returned with the errno and reason set to one of the values in Section ERRORS.

SDT_DETACH_REQ, SDT_OK_ACK, SDT_ERROR_ACK

Requests that a Style 2 SDTI be detached from its Signalling Data Link (SDL). This request is only valid from the SDT_ATTACHED state of the interface and takes an sdt_detach_req_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_DETACH_REQ */
} sdt_detach_req_t;

When successful an SDT_OK_ACK is returned, otherwise an SDT_ERROR_ACK is returned with the errno and reason set to one of the values in Section ERRORS.

SDT_ENABLE_REQ, SDT_ENABLE_CON, SDT_ERROR_ACK

Requests that the interface be enabled for operation. This request is only valid from the SDT_DISABLED state of the interface and takes an sdt_enable_req structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_ENABLE_REQ */
    sdt_ulong   sdt_rx_init;
    sdt_ulong   sdt_tx_init;
} sdt_enable_req_t;

The sdt_rx_init and sdt_tx_init specify what the initial state of the receivers and transmitters should be when the interface is enabled. The receivers can be initialized in any of the following states (all values are not necessarily supported by all drivers):

SDT_RX_OFF

Initializes the receivers but keeps them detached from the line. The receivers do not synchronize with flags or generate any indications to the driver.

SDT_RX_NONE

Leaves the receivers in the state that they were before the SDT_ENABLE_REQ command. This permits an SDT_DISABLE_REQ followed by an SDT_ENABLE_REQ without changing the state of the receiver. The first initialization of the receiver leaves it in the default state SDT_RX_OFF.

SDT_RX_DISABLE

Turns on the receiver interrupt service routine but disables the transfer of frames from the driver. Other internal indications (such as loss of sync) are detected and reported internally to the driver.

The transmitters can be initialized in any of the following states (all values are not necessarily supported by all drivers):

SDT_TX_OFF

Initializes the transmitters but keeps then disconnected from the line (i.e. allows the Tx line to float). The transmitters do not generate flags or any other idle character on the line.

SDT_TX_NONE

Leaves the transmitters in the state that they were befoer the SDT_ENABLE_REQ command. This permits an SDT_DISABLE_REQ followed by an SDT_ENABLE_REQ without changing the state of the transmitter. The first initialization of the transmitter leave it in the default state SDT_TX_OFF.

SDT_TX_IDLE_MARK, SDT_TX_IDLE_SPACE, SDT_TX_IDLE_FLAG

Initializes the transmitter and attaches it to the line but configures it to idle mark 0xff (space 0x00 or flag 0x7e). The transmit interrupt service routine can be disabled if the serial controller chip is capable of idling mark (space or flag) on its own.

SDT_TX_IDLE_FISU, SDT_TX_IDLE_SIOS

Initializes the transmitter and attaches it to the line but configures it to idle a FISU (or LSSU SIOS). The value of the BIB/BSN FIB/FSN in the FISU (or LSSU SIOS) is determined by the last transmitted MSU on the interface. The transmit interrupt service routine can be enabled if the serial controller chip is incapable of idling FISU on its own.

When successful an SDT_ENABLE_CON is returned, otherwise an SDT_ERROR_ACK is returned with the errno and reason set to one of the values in Section ERRORS.

SDT_DISABLE_REQ, SDT_DISABLE_CON, SDT_ERROR_ACK

Requests that the interface be disabled from operation. This requiest is only valid from the SDT_ENABLED state of the interface and takes an sd_disable_req_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_DISABLE_REQ */
    sdt_ulong   sdt_rx_disp;
    sdt_ulong   sdt_tx_disp;
} sdt_disable_req_t;

The sdt_rx_disp and sdt_tx_disp specify the disposition of the receiver and transmitter when the interface is disabled. The receiver can be left in any of the following states (all values are not necessarily supported by all drivers):

SDT_RX_OFF

Shuts down the receiver and detaches it from the line. The receiver no longer synchronize with flags or generate any indications to the driver. The receiver interrupt service routine is disabled.

SDT_RX_NONE

Leaves the receiver in the state that it was before the SDT_DISABLE_REQ command. The receivers are disabled from transferring received SUs across the SDT interface.

SDT_RX_DISABLE

Disables the receivers and the transfer of received SUs to the upper level state machines, but continues to monitor the line and sychronize with flags.

The transmitter can be left in any of the following states (all values are not necessarily supported by all drivers):

SDT_TX_OFF

Shuts down the transmitter and detaches it from the line. The transmitter does not generate any bits and the line is allowed to float.

SDT_TX_NONE

Leaves the transmitter in the state that it was before the SDT_DISABLE_REQ command. The transmitter no longer accepts SUs for transmission from the SDT interface. If the transmitter was idling an LSSU it continues to idle that LSSU. If the transmitter was idling a FISU, it continues to idle that FISU. It the transmitter was sending an MSU, it completes transmission of the MSU and then idles a FISU with the same BIB/BSN FIB/FSN as the last transmitted MSU.

SDT_TX_IDLE_MARK, SDT_TX_IDLE_SPACE, SDT_TX_IDLE_FLAG

Shuts down the transmit interrupt service routine, but configures the transmitter to idle mark, space or flags as indicated by the specific value above.

SDT_TX_IDLE_FISU, SDT_TX_IDLE_SIOS

Disables the ability to transfer SUs across the SDT interface for transmission and configures the transmitter (and TxISR if necessary) to idle a FISU (or LSSU SIOS) with the BIB/BSN FIB/FSN of the last transmitted FISU or MSU.

When successful an SDT_DISABLE_CON is returned, otherwise an SDT_ERROR_ACK is returned with the errno and reason set to one of the values in Section ERRORS.

SDT_STATUS_REQ, SDT_STATUS_ACK, SDT_ERROR_ACK

This request and acknowledgement permit the SDT user to interrogate the state of any of the state machines in the SDT. This is particularly important for SDT users which may loose communications with the SDT provider and need to resynchronize state between the user and provider. It may also be used for diagnostic, debuggin or ferry-clip testing purposes when the state of the internal state machines of the SDT provider need be examined.

The SDT_STATUS_ACK primitive contains the sdt_status_ack_t type structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong       sdt_primitive;  /* SDT_STATUS_ACK */
    sdt_statem_t    sdt_statem;
} sdt_status_ack_t;

typdef struct sdt_statem {
    sdt_ulong   daedt_state;
    sdt_ulong   daedr_state;
    sdt_ulong       octet_counting_mode;
    sdt_ulong   aerm_state;
    sdt_ulong       Ca;
    sdt_ulong       Ti;
    sdt_ulong   suerm_state;
    sdt_ulong       Cs;
    sdt_ulong       Ns;
    sdt_ulong   eim_state;
    sdt_ulong       Ce;
    sdt_ulong       su_received;
    sdt_ulong       interval_error;
} sdt_statem_t;

The members of the sdt_statem structure are interpreted as follows:

daedt_state

Provides the total state of the DAEDT (Delimitation Alignment and Error Detection Transmitting) per Q.703. This member can take on values SDT_STATE_IDLE or SDT_STATE_IN_SERVICE.

daedr_state, octet_counting_mode

Provides the total state of the DAEDR (Delimitation Alignment and Error Detection Receiving) per Q.703. The daedr_state member can take on values SDT_STATE_IDLE or SDT_STATE_IN_SERVICE. The octet_counting_mode member is a flag which indicates that the DAEDR is in octet counting modes as defined by Q.703 when non-zero and in normal mode when zero.

aerm_state, Ca, Ti

Provides the total state of the AERM (Alignment Error Rate Monitor) per Q.703. The aerm_state member can take on values SDT_STATE_IDLE or SDT_STATE_MONITORING. The Ca member provides the current count of errored SUs for the interval that the AERM has been monitoring and the Ti member provides the current threshold (either Tin or Tie) to which the error count is being compared.

suerm_state, Cs, Ns

Provides the total state of the SUERM (Signal Unit Error Rate Monitor) per Q.703. The suerm_state member can take on values SDT_STATE_IDLE or SDT_STATE_MONITORING. The Cs member provides the current time-weighted ratio of errored SUs to correct SUs and Ns provides the number of above error threshold intervals which remain before link failure.

eim_state, Ce, su_received, interval_error

Provides the total state of the EIM (Errorred Interval Rate Monitor) per Q.703 Annex A. The eim_state member can take on values SDT_STATE_IDLE or SDT_STATE_MONITORING. The Ce member provides the current time-weighted ration of errored intervals to error-free intervals. The two flags su_received and interval_error are used to indicate whether there is an error at this point in time in the current interval.

If it is not possible to retreive the state of the SDT provider, the provider will return an SDT_ERROR_ACK containing the sdt_errno and sdt_reason indicating the problem. Normally it is possible to retreive state information at any time.

 

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 sdt_primitive. Where additional arguments are required in the control part, those arguments and the control part datastructure are indicated.

Downstream primitives (requests, responses) can be sent using putmsg(2). No response is provided to properly formatted primitives outside of the scope of the protocol (i.e. no SDT_OK_ACK). Improperly formatted primitives receive the errors described in under ERRORS. All downstream messages must be sent as regular (M_PROTO) or priority messages (M_PCPROTO). SDT_SIGNAL_UNIT_REQ may also be sent as a data only (M_DATA) message using putmsg(2) with no control part or write(2). The only downstream message which contains a data (M_DATA) part is the SDT_SIGNAL_UNIT_REQ message. Any data part in the other request primitives will be ignored.

Upstream primitives (indications, confirmations) are sent from the Signalling Data Terminal Interface provider to the user of the module. These are normally priority (M_PCPROTO) messages with the exception of SDT_SIGNAL_UNIT_IND messages. A number of these primtives are provided in response to the downstream primtives as described below. The only upstream message which contains a data (M_DATA) part is the SDT_SIGNAL_UNIT_IND message. Any data part in the other indication primitives should be ignored. The SD_SIGNAL_UNIT_IND message is normally sent as a data only (M_DATA) message and should be collected using getmsg(2) not expected a control part or read(2).

Protocol primitives are as follows:

SDT_SIGNAL_UNIT_REQ, SDT_SIGNAL_UNIT_IND (M_DATA)

This request and indication provide an SU (Signal Unit) for transmission (or received) in the data (M_DATA) part of the message. The SU represents all of the bytes between the opening flag and the CRC bits in the transmitted (received) frame. The SDT_SIGNAL_UNIT_IND is not normally used by the driver, received SUs are normally transferred upstream using M_DATA messages. Although recognized by the driver, the SDT_SIGNAL_UNIT_REQ should not normally be used by the module above this driver. Transmitted SUs should be normally transferred downstream using M_DATA messages.

SDT_DAEDT_START_REQ

This request starts the DAEDT state machine in the SDT within the SS7 protocol. The DAEDT state machine is essentially the transmitter. If the transmitter was left in one of the idle states (SDT_STATE_IDLE), it is moved to the in service state (SDT_STATE_IN_SERVICE).

SDT_DAEDR_START_REQ

This request starts the DAEDR state machine in the SDT within the SS7 protocol. The DAEDR state machine is essentially the receiver. If the receiver was left in one of the idle states (SDT_STATE_IDLE), it is moved to the in service state (SDT_STATE_IN_SERVICE).

SDT_DAEDR_CORRECT_SU_IND

This is an indication which is given from the DAEDR to the IAC (Initial Alignment Control) above the SDT interface to indicate that a correct SU has been received immediately after an SDT_AERM_ABORT_PROVING_IND has been indicated. This SU indication is necessary to trigger the next proving period of the IAC if further proving is required.

SDT_AERM_START_REQ, SDT_AERM_STOP_REQ

These requests start and stop the AERM (Alignment Error Rate Monitor) within the SS7 protocol implemented in the SDT.

SDT_AERM_SET_TI_TO_TIN_REQ, SDT_AERM_SET_TI_TO_TIE_REQ

These request set the value of Ti in the AERM to either the normal threshold value (Tin) or the emergency threshold value (Tie). This is used to indicate to the SDT whether error rate monitoring should be performed on a normal or emergency basis.

SDT_AERM_ABORT_PROVING_IND

This indication is given from the AERM when it detects that the number of SU errors received has exceeded the current Ti threshold.

SDT_SUERM_START_REQ, SDT_SUERM_STOP_REQ

These requests start and stop the SUERM (Signal Unit Error Rate Monitor) within the SS7 protocol implemented in the SDT.

SDT_SUERM_LINK_FAILURE_IND

This indication is given from the SUERM (Signal Unit Error Rate Monitor) within the SS7 protocol implemented in the SDT.

SDT_LINK_CONG_IND, SDT_NO_LINK_CONG_IND

These indications are given from the SDT to the signalling link when the driver detects that it can no longer keep up with the receive SU stream. An indicatoin of SDT_LINK_CONG_IND is assumed to be at the discard level.

 

IOCTLS

OpenSS7 supports some standard ioclts to configure SS7 Signalling Data Terminal Interface (SDTI) device drivers. They must be used on a stream which is attached to the device to which the ioctl applies, or passed through a multiplexor (e.g. MTP, SLS) using pass through IOCTLs of the multiplexor (see, mtpi(7) and slsi(7)).

If an ioctl is indicated as privileged, then using it requires sufficient access credentials. If this is not the case, EPERM will be returned.

SDT_IOCSIFMODE, SDT_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:

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

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

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

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

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

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

SDT_IOCSIFCLOCK, SDT_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:

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

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

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

SDT_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).

SDT_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).

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

SDT_IOCSIFLEAD, SDT_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 SDT_IOCSIFLEAD but only read with SDT_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.

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

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

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

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

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

SDT_IOCCBRKTXLINE, SDT_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.

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

SDT_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 SDT_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 SDT_IOCCSTATS.

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

SDT_IOCSCONFIG, SLIOCGCONFIG

Sets or gest the configuration information for the signalling link. Both set and get takes a pointer to a sdt_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 sdt_config_t is defined in <ss7/sdti_ioctl.h> as follows:

typedef struct {
    sdt_ulong   pvar;   /* Protocol Variant     */
    sdt_ulong   popt;   /* Protocol Options     */
    sdt_ulong   M;      /* IAC proving          */
    sdt_ulong   Tin;    /* AERM norm  thres     */
    sdt_ulong   Tie;    /* AERM emerg thres     */
    sdt_ulong   T;      /* SUERM threshold      */
    sdt_ulong   D;      /* SUERM rate parm      */
    sdt_ulong   N;      /* octets/SU error      */
    sdt_ulong   t8;     /* EIM interval timer   */
    sdt_ulong   Te;     /* EIM threshold        */
    sdt_ulong   De;     /* EIM downcount        */
    sdt_ulong   Ue;     /* EIM upcount          */
} sdt_conf_t;

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 no members are changed from the current setting (i.e. all members are set to 0xffffffff) all values will take on the default values assigned by the driver.

The members in the sdt_config_t structure are interpreted as follows:

pvar

This indicates the protocol variant which the Signalling Data Terminal is expected to support. This may be any of the protocol variant values described in ss7(7). When this member alone is changed, the other members of the configuration are defaulted to the default value of the specifications associated with the protocol variant selected.

popt

This is a bit-vector of protocol options which may be enabled or disabled on the SDTI interface. Currently there is only one protocol option as follows:

SDT_POPT_EIM

When set, this option bit indicates that the EIM (Errored Interval Monitor) of Q.703 Annex A should be used instead of the SUERM (Signal Unit Error Rate Monitor) of the main Q.703. This option is required for high-speed links.

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.

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.

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) associated with the SUERM (Signal Unit Error Rate Monitor) of Q.703. These are unitless values and must normally be set to 32 or 64, 256, and 16 respectively to meet specifications.

t8, Te, De, Ue

This is the interval time t8, the error threshold Te, the correct interval downcount De and the errored interval upcount Ue associated with the EIM (Errorred Interval Monitor) state machine of Q.703 Annex A. The time interval t7 is in jiffies, and the other numbers unitless numbers which are decimal numbers represented as an integer by multiplying the recommendations of Q.703 Annex A by 1000 and rounding to obtain an integer value.

 

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 SDT_OK_ACK primitive which is returned on success. The format of the SDT_OK_ACT primitive uses the sdt_ok_ack_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_OK_ACK */
    sdt_ulong   sdt_state;
    sdt_ulong   sdt_correct_primitive;
} sdt_ok_ack_t;

The sdt_state member returns the current state of the interface. The local management states of the interface are described in LOCAL MANAGEMENT PRIMITIVES. The sdt_correct_primitive member returns the primitive identifier of the primitive which was successful.

When the local management primitive operation is unsuccessful, the SDT provider returns a SDT_ERROR_ACK acknowledgement indicating the primitive in error (sdt_error_primitive), the state of the interface (sdt_state) and the error number (sdt_errno) and explanation (sdt_reason) of the error encountered. The format of the SDT_ERROR_ACK primitive uses the sdt_error_ack_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_ERROR_ACK */
    sdt_ulong   sdt_state;
    sdt_ulong   sdt_error_primitive;
    sdt_ulong   sdt_errno;
    sdt_ulong   sdt_reason;
} sdt_error_ack_t;

The SDTI 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 SDT_ERROR_IND primitive indicating the state of the interface (sdt_state) and the error number (sdt_error) and explanation (sdt_reason) of the error encountered. The format of the SDT_ERROR_IND primitive uses the sdt_error_ind_t structure defined in <ss7/sdti.h> as follows:

typedef struct {
    sdt_ulong   sdt_primitive;  /* SDT_ERROR_IND */
    sdt_ulong   sdt_state;
    sdt_ulong   sdt_errno;
    sdt_ulong   sdt_reason;
} sdt_error_ind_t;

 

ERRORS

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

ERROR NUMBERS

The following error numbers may be returned in the sdt_errno member of the SDT_ERROR_ACK or SDT_ERROR_IND primitive:

SDT_BADDISPOSAL

Bad disposal parameter. This means that the value of the sdt_rx_init, sdt_tx_init, sdt_rx_disp or sdt_tx_disp parameter of an SDT_ENABLE_REQ or an SDT_DISABLE_REQ was not a listed value.

SDT_BADFRAME

A bad frame was delivered to the driver with SDT_SIGNAL_UNIT_REQ. Either the size was smaller than that provided for in sdt_min_sdu or larger than that provided for in sdt_max_sdu which can be discovered in an SDT_INFO_ACK.

This is normally provided in an SDT_ERROR_ACK to an SDT_SIGNAL_UNIT_REQ or as an SDT_ERROR_IND to an M_DATA.

SDT_BADPPA

The PPA (Physical Point of Appearance) address provided in an SDT_ATTACH_REQ was invalid. The error reason may provide more information. This is normally provided in an SDT_ERROR_ACK.

SDT_BADPRIM

The primitive provided in an M_PROTO or M_PCPROTO command is not and expected value. This is normally provided in an SDT_ERROR_ACK.

SDT_DISC

The primitive cannot be completed because the link is not in the SDT_STATE_IN_SERVICE state. This is normally provided in an SDT_ERROR_IND in response to one of M_PROTO primitives when the interface has not been attached by SDT_ATTACH_REQ and enabled by SDT_ENABLE_REQ.

SDT_EVENT

Some protocol specific event occured which does not permit the operation.

SDT_FATALERR

A fatal error occured in the device or driver. This error is not recoverable and will result in the generation of an M_ERROR indication.

SDT_INITFAILED

Initialization of the device or driver failed. This is normally in an SDT_ERROR_ACK response to a local management primitive.

SDT_NOTSUPP

The primitive is not supported by this particular device or driver. This is normally returned in an SDT_ERROR_ACK to a local management primitive and indicates that the primitive or a parameter of the primitive is not supported by the device or driver.

SDT_OUTSTATE

The primitive is only valid for a different state of the interface. The state of the interface is not consistent with the primitive. This is normally returned to a local management primitive which is out of order with the state, such as an SDT_ENABLE_REQ before an SDT_ATTACH_REQ has been fullfilled. This error is normally returned in an SDT_ERROR_ACK to a local management primitive.

SDT_PROTOSHORT

The M_PROTO or M_PCPROTO block is too short for the primitive.

SDT_SYSERR

A UNIX system error occured which does not permit the operation to complete.

SDT_WRITEFAIL

An attempt to write the SDT_SIGNAL_UNIT_REQ or M_DATA failed. This is normally returned in an SDT_ERROR_ACK in the former case and an SDT_ERROR_IND in the later.

ERROR EXPLANATIONS

The following error reasons (explanations) may be returned in the sdt_reason member of the SDT_ERROR_ACK or SDT_ERROR_IND primitive:

SDT_FORMAT

Formatting error. This indicates something wrong with the formatting of the item indicated by the error number.

SDT_OVERRUN

Receiver overrun. This is a reason for a error indication such as SDT_SYSERR or SDT_EVENT.

SDT_BUSY

The requested resource was busy. For example, this is a reason for refusing a validly formatted PPA in an SDT_ATTACH_REQ where the PPA is already assigned.

SDT_QUIESCENT

The requested PPA is in a transient state and is unavailable for assignment.

SDT_DSRTIMEOUT

The DSR lead has timedout on a V.35 interface.

SDT_LOSTCTS

The CTS lead has been deasserted on a V.35 interface.

 

SEE ALSO

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

CAVEATS

The SDTI relies on the STREAMS queue back-enabling mechanism to invoke the upper layer module as to when to generate a frame for transmission. This is so that frames have timely BIB/BSN FIB/FSN values before they are transferred across the SDTI. The high-water mark on the SDTI write queue is set to 1 so that when the driver takes a frame from its write queue, the queue is back-enabled to invoke the writer's write service routine an potentially back-enable the queue all the way to the stream head (if opened at the user level).

 

AUTHOR

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

HISTORY

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

PPA Style

Local Management States

Local Management Primitives

PRIMITIVE INTERFACE

IOCTLS

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