DEVI(7)

NAME
devi - Signalling System No. 7 Device (DEV) Interface

SYNOPSIS
#include <ss7/devi.h>
#include <ss7/devi_ioctl.h>

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

DESCRIPTION

This man page describes the STREAMS interface which is used to configure and exchanged data with an SS7 Device (DEVI) for all SS7 devices conforming to the OpenSS7 Device Interface (DEVI) specification.

DEVI drivers implement this interface in addition to the sdli(7) or sdti(7) interface at the driver level. These are driver specific ioctls which are used to configure a wide ranges of devices.

The DEVI interface consists of only a control interface which is utilizes ioctl(2) tranparent calls or an I_STR ioctl from streamio(2) from a stream head to the driver. Devices may also be controlled from the stream head of a slsi(7) or mtpi(7) stream head using ioctl(2) or I_STR ioctl from streamio(2). This later method uses a pass-along ioctl which passes the device control through the multiplexor to a specified device. (See slsi(7) and mtpi(7).) The control interface controls specific aspects of the device driver which are outside the scope of the SS7 protocol. These controls are normally used by the SS7 Configuration Daemon ss7d(8) on the driver interface or multiplexor control channel before or after the protocol stack has been assembled. This control interface is described below. IOCTLs are used to affect the operation of the SS7 device. A common set of IOCTLs are available for all SS7 devices as follows:

DEV_IOCGIFTYPE, DEV_IOCSIFTYPE
    Gets or sets the value of the interface type. The interface type is the type of interface to which the stream device is connected (attached). arg is a pointer to a dev_ulong which contains one of the following values:

    DEV_TYPE_NONE | There is no device type (default) or the device type is not meaningful.
    DEV_TYPE_V35 | A V.35 interface.
    DEV_TYPE_DS0 | A DS0 interface.
    DEV_TYPE_DS0A | A DS0A interface.
    DEV_TYPE_E1 | A (full) E1 interface.
    DEV_TYPE_T1 | A (full) T1 interface.
    DEV_TYPE_J1 | A (full) J1 interface.
    DEV_TYPE_ATM | An ATM interface.
    DEV_TYPE_PACKET | A generic packet interface.

DEV_IOCGGRPTYPE, DEV_IOCSGRPTYPE
    Gets or sets the value of the interface group type. The interface group type is the type of the group of communications channels, to a channel of which the stream is attached. Interface groups are only meaningful (or required) for Style 2 drivers which must be explicitly attached to a channel within the group. Style 1 drivers (with implicit attachment at open) should be specified as DEV_GTYPE_NONE. arg is a pointer to a dev_ulong which contains one of the following values:

    DEV_GTYPE_NONE | There is no group type (default) or the group type is not meaningful (i.e., there is no group but a single channel).
    DEV_GTYPE_T1 | A channel of a T1 interface.
    DEV_GTYPE_E1 | A channel of a E1 interface.
    DEV_GTYPE_J1 | A channel of a J1 interface.
    DEV_GTYPE_ATM | A channel of an ATM interface.
    DEV_GTYPE_ETH | A subset of an Ethernet interface.
    DEV_GTYPE_IP | A subset of an IP interface.
    DEV_GTYPE_UDP | A port of a UDP interface.
    DEV_GTYPE_TCP | A port of a TCP interface.
    DEV_GTYPE_RTP | A port of an RTP interface.
    DEV_GTYPE_SCTP | A port of an SCTP interface.

DEV_IOCGIFMODE, DEV_IOCSIFMODE
    Gets or sets the interface mode. Most interfaces can be in one of two modes depending on the side of the interface to which the device is attached. Setting this value may have an impact on the valid ranges of other interface values (such as clocking mode). arg is a pointer to a dev_ulong which contains one of the following values:

    DEV_MODE_NONE | The interface is modeless or the mode is unspecified.
    DEV_MODE_DSU | Data Service Unit mode.
    DEV_MODE_CSU | Control Service Unit mode.
    DEV_MODE_DTE | Data Terminal Equipment mode.
    DEV_MODE_DCE | Control Terminal Equipment mode.
    DEV_MODE_CLIENT | Client mode.
    DEV_MODE_SERVER | Server mode.
    DEV_MODE_PEER | Peer to peer mode.
    DEV_MODE_ECHO | Local echo mode.
    DEV_MODE_REM_LB | Remote loopback mode.
    DEV_MODE_LOC_LB | Local loopback mode.
    DEV_MODE_LB_ECHO | Loopback and echo mode.
    DEV_MODE_TEST | Test mode.

DEV_IOCGIFCLOCK, DEV_IOCSIFCLOCK
    Get or set the interface clocking. Most interfaces can be in one of several clocking modes. Not all clocking modes apply to all interface types. Different interface and interface group types may have different default values regarding clock modes. arg is a pointer to a dev_ulong which contains one of the following values:

    DEV_CLOCK_NONE | No interface clock.
    DEV_CLOCK_INT | Internal clocking.
    DEV_CLOCK_EXT | External clocking.
    DEV_CLOCK_LOOP | Loop clocking.
    DEV_CLOCK_MASTER | Master clock.
    DEV_CLOCK_SLAVE | Slave.
    DEV_CLOCK_DPLL | Digital Phase Locked Loop.
    DEV_CLOCK_ABR | Average Bit Rate.
    DEV_CLOCK_SHAPER | Traffic shaped to an effective clock rate.

DEV_IOCGIFCODING, DEV_IOCSIFCODING
    Gets or sets the interface bit coding. Most interfaces can apply one of several bit line coding. Some interface and interface group types do not permit bit codings to be changed. Not all bit codings are permitted on all interface types. Interface types which have implicit bit codings should be set to either the appropriate coding or to DEV_CODING_NONE. arg is a pointer to a dev_uong which contains one of the following values:

    DEV_CODING_NONE | No coding. Coding unspecified.
    DEV_CODING_NRZ | Non-Return to Zero
    DEV_CODING_NRZI | Non-Return to Zero Inverted
    DEV_CODING_AMI | AMI coding (especially applicable to T1/E1/J1)
    DEV_CODING_B6ZS | B6ZS coding (especially applicable to T1/E1/J1)
    DEV_CODING_B8ZS | B8ZS coding (especially applicable to T1/E1/J1)
    DEV_CODING_ESF | Extended Super Frame coding (especially applicable to T1/E1/J1)
    DEV_CODING_AAL1 | ATM Adaptation Layer 1 coding
    DEV_CODING_AAL2 | ATM Adaptation Layer 2 coding
    DEV_CODING_AAL5 | ATM Adaptation Layer 5 coding

DEV_IOCGIFLEADS, DEV_IOCSIFLEADS, DEV_IOCCIFLEADS
    Gets or sets one or more leads according to a bitmask. The interface lead is only applicable to interface types which support these leads. This control permits the configuration manager or user to control interface leads which are outside the scope of the SS7 protocol. arg is a point to a bit mask of leads to set or clear and is a bitwise OR of one of the following bitmasks:

    DEV_LEAD_DTR | Data-Terminal-Ready
    DEV_LEAD_RTS | Request-To-Send
    DEV_LEAD_DCD | Data-Carrier-Detect
    DEV_LEAD_CTS | Clear-To-Send
    DEV_LEAD_DSR | Data-Set-Ready

DEV_IOCCDISCTX, DEV_IOCCCONNTX
    Diconnects or connects the transmit path. This is specifically to assist with Q.781 conformance testing of Level 2 implementations. One of the conformance tests in the suite requires that the Tx path be disconnected and reconnected at several points in the test. This control is provided to peform that function in an automated fashion rather than having to physically disconnect the link.

Private IOCTLs
    Specific device driver implementations may require additional IOCTLs which are used to configure that particular device. For more information on a particular device IOCTLs, see the appropriate man page for the device.

ERROR HANDLING

When an IOCTL is successful, it returns 0. When it is unsuccessful, it returns -1 and errno is appropriately set. When unsuccessful, no changes will have been made to device parameters or variables.

  Errors

Any of the errors which are returned by ioctl(2) or streamio(2) I_STR can be returned. In addition, the following errors may be returned as a result of the failure of the control operation:

EOPNOTSUPP
    The operation is not supported.

EINVAL
    The value which arg points to is not within the valid range.

EFAULT
    The point arg points outside of the valid address space of the calling user.

EPERM
    The calling process does not have the permission or the capabilities to perform the requested operation.

SEE ALSO

lmi(7), sdli(7), sdti(7), ioctl(2), streamio(2), ss7d(8)

CAVEATS

Not all IOCTLs presented here are supported by all DEVI device drivers. Some values of some members are not applicable to all device drivers. Some device drivers will return an error if an attempt is made to change a value.

AUTHOR

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

HISTORY

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

COPYRIGHT NOTICE

Copyright © 1997-2001 Brian Bidulock. All Rights Reserved. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one Since the Linux kernel and libraries are constantly changing, this manual page may be incorrect or out-of-date. The author(s) assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. The author(s) may not have taken the same level of care in the production of this manual, which is licensed free of charge, as they might when working professionally. Formatted or processed versions of this manual, if unaccompanied by the source, must acknowledge the copyright and authors of this work.