isdnio

Synopsis

Description

ISDN ioctl commands are a subset of ioctl(2) commands that perform
a variety of control functions on Integrated Services Digital Network (ISDN) STREAMS devices.
The arguments command and arg are passed to the file designated by
fd and are interpreted by the ISDN device driver.

fd is an open file descriptor that refers to a stream. command
determines the control function to be performed as described in the IOCTLS
section of this document. arg represents additional information that is needed by command.
The type of arg depends upon the command, but generally it is
an integer or a pointer to a command-specific data structure.

Since these ISDN commands are a subset of ioctl and streamio(7I), they
are subject to errors as described in those interface descriptions.

This set of generic ISDN ioctl commands is meant to control various
types of ISDN STREAMS device drivers. The following paragraphs give some background
on various types of ISDN hardware interfaces and data formats, and other device
characteristics.

Controllers, Interfaces, and Channels

This manual page discusses operations on, and facilities provided by ISDN controllers,
interfaces and channels. A controller is usually a hardware peripheral device that
provides one or more ISDN interfaces and zero or more auxiliary interfaces.
In this context, the term interface is synonymous with the term “port”. Each
interface can provide one or more channels.

Time Division Multiplexed Serial Interfaces

ISDN BRI-TE, BRI-NT, and PRI interfaces are all examples of Time Division
Multiplexed Serial Interfaces. As an example, a Basic Rate ISDN (BRI) Terminal
Equipment (TE) interface provides one D-channel and two B-channels on the same
set of signal wires. The BRI interface, at the S reference point, operates
at a bit rate of 192,000 bits per second. The bits are
encoded using a pseudoternary coding system that encodes a logic one as
zero volts, and a logic zero as a positive or negative voltage.
Encoding rules state that adjacent logic zeros must be encoded with opposite
voltages. Violations of this rule are used to indicate framing information such that
there are 4000 frames per second, each containing 48 bits. These 48
bits are divided into channels. Not including framing and synchronization bits, the
frame is divided into 8 bits for the B1-channel, 1 bit for
the D-channel, 8 bits for B2, 1 bit for D, 8 bits for
B1, 1 bit for D, and 8 bits for B2. This results
in a 64,000 bps B1-channel, a 64,000 bps B2-channel, and a 16,000
bps D-channel, all on the same serial interface.

Basic Rate ISDN

A Basic Rate ISDN (BRI) interface consists of a 16000 bit per
second Delta Channel (D-channel) for signaling and X.25 packet transmission, and two
64000 bit per second Bearer Channels (B-channels) for transmission of voice or
data.

The CCITT recommendations on ISDN Basic Rate interfaces, I.430, identify several “reference
points” for standardization. From (Stallings89): Reference point T (terminal) corresponds to a
minimal ISDN network termination at the customer's premises. It separates the network
provider's equipment from the user's equipment. Reference point S (system) corresponds to the
interface of individual ISDN terminals. It separates user terminal equipment from network-related
communications functions. Reference point R (rate) provides a non-ISDN interface between user
equipment that is not ISDN-compatible and adaptor equipment. . . . The final reference point
. . . is reference point U (user). This interface describes the full-duplex data
signal on the subscriber line.

Some older technology components of some ISDN networks occasionally steal the low
order bit of an ISDN B-channel octet in order to transmit in-band
signaling information between switches or other components of the network. Even when
out-of-band signaling has been implemented in these networks, and the in-band signaling is
no longer needed, the bit-robbing mechanism may still be present. This bit
robbing behavior does not appreciably affect a voice call, but it will
limit the usable bandwidth of a data call to 56000 bits per
second instead of 64000 bits per second. These older network components only seem
to exist in the United States of America, Canada and Japan. ISDN
B-channel data calls that have one end point in the United States,
Canada or Japan may be limited to 56000 bps usable bandwidth instead
of the normal 64000 bps. Sometimes the ISDN service provider may be
able to supply 56kbps for some calls and 64kbps for other calls. On
an international call, the local ISDN service provider may advertise the call
as 64kbps even though only 56kbps are reliably delivered because of bit-robbing
in the foreign ISDN that is not reported to the local switch.

A Basic Rate Interface implements either a Terminal Equipment (TE) interface or
a Network Termination (NT) interface. TE's can be ISDN telephones, a Group
4 fax, or other ISDN terminal equipment. A TE connects to an
NT in order to gain access to a public or private ISDN
network. A private ISDN network, such as provided by a Private Branch Exchange
(PBX), usually provides access to the public network.

If multi-point configurations are allowed by an NT, it may be possible
to connect up to eight TE's to a single NT interface. All
of the TE's in a multipoint configuration share the same D and
B-channels. Contention for B-Channels by multiple TEs is resolved by the ISDN
switch (NT) through signaling protocols on the D-channel.

Contention for access to the D-channel is managed by a collision detection
and priority mechanism. D-channel call control messages have higher priority than other
packets. This media access function is managed at the physical layer.

A BRI-TE interface may implement a “Q-channel”, the Q-channel is a slow
speed, 800 bps, data path from a TE to an NT. Although
the structure of the Q-channel is defined in the I.430 specification, the
use of the Q-channel is for further study.

A BRI-NT interface may implement an “S-channel”, the S-channel is a slow
speed, 4000 bps, data path from a NT to an TE. The
use of the S-channel is for further study.

Primary Rate ISDN

Primary Rate ISDN (PRI) interfaces are either 1.544Mbps (T1 rate) or 2.048Mbps
(E1 rate) and are typically organized as 23 B-channels and one D-Channel
(23B+D) for T1 rates, and 30 B-Channels and one D-Channel (30B+D) for
E1 rates. The D-channels on a PRI interface operate at 64000 bits per
second. T1 rate PRI interface is the standard in the United States,
Canada and Japan while E1 rate PRI interface is the standard in
European countries. Some E1 rate PRI interface implementations allow access to channel
zero which is used for framing.

Channel Types

ISDN channels fall into several categories; D-channels, bearer channels, and management pseudo
channels. Each channel has a corresponding device name somewhere under the directory
/dev/isdn/ as documented in the appropriate hardware specific manual page.

D-channels

There is at most one D-channel per ISDN interface. The D-channel carries signaling information for the management of ISDN calls and can also carry X.25 packet data. In the case of a PRI interface, there may actually be no D-channel if Non-Facility Associated Signaling is used. D-channels carry data packets that are framed and checked for transmission errors according to the LAP-D protocol. LAP-D uses framing and error checking identical to the High Speed Data Link (HDLC) protocol.

B-channels

BRI interfaces have two B-channels, B1 and B2. On a BRI interface, the only other type of channel is an H-channel which is a concatenation of the B1 and B2 channels. An H-channel is accessed by opening the “base” channel, B1 in this case, and using the ISDN_SET_FORMAT ioctl to change the configuration of the B-channel from 8-bit, 8 kHz to 16-bit, 8kHz.

On a primary rate interface, B channels are numbered from 0 to 31 in Europe and 1 to 23 in the United States, Canada and Japan.

H-Channels

A BRI or PRI interface can offer multiple B-channels concatenated into a single, higher bandwidth channel. These concatenated B-channels are referred to as an “H-channels” on a BRI interface. The PRI interface version of an H-channel is referred to as an Hn-channels where n is a number indicating how the B-channels have been aggregated into a single channel.

A T1 PRI interface H11 channel is 1536 kbps (24×64000bps). This will consume the channel normally reserved for the D-channel, so signaling must be done with Non-Facility Associated Signaling (NFAS) from another PRI interface.

An E1 PRI interface H12 channel is 1920 kbps (30×64000bps). An H12-channel leaves room for the framing-channel as well as the D-channel.

Auxiliary channels

Auxiliary channels are non-ISDN hardware interfaces that are closely tied to the ISDN interfaces. An example would be a video or audio coder/decoder (codec). The existence of an auxiliary channel usually implies that one or more B-channels can be “connected” to an auxiliary interface in hardware.

Management pseudo-channels

A management pseudo-channel is used for the management of a controller, interface, or hardware channel. Management channels allow for out-of-band control of hardware interfaces and for out-of-band notification of status changes. There is at least one management device per hardware interface.

There are three different types of management channels implemented by ISDN hardware drivers:

A controller management device handles all ioctls that simultaneously affect hardware channels on different interfaces. Examples include resetting a controller, mu-code (as in the Greek letter mu) downloading of a controller, or the connection of an ISDN B-channel to an auxiliary channel that represents an audio coder/decoder (codec). The latter case would be accomplished using the ISDN_SET_CHANNEL ioctl.

An interface management device handles all ioctls that affect multiple channels on the same interface. Messages associated with the activation and deactivation of an interface arrive on the management device associated with the D channel of an ISDN interface.

Auxiliary interfaces may also have management devices. See the hardware specific man pages for operations on auxiliary devices.

Trace pseudo-channels

A device driver may choose to implement a trace device for a data or management channel. Trace channels receive a special M_PROTO header with the original channel's original M_PROTO or M_DATA message appended to the special header. The header is described by:

ISDN Channel types

The isdn_chan_t type enumerates the channels available on ISDN interfaces. If a
particular controller implements any auxiliary channels then those auxiliary channels will be
described in a controller specific manual page. The defined channels are described by
the isdn_chan_t type as shown below:

Activation and Deactivation of ISDN Interfaces

The management device associated with an ISDN D-channel is used to request
activation, deactivation and receive information about the activation state of the interface.
See the descriptions of the ISDN_PH_ACTIVATE_REQ and ISDN_MPH_DEACTIVATE_REQ ioctls. Changes in the activation
state of an interface are communicated to the D-channel application through M_PROTO
messages sent up-stream on the management device associated with the D-channel. If
the D-channel protocol stack is implemented as a user process, the user
process can retrieve the M_PROTO messages using the getmsg(2) system call.

ioctls

STREAMS IOCTLS

All of the streamio(7I)ioctl commands may be issued for a device
conforming to the the isdnio interface.

ISDN interfaces that allow access to audio data should implement a reasonable
subset of the audio(7I) interface.

ISDN ioctls

ISDN_PH_ACTIVATE_REQ

Request ISDN physical layer activation. This command is valid for both TE and NT interfaces. fd must be a D-channel file descriptor. arg is ignored.

TE activation will occur without use of the ISDN_PH_ACTIVATE_REQ ioctl if the device corresponding to the TE D-channel is open, “on”, and the ISDN switch is requesting activation.

ISDN_MPH_DEACTIVATE_REQ

fd must be an NT D-channel file descriptor. arg is ignored.

This command requests ISDN physical layer de-activation. This is not valid for TE interfaces. A TE interace may be turned off by use of the ISDN_PARAM_POWER command or by close(2) on the associated fd.

ISDN_ACTIVATION_STATUS

fd is the file descriptor for a D-channel, the management device associated with an ISDN interface, or the management device associated with the controller. arg is a pointer to an isdn_activation_status_t structure. Although it is possible for applications to determine the current activation state with this ioctl, a D-channel protocol stack should instead process messages from the management pseudo channel associated with the D-channel.

The type field should be set to ISDN_TYPE_SELF. The device specific interface type will be returned in the type field.

The isdn_activation_status_t structure contains the interface type and the current activation state. type is the interface type and should be set by the caller to ISDN_TYPE_SELF.

ISDN_INTERFACE_STATUS

The ISDN_INTERFACE_STATUS ioctl retrieves the status and statistics of an ISDN interface. The requesting channel must own the interface whose status is being requested or the ioctl will fail. fd is the file descriptor for an ISDN interface management device. arg is a pointer to a struct isdn_interface_info. If the interface field is set to ISDN_TYPE_SELF, it will be changed in the returned structure to reflect the proper device-specific interface of the requesting fd.

The ISDN_CHANNEL_STATUS ioctl retrieves the status and statistics of an ISDN channel. The requesting channel must own the channel whose status is being requested or the ioctl will fail. fd is any file descriptor. arg is a pointer to a struct isdn_channel_info. If the interface field is set to ISDN_CHAN_SELF, it will be changed in the returned structure to reflect the proper device-specific channel of the requesting fd.

fd is the file descriptor for a management device. arg is a pointer to a struct isdn_param. This command allows the setting of various ISDN physical layer parameters such as timers. This command uses the same arguments as the ISDN_PARAM_GETcommand.

ISDN_PARAM_GET

fd is the file descriptor for a management device. arg is a pointer to a structisdn_param This command provides for querying the value of a particular ISDN physical layer parameter.

If an implementation provides power on and off functions, then power should be on by default. If flag is ISDN_PARAM_POWER_OFF then a TE interface is forced into state F0, NT interfaces are forced into state G0. If flag is ISDN_PARAM_POWER_ON then a TE interface will immediately transition to state F3 when the TE D-channel is opened. If flag is one, an NT interface will transition to state G1 when the NT D-channel is opened.

Implementations that do not provide ISDN_POWER return failure with errno set to ENXIO.ISDN_POWER is different from ISDN_PH_ACTIVATE_REQ since CCITT specification requires that if a BRI-TE interface device has power, then it permits activation.

ISDN_PARAM_NT_T101

This parameter accesses the NT timer value T1. The CCITT recommendations specify that timer T1 has a value from 5 to 30 seconds. Other standards may differ.

ISDN_PARAM_NT_T102

This parameter accesses the NT timer value T2. The CCITT recommendations specify that timer T2 has a value from 25 to 100 milliseconds. Other standards may differ.

ISDN_PARAM_TE_T103

This parameter accesses the TE timer value T3. The CCITT recommendations specify that timer T3 has a value from 5 to 30 seconds. Other standards may differ.

ISDN_PARAM_TE_T104

This parameter accesses the TE timer value T4. The CTS2 specifies that timer T4 is either not used or has a value from 500 to 1000 milliseconds. Other standards may differ. CTS2 requires that timer T309 be implemented if T4 is not available.

ISDN_PARAM_MAINT

This parameter sets the multi-framing mode of a BRI-TE interface. For normal operation this parameter should be set to ISDN_PARAM_MAINT_ECHO. Other uses of this parameter are dependent on the definition and use of the BRI interface S and Q channels.

ISDN_PARAM_ASMB

There are a few differences in the BRI-TE interface activation state machine standards. This parameter allows the selection of the appropriate standard. At this time, only ISDN_PARAM_TE_ASMB_CCITT88 and ISDN_PARAM_TE_ASMB_CTS2 are available.

ISDN_PARAM_PAUSE

This parameter allows a management device to pause the IO on a B-channel. pause.channel is set to indicate which channel is to be paused or un-paused. pause.paused is set to zero to un-pause and one to pause. fd is associated with an ISDN interface management device. arg is a pointer to a struct isdn_param.

ISDN_SET_LOOPBACK

fd is the file descriptor for an ISDN interface's management device. arg is a pointer to an isdn_loopback_request_t structure.

arg is a pointer to an isdn_loopback_request_t structure. ISDN_RESET_LOOPBACK turns off the selected loopback modes.

ISDN Data Format

The isdn_format_t type is meant to be a complete description of the
various data modes and rates available on an ISDN interface. Several macros
are available for setting the format fields. The isdn_format_t structure is shown
below:

ISDN Datapath Types

Every STREAMS stream that carries data to or from the ISDN serial
interfaces is classified as a channel-stream datapath. A possible ISDN channel-stream datapath
device name for a TE could be /dev/isdn/0/te/b1.

On some hardware implementations, it is possible to route the data from
hardware channel to hardware channel completely within the chip or controller. This
is classified as a channel-channel datapath. There does not need to be
any open file descriptor for either channel in this configuration. Only when data
enters the host and utilizes a STREAMS stream is this classified as
an ISDN channel-stream datapath.

ISDN Management Stream

A management stream is a STREAMS stream that exists solely for control
purposes and is not intended to carry data to or from the
ISDN serial interfaces. A possible management device name for a TE could
be /dev/isdn/0/te/mgt.

Channel Management IOCTLS

The following ioctls describe operations on individual channels and the connection of
multiple channels.

ISDN_SET_FORMAT

fd is a data channel, the management pseudo-channel associated with the data channel, or the management channel associated with the data channel's interface or controller. arg is a pointer to a struct isdn_format_req. The ISDN_SET_FORMAT ioctl sets the format of an ISDN channel-stream datapath. It may be issued on both an open ISDN channel-stream datapath Stream or an ISDN Management Stream. Note that an open(2) call for a channel-stream datapath will fail if an ISDN_SET_FORMAT has never been issued after a reset, as the mode for all channel-stream datapaths is initially biased to ISDN_MODE_NOTSPEC.arg is a pointer to an ISDN format type (isdn_format_req_t*).

If there is not an open channel-stream datapath for a requested channel, the default format of that channel will be set for a subsequent open(2).

To modify the format of an open stream, the driver will disconnect the hardware channel, flush the internal hardware queues, set the new default configuration, and finally reconnect the data path using the newly specified format. Upon taking effect, all state information will be reset to initial conditions, as if a channel was just opened. It is suggested that the user flush the interface as well as consult the hardware specific documentation to insure data integrity.

If a user desires to connect more than one B channel, such as an H-channel, the B-channel with the smallest offset should be specified, then the precision should be specified multiples of 8. For an H-channel the precision value would be 16. The user should subsequently open the base B-channel. If any of the sequential B-channels are busy the open will fail, otherwise all of the B-channels that are to be used in conjunction will be marked as busy.

The ISDN_SET_CHANNEL ioctl sets up a data connection within an ISDN controller. The ISDN_SET_CHANNELioctl can only be issued from an ISDN management stream to establish or modify channel-channel datapaths. The ioctl parameter arg is a pointer to an ISDN connection request (isdn_conn_req_t*). Once a data path is established, data flow is started as soon as the path endpoints become active. Upon taking effect, all state information is reset to initial conditions, as if a channel was just opened.

The isdn_conn_req_t structure is shown below. The five fields include the receive and transmit ISDN channels, the number of directions of the data path, as well as the data format. The reserved field must always be set to zero.

To specify a read-only, write-only, or read-write path, or to disconnect a path, the dir field should be set to ISDN_PATH_ONEWAY, ISDN_PATH_TWOWAY, and ISDN_PATH_DISCONNECT respectively. To modify the format of a channel-channel datapath, a user must disconnect the channel and then reconnect with the desired format.

The ISDN_GET_FORMAT ioctl gets the ISDN data format of the channel-stream datapath described by fd. arg is a pointer to an ISDN data format request type (isdn_format_req_t*). ISDN_GET_FORMAT can be issued on any channel to retrieve the format of any channel it owns. For example, if issued on the TE management channel, the format of any other te channel can be retrieved.

ISDN_GETCONFIG

The ISDN_GETCONFIG ioctl is used to get the current connection status of all ISDN channels associated with a particular management stream. ISDN_GETCONFIG also retrieves a hardware identifier and the generic interface type. arg is an ISDN connection table pointer (isdn_conn_tab_t*). The isdn_conn_tab_t structure is shown below:

The table contains a string which is the interface's unique identification string. The second element of this table contains the ISDN transmit and receive connections and configuration for all possible data paths for each type of ISDN controller hardware. Entries that are not connected will have a value of ISDN_NO_CHAN in the from and to fields. The number of entries will always be ISDN_MAX_CHANS, and can be referenced in the hardware specific implementation documentation. An isdn_conn_tab_t structure is allocated on a per controller basis.