OpenSS7

OpenSS7,

Copyright 1997-2001, OpenSS7, All Rights Reserved.


Home Index Prev Next More Download Info FAQ Mail

SS7 Device

NAME SOCKET OPTIONS SEE ALSO RESTRICTIONS
SYNOPSIS IOCTLS NOTES AUTHOR
DESCRIPTION ERROR HANDLING CAVEATS HISTORY
ADDRESS FORMATS ERRORS DIAGNOSTICS REFERENCES
SYSCTLS EXAMPLES BUGS  

NAME

ss7device - Low level access to OpenSS7 SS7 MTP Level 2 (Link) Devices

SYNOPSIS

#include <sys/ioctl.h>
#include <ss7/ss7if.h>

DESCRIPTION

This man page describes the sockets interface which is used to configure SS7 Link interface devices.

OpenSS7 supports some standard ioctls to configure SS7 Link level devices. They can be used on any SS7 socket's file descriptor regardless of the family, protocol or socket type. They pass an ifreq structure:

struct ifreq
{
    char        ifr_name[IFNAMSIZE];    /* Interface name */
    union {
                struct sockaddr     ifr_addr;
                struct sockaddr     ifr_dstaddr;
                struct sockaddr     ifr_broadaddr;
                struct sockaddr     ifr_netmask;
                struct sockaddr     ifr_hwaddr;
                short               ifr_flags;
                int                 ifr_ifindex;
                int                 ifr_metric;
                int                 ifr_mtu;
                struct ifmap        ifr_map;
                char                ifr_slave[IFNAMSIZ];
                char                ifr_newname[IFNAMSIZ];
                char *              ifr_data;
    };
}

struct ifconf
{
    int         ifc_len;            /* size of buffer */
    union {
                char *              ifc_buf;    /* buffer address */
                struct ifreq *      ifc_req;    /* array of structures */
    };
};

Normally, the user specifies which device to affect by setting ifr_name to the name of the interface. All other members of the structure may share memory.

ADDRESS FORMATS

Addresses (SS7 Point Codes) are formatted as described in ss7(7).

SYSCTLS

These sysctls can be access by the /proc/sys/net/ss7/conf/link/* files or with the sysctl(2) interface.

Default values are really only default-default values, and can be changed by changing the values in the /proc/sys/net/ss7/conf/link/default/* files. Default values are only effective to newly registered SS7 LINK devices. Changing the default values will have an effect on all subsequently registered SS7 LINK devices.

ss7_link_pvar
This sysctl is used to set the protocol variant associated with the SS7 LINK device. The default value is 0, corresponding to ITU-T Recommendation Q.703 (06/93). Protocol variants currently defined are as follows:

Value Protocol Variant
0 ITU-T Recommendation Q.703 (03/93)
1 ETSI ETS 300 008-1
2 ANSI T1.111.1992

ss7_link_pcr
When this sysctl is enabled, the SS7 Link will perform PCR (Preventative Cyclic Retransmission) procedures for transmission and reception as described in ITU-T Q.703, ANSI T1.111 and ETSI ETS 300 008. Otherwise the link uses the default Basic procedures.

ss7_link_t1, ss7_link_t2, ss7_link_t2l, ss7_link_t2h, ss7_link_t3, ss7_link_t4n, ss7_link_t4e, ss7_link_t5, ss7_link_t6, ss7_link_t7
MTP Level 2 timers for SS7 operation per ITU-T Q.703, ANSI T1.111 and ETSI ETS 300 008-1. Changing a timeout values will be effective upon the next starting of a timer of that type. Timers which are already running are not affected. Default values (in seconds, for 64 kbit/s links) are as follows (minimum and maximum values are per ITU-T Q.703, ANSI T1.111 and ETSI ETS 300 008-1):

ITU-T Recommendation Q.703 (03/93) Timer Values
Timer Min. Def. Max. Description
ss7_link_t1 40.00 40.00 50.00 Timer ``aligned ready''
ss7_link_t2 5.00 5.00 150.00 Timer ``not aligned''
ss7_link_t2l 5.00 5.00 50.00 (Only used for automatic allocation of
signalling data link terminals.)
ss7_link_t2h 70.00 70.00 150.00
ss7_link_t3 1.00 1.00 2.00 Timer ``aligned''
ss7_link_t4n 7.50 8.20 9.50 Normal proving period (64 kbit/s)
ss7_link_t4e 0.40 0.60 0.60 Emergency proving period (64 kbit/s)
ss7_link_t5 0.08 0.12 0.12 Timer ``sending SIB''
ss7_link_t6 0.30 0.60 0.60 Timer ``remote congestion''
ss7_link_t7 0.50 1.00 2.00 Timer ``excessive delay of acknowledgement''

ETSI ETS 300 008-1 Timer Values
Timer Min. Def. Max. Description
ss7_link_t1 40.00 40.00 50.00 Timer ``aligned ready''
ss7_link_t2 5.00 5.00 150.00 Timer ``not aligned''
ss7_link_t2l - - - (Not used.)
ss7_link_t2h - - - (Not used.)
ss7_link_t3 1.00 1.00 2.00 Timer ``aligned''
ss7_link_t4n 7.50 8.20 9.50 Normal proving period (64 kbit/s)
ss7_link_t4e 0.40 0.60 0.60 Emergency proving period (64 kbit/s)
ss7_link_t5 0.08 0.12 0.12 Timer ``sending SIB''
ss7_link_t6 0.30 0.60 0.60 Timer ``remote congestion''
ss7_link_t7 0.50 1.00 2.00 Timer ``excessive delay of acknowledgement''

ANSI T1.111.1992 Timer Values
Timer Min. Def. Max. Description
ss7_link_t1 13.00 13.00 13.00 Timer ``aligned ready''
ss7_link_t2 11.50 11.50 23.00 Timer ``not aligned''
ss7_link_t2l - - - (Not used.)
ss7_link_t2h - - - (Not used.)
ss7_link_t3 11.50 11.50 11.50 Timer ``aligned''
ss7_link_t4n 2.30 2.30 2.30 Normal proving period (64 kbit/s)
ss7_link_t4e 0.60 0.60 0.60 Emergency proving period (64 kbit/s)
ss7_link_t5 0.08 0.12 0.12 Timer ``sending SIB''
ss7_link_t6 0.30 0.60 0.60 Timer ``remote congestion''
ss7_link_t7 0.50 1.00 2.00 Timer ``excessive delay of acknowledgement''

Timer values are set in jiffies (i.e. 10's of milliseconds for Intel Architectures under Linux). Values read and written to these sysctls are in jiffies (seconds x 100).

SOCKET OPTIONS

There are no device specific socket options. For SS7 socket options applicable to SS7 sockets, see ss7(7); for SS7 link specific socket options, see link(7).

IOCTLS

If an ioctl is marked as privileged, then using it requires an effective user id of 0 or the CAP_NET_ADMIN capability. If this is not the case EPERM will be returned.

SIOCGIFNAME
Given the ifr_ifindex, return the name of the interface in ifr_name. This is the only ioctl which returns its result in ifr_name.
SIOCGIFINDEX
Retrieve the interface index of the interface into ifr_ifindex.
SIOCSIFNAME
Changes the name of the interface specified in ifr_ifindex to ifr_newname. This is a privileged operation.
SIOCGIFADDR, SIOCSIFADDR
Gets or sets the interface address for the device using ifr_addr. For an SS7 device, this sets the local MTP PC (Point Code) associated with the link. The interface address can only be set on a link which is out of service.
SIOCGIFDSTADDR, SIOCSIFDSTADDR
Gets or sets the destination address for the device using ifr_dstaddr. For an SS7 device, this sets the adjacent MTP PC (Point Code) associated with the link. The destination address can only be set on a link which is out of service.
SIOCGIFFLAGS, SIOCSIFFLAGS
Get of set the active flags word of the device, ifr_flags contains a bit mask of the following values (some values are preset for SS7 vs. IP, and some values are not applicable):

Device Flags
IFF_UP Interface is running.
Used normally (similar to IP) for SS7.
IFF_BROADCAST Valid broadcast address set.
Not used for SS7; always set false (0).
IFF_DEBUG Internal debugging flag.
Used normally (similar to IP) for SS7.
IFF_LOOPBACK Interface is a loopback interface.
Not used for SS7; always set false (0).
IFF_POINTTOPOINT Interface is a point-to-point link.
Not used for SS7; always set true (1).
IFF_RUNNING Resources allocated.
Used normally (similar to IP) for SS7.
IFF_NOARP No arp protocol, L2 destination address not set.
Not used for SS7; always set true (1).
IFF_PROMISC Interface is in promiscuous mode.
Not used for SS7; always set false (0).
IFF_NOTRAILERS Avoid use of trailers.
Not used for SS7; always set true (1).
IFF_ALLMULTI Receive all multicast packets.
Not used for SS7; always set false (0).
IFF_MASTER Master of a load balancing bundle.
Not used for SS7; always set false (0).
IFF_SLAVE Slave of a load balancing bundle.
Not used for SS7; always set false (0).
IFF_MULTICAST Supports multicast.
Not used for SS7; always set false (0).
IFF_PORTSEL Is able to select media type via ifmap.
Not used for SS7; always set false (0).
IFF_AUTOMEDIA Auto media selection active.
Not used for SS7; always set false (0).
IFF_DYNAMIC The addresses are lost when the interface goes down.
Not used for SS7; always set false (0).

Setting the active flag word is a privileged operation, but any process may read it.

SIOCGIFMETRIC, SIOCSIFMETRIC
Get or set the metric of the device using ifr_metric. This is currently not implemented; it sets ifr_metric to 0 if you attempt to read it and returns EINVAL if you attempt to set it. Eventually this will be used to set an SDT (Signalling Data Terminal) priority.
SIOCGIFMTU, SIOCSIFMTU
Get or set the MTU (Maximum Transfer Unit), or in SS7 terms, the SIF_MAX of a device using ifr_mtu. Setting the MTU is a privileged operation. Setting the MTU to other than a standard value for the interface (LSL, HSL) will cause non-conforming operation of the interface for SS7.
SIOCGIFMAP, SIOCSIFMAP
Get or set the interface hardware parameters using ifr_map. Setting the parameters is a privileged operation.
struct ifmap
{
    unsigned long   mem_start;
    unsigned long   mem_end;
    unsigned short  base_addr;
    unsigned char   irq;
    unsigned char   dma;
    unsigned char   port;
};
    

The interpretation of the ifmap structure depends on the device driver and the architecture.

SIOCGIFXQLEN, SIOCSIFXQLEN
Get or set the transmit queue length of a device using ifr_qlen. Setting the transmit queue length is a privileged operation.
SIOCGIFCONF
Return a list of interface (transport layer) addresses. The user passes an ifconf structure as argument to the ioctl. It contains a pointer to an array of ifreq structures in ifc_req and its length in bytes is ifc_len. The kernel fills the ifreqs with all current L3 interface addresses that are running: ifr_name contains the interface name (ss7link0 etc), ifr_addr the address. The kernel returns with the actual length in ifc_len; it it is equal to the original length, the user should assume that it overflowed and retry with a bigger buffer. When no error occurs the ioctl returns 0; otherwise -1. Overflow is no error.

The following ioctls do not use the ifreq structure.

SS7IOCIFINHIBIT, SS7IOCIFUNINHIBIT
Inhibits or unihibits the Signalling Data Link associated with this Signalling Data Terminal. This is a privileged operation.

Most protocols support their own ioctls to configure protocol specific interface options. See the protocol man pages for description. For configuring MTP Point Codes (PCs), see mtp(7).

In addition, some devices support private ioctls. These are not described here.

ERROR HANDLING

ERRORS

EADDRNOTAVAIL
The requested address is not available. This error is returned in response to SIOCSIFADDR when the local PC (Point Code) does not exist locally; it is also return for SOICSIFDSTADDR for a missing adjacent PC (Point Code). One could use the SIOCADDRT ioctl to add the missing address.
EACCES
The operation is a privileged operation and the caller does not have sufficient access permission or capabilities to perform the operation.
EINVAL
A parameter is invalid.
EFAULT
A system fault occured.
EPERM
The caller does not have permission to execute the operation on the socket descriptor.

EXAMPLES

SEE ALSO

ss7(7), link(7), mtp(7), packet(7), proc(7), netdevice(7), sysctl(2)

NOTES

Many of the ioctls which are available for netdevice(7) are ip(7) specific and are not applicable to SS7.

The names of interfaces with no addresses or that don't have the IFF_RUNNING flag set can be found via /proc/net/ss7/dev.

CAVEATS

DIAGNOSTICS

BUGS

As this is an ALPHA (experimental) release. As such, there are probably many unknown bugs.

The SS7 LINK interface is not capable of performing PCR (Preventative Cyclic Retransmission) procedures and the ss7_link_pcr sysctl has no effect.

RESTRICTIONS

The SS7 LINK interface does not currently support the concept of dynamic assignment of Signalling Data Terminals as described in ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008. Each Signalling Data Terminal (ss7 device) is bound to a Signalling Data Link (communications path between signalling points).

AUTHOR

OpenSS7, mailto:[email protected].

This man page borrows literally and heavily from the netdevice(7) man page for Linux written by Andi Kleen mailto:[email protected].

HISTORY

OpenSS7 is a kernel module for Linux written for the Linux 2.2 kernel.

REFERENCES

ITU-T Rec. Q.700, Introduction to CCITT Signalling System No. 7,
ITU-T Rec. Q.701, Functional description of the message transfer part (MTP) of Signalling System No. 7,
ITU-T Rec. Q.702, Signalling data link,
ITU-T Rec. Q.703, Signalling link,
ITU-T Rec. Q.704, Signalling network functions and messages

ANSI T1.110, General Information,
ANSI T1.111, Message Transfer Part (MTP)

ETSI ETS 300 008-1, Message Transfer Part (MTP),
ETSI ETS 300 008-2, Message Transfer Part (MTP)


Home Index Prev Next More Download Info FAQ Mail

OpenSS7

OpenSS7,

Copyright 1997-2001, OpenSS7, All Rights Reserved.

Last modified: $Date: 2001/01/07 08:42:52 $