OpenSS7: STREAMS Design

SS7 devices have characteristics (primarily at Level 1) which are not specified in the SS7 specifications. An example of this are the leads of V.35 interface and the carrier alarms of the T1 interface.

SS7 devices under OpenSS7 provide a common device interface (DEVI) which provides for control of these device characteristics which are outside of the SS7 specification but which must be performed on real devices to make for a practical system.

SS7 devices which conform to this Device Interface (DEVI) do not provide a full range of services. On the other hand, the Signalling Data LInk (SDL) and Signalling Data Terminal (SDT) drivers implement this device interface in addition to the protocol interfaces.

Model

SS7 devices which provide the DEVI are the SDL/SDT drivers described here. The mechanism which is used for the interface is the ioctl(2) or the streamio(2) library calls on a stream head.

Services

The Device Interface (DEVI) does not provide any protocol services but merely provides a mechanism to control characteristics of the device which are outside the scope of the protocol.

Primitives

The Device Interface (DEVI) is modelled after the ioctl(2) interface and provides the ability to get, set, clear and perform other functions on configuration parameters and variables of the device structure. The Device Interface (DEVI) provides the following IOCTLs:

Input Output Controls

Becuase it does not provide any protocol services, there are not specific sequences that must be observed in the Device Interface (DEVI). The only ordering which might need to be respected is that the device should be configurated for operation with these controls before the device is enabled for protocol data transfer and operations. Nevertheless, some devices might be capable of performing changes to a number of these characteristics while the device is operational and with necessarily disrupting the integrity of any given signalling link.

Implementation

Header File

/*****************************************************************************

 @(#) $Id: devi_ioctl.h,v 0.7.8.1 2001/12/11 13:16:04 brian Exp $

 -----------------------------------------------------------------------------

     Copyright (C) 1997-2001 OpenSS7 Corporation.  All Rights Reserved.


                                  PUBLIC LICENSE

     This license is provided without fee, provided that the above copy-
     right 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.

 -----------------------------------------------------------------------------

 U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software on
 behalf of the U.S. Government ("Government"), the following provisions apply
 to you.  If the Software is supplied by the Department of Defense ("DoD"), it
 is classified as "Commercial Computer Software" under paragraph 252.227-7014
 of the DoD Supplement to the Federal Acquisition Regulations ("DFARS") (or any
 successor regulations) and the Government is acquiring only the license rights
 granted herein (the license rights customarily provided to non-Government
 users).  If the Software is supplied to any unit or agency of the Government
 other than DoD, it is classified as "Restricted Computer Software" and the
 Government's rights in the Software are defined in paragraph 52.227-19 of the
 Federal Acquisition Regulations ("FAR") (or any success regulations) or, in
 the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the FAR
 (or any successor regulations).

 -----------------------------------------------------------------------------

 Last Modified $Date: 2001/12/11 13:16:04 $ by $Author: brian $

 *****************************************************************************/

#ifndef __DEVI_IOCTL_H__
#define __DEVI_IOCTL_H__

#ident "@(#) $Name:  $($Revision: 0.7.8.1 $) Copyright (c) 1997-2001 OpenSS7 Corporation."

#include <linux/ioctl.h>
#include <asm/spinlock.h>

#define DEV_IOC_MAGIC 'v'

/*
 *  DEVICE CONFIGURATION
 */

struct sdl;

#ifdef __KERNEL__

typedef struct dev_device {
    spinlock_t  iflock;     /* interface lock   */
    dev_ulong   ifflags;    /* interface flags  */
    dev_ulong   iftype;     /* interface type   */
    dev_ulong   ifgtype;    /* group type       */
    dev_ulong   ifmode;     /* interface mode   */
    dev_ulong   ifrate;     /* interface rate   */
    dev_ulong   ifclock;    /* interface clock  */
    dev_ulong   ifcoding;   /* interface coding */
    dev_ulong   ifleads;    /* interface leads  */
    dev_ulong   ifindex;    /* interface index  */
    dev_ulong   irq;        /* interrupt        */
    dev_ulong   iobase;     /* i/o base address */
    dev_ulong   dma_rx;     /* dma receive      */
    dev_ulong   dma_tx;     /* dma transmit     */
} dev_device_t;

#endif

#define DEV_IOCCIFRESET   _IO(  DEV_IOC_MAGIC,  0 )

#define DEV_IOCGIFFLAGS   _IOW( DEV_IOC_MAGIC,  1, dev_ulong )
#define DEV_IOCSIFFLAGS   _IOW( DEV_IOC_MAGIC,  2, dev_ulong )

#define DEV_IF_UP            0x00000001  /* device should set on enable  */
#define DEV_IF_RX_RUNNING    0x00000002  /* when Rx running              */
#define DEV_IF_TX_RUNNING    0x00000004  /* when Tx running              */
#define DEV_IF_SU_COMPRESS   0x00000008  /* when Rx compressing          */

#define DEV_IOCGIFTYPE    _IOR( DEV_IOC_MAGIC,  3, dev_ulong )
#define DEV_IOCSIFTYPE    _IOW( DEV_IOC_MAGIC,  4, dev_ulong )

enum {
    DEV_TYPE_NONE,
    DEV_TYPE_V35,
    DEV_TYPE_DS0,
    DEV_TYPE_DS0A,
    DEV_TYPE_E1,
    DEV_TYPE_T1,
    DEV_TYPE_J1,
    DEV_TYPE_ATM,
    DEV_TYPE_PACKET
};

#define DEV_IOCGGRPTYPE   _IOR( DEV_IOC_MAGIC,  5, dev_ulong )
#define DEV_IOCSGRPTYPE   _IOW( DEV_IOC_MAGIC,  6, dev_ulong )

enum {
    DEV_GTYPE_NONE,
    DEV_GTYPE_T1,
    DEV_GTYPE_E1,
    DEV_GTYPE_J1,
    DEV_GTYPE_ATM,
    DEV_GTYPE_ETH,
    DEV_GTYPE_IP,
    DEV_GTYPE_UDP,
    DEV_GTYPE_TCP,
    DEV_GTYPE_RTP,
    DEV_GTYPE_SCTP
};

#define DEV_IOCGIFMODE    _IOR( DEV_IOC_MAGIC,  7, dev_ulong )
#define DEV_IOCSIFMODE    _IOW( DEV_IOC_MAGIC,  8, dev_ulong )

enum {
    DEV_MODE_NONE,
    DEV_MODE_DSU,
    DEV_MODE_CSU,
    DEV_MODE_DTE,
    DEV_MODE_DCE,
    DEV_MODE_CLIENT,
    DEV_MODE_SERVER,
    DEV_MODE_PEER,
    DEV_MODE_ECHO,
    DEV_MODE_REM_LB,
    DEV_MODE_LOC_LB,
    DEV_MODE_LB_ECHO,
    DEV_MODE_TEST
};

#define DEV_IOCGIFRATE    _IOR( DEV_IOC_MAGIC,  9, dev_ulong )
#define DEV_IOCSIFRATE    _IOW( DEV_IOC_MAGIC, 10, dev_ulong )

#define DEV_IOCGIFCLOCK   _IOR( DEV_IOC_MAGIC, 11, dev_ulong )
#define DEV_IOCSIFCLOCK   _IOW( DEV_IOC_MAGIC, 12, dev_ulong )

enum {
    DEV_CLOCK_NONE,
    DEV_CLOCK_INT,
    DEV_CLOCK_EXT,
    DEV_CLOCK_LOOP,
    DEV_CLOCK_MASTER,
    DEV_CLOCK_SLAVE,
    DEV_CLOCK_DPLL,
    DEV_CLOCK_ABR,
    DEV_CLOCK_SHAPER,
    DEV_CLOCK_TICK
};

#define DEV_IOCGIFCODING  _IOR( DEV_IOC_MAGIC, 13, dev_ulong )
#define DEV_IOCSIFCODING  _IOW( DEV_IOC_MAGIC, 14, dev_ulong )

enum {
    DEV_CODING_NONE,
    DEV_CODING_NRZ,
    DEV_CODING_NRZI,
    DEV_CODING_AMI,
    DEV_CODING_B6ZS,
    DEV_CODING_B8ZS,
    DEV_CODING_ESF,     /* FIXME: this is actually a framing value */
    DEV_CODING_AAL1,
    DEV_CODING_AAL2,
    DEV_CODING_AAL5
};

#define DEV_IOCGIFLEADS   _IOR( DEV_IOC_MAGIC, 15, dev_ulong )
#define DEV_IOCSIFLEADS   _IOW( DEV_IOC_MAGIC, 16, dev_ulong )
#define DEV_IOCCIFLEADS   _IOW( DEV_IOC_MAGIC, 17, dev_ulong )

enum {
    DEV_LEAD_DTR = 0x01,    /* for V.35 DTR lead set or clr */
    DEV_LEAD_RTS = 0x02,    /* for V.35 RTS lead set or clr */
    DEV_LEAD_DCD = 0x04,    /* for V.35 DCD lead get */
    DEV_LEAD_CTS = 0x08,    /* for V.35 CTS lead get */
    DEV_LEAD_DSR = 0x10     /* for V.35 DSR lead get */
};

#define DEV_IOCCDISCTX    _IO(  DEV_IOC_MAGIC, 18 )
#define DEV_IOCCCONNTX    _IO(  DEV_IOC_MAGIC, 19 )

#define DEV_IOC_FIRST    0
#define DEV_IOC_LAST    19
#define DEV_IOC_PRIVATE 32

#endif  __DEVI_IOCTL_H__

Overview	- A brief overview of the Device Interface.
Model	- The model of a Device.
Services	- Services provided at the Device Interface.
Primitives	- Primitives described at the Device Interface.
Sequences	- Allowed sequences of primitives and interface state transitions.
Implementation	- Considerations for implementation of drivers using the Device Interface.
Header File	- A header file which provides definitions for the Device Interface.

`DEV_IOCGIFTYPE DEV_IOCSIFTYPE`	Gets or sets the interface type. There are a number of interface types which are supported by SS7 and in particular OpenSS7.
`DEV_IOCGGRPTYPE DEV_IOCSGRPTYPE`	Gets or sets the interface group type. Often, the actual channel that is used for the SS7 link is only one channel of a larger group of channels. Some interfaces support multiple channels and this characteristic of the device is used to change or examine the type of group to which the current link belongs. Often this would be a DS0 channel which is actually part of a T1/E1/J1 span.
`DEV_IOCGIFMODE DEV_IOCSIFMODE`	Gets or sets the mode of the interface. Many interfaces are capable of operating in a number of modes. V.35 interfaces can be configured as DCE (Data Control Equipment) or DTE (Data Terminal Equipment). This characteristic of the deivce is used to change or examine the mode of the current link interface. Often this would be CSU/DSU, DTE/DCE, or client/server in some packet arrangements.
`DEV_IOCGIFCLOCK DEV_IOCSIFCLOCK`	Gets or sets the clocking associated with the interface. A number of interface types, being synchronous interfaces, have options on the source which is used to derive the clocking for the synchronous interface. For example, V.35 interfaces are often configured for internal or external clocking independent of whether the interface is a DCE or DTE interface. T1 carriers have differing clocking modes which are essentially master, slave or loop modes. Some interfaces and interface cards have the ability to regenerate clocks using Digital Phase Locked Loops. These are provided for in this characteristic of the device.
`DEV_IOCGIFCODING DEV_IOCSIFCODING`	Gets or sets the bit coding associated with the interface. A number of interface types can utilize differing line coding which is independent of the information being carried over the channel. Synchronous interfaces such as V.35 are capable of NRZ, NRZI, Manchester and other codings. T1 interfaces are capable of AMI, B8ZS and other codings which do not affect the information being carried, just the format of the bit coding on the line. This characteristic of the device provdes for changing the line coding on devices which are capable of making the change and provides for determining which coding is being used in any case.
`DEV_IOCGIFLEADS DEV_IOCSIFLEADS DEV_IOCCIFLEADS`	Gets, sets or clears control leads associated with the interface. A number of interfaces (such as V.35) have control leads which must be set or cleared outside of the SS7 protocol, but without which the interface will not be usable. V.35 is an example of this with particular regard to the CTS, DTR, DCD and RTS leads. It is possible to establish these leads at the proper levels using special cables and jumpers; however, this characteristic provides the ability to change the leads under software control on those interfaces which require and support it.
`DEV_IOCCDISCTX DEV_IOCCCONNTX`	Disconnects and connects the transmit path on the interface. This is required only for automated conformance testing per Q.781. Q.781 has a number of tests where the Tx path must be disconnected and then reconnected. This control affords the same capability on interfaces which support it so that a physical action is not necessary to perform the disconnection and reconnection.

STREAMS Design

Device (DEV) Interface