HFC-4s / HFC-8s / HFC-E1 Driver Documentation

HFC-4S / HFC-8S / HFC-E1 Driver Documentation

1. What is what?

The HFC-4S is a single chip controller with 4 S/T interfaces (Basic Rate Interface = BRI). Each interface has two B-channels.

The HFC-8S is a single chip controller with 8 S/T interfaces (Basic Rate Interface = BRI). Each interface has two B-channels.

The HFC-E1 is a single chip controller with one E1 interface (Primary Rate Interface = PRI). The interface has 30 B-channels.

These controllers are designed and produced by Cologne Chip (http://www.colognechip.de).

All of these controllers provide the following features with this driver:

TE-Mode (connecting a port with an ISDN line)
NT-Mode (connecting telephones and other terminals to the port)
Hardware DTMF detection (detection for each B-channel)
Cross connecting of all B-channels on one chip.
Cross connecting between chips using PCM bus. (up to 128 calls)
Conference (up to 8 conferences between all B-channels on one chip)
Simple tone generation (playing tones/patterns with minimum CPU usage)
Silence generation (playing silence (0-level) without CPU usage)

2. Loading kernel module

Note: The “mISDN” modules by Karsten Keil must be compiled and loaded. Follow the instruction on how to load them in the documentation of “mISDN”.

modprobe hfcmulti \

type=<card 1>[,<card 2>[, …]] \

protocol=<interface 1>[,<interface 2>[, …]] \

[layermask=<layermask 1>[,<layermask 2>[, …]]] \

[pcm=<pcm id 1>[,<pcm id 2>[, …]]] \

[poll = 8 | 16 | 32 | 64 | 128 | 256] \

[debug = <flags>]

The “type” is used to define the cards you have installed in your system. The following types are expected:

Value 4 = HFC-4S (4 BRI interfaces)
Value 8 = HFC-8S (8 BRI interfaces)

· Value 1 = HFC-E1 (1 PRI interface)

Optional bits can be given with the “type”:

· Bit 8 = uLaw (instead of aLaw)

· Bit 9 = Enable DTMF detection on all B-channels

· Bit 10 = spare

· Bit 11 = Set PCM bus into slave mode.

· Bit 14 = Use external ram (128K)

· Bit 15 = Use external ram (512K)

· Bit 16 = Use 64 timeslots instead of 32

· Bit 17 = Use 128 timeslots instead of anything else

(all other bits are reserved and shall be 0)

The “protocol” is used to define the interface protocol and modes. Except for the HFC-E1, the card will have more than one interface. The total number of interfaces must match with the card types defined. Example: “type=8,1” will need 9 interfaces to be configured using “protocol”. The “protocol” specified a bit map with the following bits:

· Bit 0-3 = Protocol (value 0x2 = DSS1)

· Bit 4 = NT-Mode (0 = TE, 1 = NT)

· Bit 5 = Point-To-Point-Mode (0 = multipoint, 1 = PTP)

· Bit 6-12 = Reserved (must be 0)

For BRI (HFC-4S / HFC-8S) the following bits are used for interface configuration:

· Bit 16 = Clock synchronization (1 = select synchronization to this interface), see Note[1]

· Bit 17 = Transmitter line setup (1 = capacitive mode, 0 = non capacitive line mode), see Note[2]

· Bit 18 = Disable E-channel (0 = normal operation, 1 = disable/ignore E-channel), the E-channel may be disabled (forced to 0) for NT-Mode and ignored for TE-Mode. Use this only for Point-To-Point configurations. If the E-channel is disabled on the NT-side, the TE-side must ignore the E-channel bits.

· Bit 19-31 = Reserved (must be 0)

For PRI (HFC-E1) the following bits are used for interface configuration:

· Bit 16 = Interface type (0 = normal G.703 copper line interface, 1 = optical interface)

· Bit 17 = Transparent mode (0 = synchronize to frame 0, 1 = transparent mode) (NOT IMPLEMENTED YET)

· Bit 18 = Report LOS (1 = reports “Loss Of Signal” to higher layer)

· Bit 19 = Report AIS (1 = reports “Alarm Indication Signal” to higher layer)

· Bit 20 = Report SLIP (1 = reports jitter buffer underrun/overrun to higher layer)

· Bit 21-22 = Elastic jitter buffer size (0 = default size, 1-3 = size of buffer), see Note[3]

· Bit 23-31 = Reserved (must be 0)

Example:

We assume that there is one HFC-E1 card for external ISDN line, and two HFC-8s card for internal ISDN ports installed. Both use DSS1 (euro ISDN) and a-Law audio data. The E1-Card is connected to a network terminator with electrical G.703 interface. All S0-interfaces shall be run in NT-Mode and multipoint mode in this example. The E1-Interface must run in PTP-Mode since the electrical interface doesn’t support multiple terminals. We need to load the module as specified:

$ modprobe hfcmulti \

type=1,8,8 \

protocol=0x42,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12,0x12

For normal operation you only need to consider about the protocol, NT/TE-Mode, and audio codec (Law-codec). All other mode bits are optionally and have 0 as default values.

3. Other modules:

This driver provides special features for the conference/DTMF/tones module “mISDN_dsp.o”.

The module realize features in software. By using this HFC module, they are supported by hardware. These module is needed in order to use the hardware features, since the HFC module doesn’t provide a general API. Restrictions apply to the following features if they should be realized in hardware. If the Hardware cannot handle the features, they will be substituted by software:

Conferences and cross connections must be connected on the same chip.

· Up to 8 conferences are possible on one chip. On the HFC-E1 a maximum of 24 parties may be in conferences. There is no limit on the number of parties in one conference.

· Volume control is only possible with some special values.

· Mixing of tones with the conference’s sound is not possible. During playing of tones, the party is removed from the conference.

· DTMF tones must be the standard “white box” tone set which is used for telephone’s keypad, in order to be decoded by hardware. DTMF coding is not supported by hardware.

· “Simple” tones use very low CPU cycles due to ring buffers on the chip.

4. References:

The new HiSax driver “mISDN” is required to use this module. The module is part of the driver. Current source for the mISDN driver is: http://www.isdn4linux.de.

This driver is written by Jolly (Andreas Eversberg) (jolly@eversberg.eu) inspired by the “hfc_pci” driver by Werner Cornelius (info@isdn-development.de) and Karsten Keil, and inspired by the Zaptel channel driver by Kapejod (http://www.junghanns.net).

This module and other modules have features developed for the “PBX4Linux” project. They are also designed to be useful in other possible projects. The PBX project’s page is http://isdn.eversberg.eu.

dsp module Documentation

1. What is what?

The module is used to generate tones and patterns, make cross connections, make conferences, decode DTMF and encrypt audio data. Everything is possible in software, but may be realized in hardware if it is supported. In contrast to the user space, it has the following benefits:

Real time processing at kernel space to provide jitter-free audio transfer
Support of a-Law and m-Law audio codecs
DTMF tone generation and decoding
Pattern and tone generation to indicate call state (dialtone, ringing, busy, …)
Cross connection of two parties (transparent interconnection)
Conferences with an unlimited number of parties
A conference will not affect the audio data from/to the party. Audio data from a party, which is in a conference, can be transferred to the user space without the other parties mixed to it. Audio data to a party, which is in a conference, can be transmitted to the user without the other parties hearing it.
Volume control of the transmit and receive audio stream (hardware interface side)
Support of multiple I/O HFC chips (HFC-4S / HFC-8S / HFC-E1) to provide hardware conference, cross connections, DTMF detection and sample-loops.
Blowfish encryption using a special codec to synchronize data blocks.

2. Loading kernel module

Note: The module can be loaded any time. It will provide layer-3 of B-channels for transparent audio.

modprobe mISDN_dsp [debug=XXXX] [options=XXX]

3. Special PH_CONTROL commands

The PH_CONTROL | REQUEST message will be used to give options to the mISDN_dsp module. The first 4 byte of the message (not the ‘dinfo’) will be used as the subcommand. The bytes must be given in the current CPU byte order. The subcommands are defined in mISDN.h and are explained here:

· DTMF_TONE_START

Turn on DTMF detection.

· DTMF_TONE_STOP

Turn off DTMF detection

· CMX_CONF_JOIN

Join a conference. The next 4 bytes of the message define the conference ID. The ID must be greater 0. All b-channels with the same conference ID will be able to talk to each other.

· CMX_CONF_SPLIT

Slit from a conference.

· TONE_PATT_ON

Play pattern/tone. The next 4 bytes of the message define the pattern/tone. See definitions TONE_GERMAN_*, TONE_AMERICAN_* and TONE_SPECIAL_* in mISDN.h. The transmit data is ignored and replaced by the given tone.

· TONE_PATT_OFF

Stop current tone/pattern.

· VOL_CHANGE_TX

· VOL_CHANGE_RX

Change the volume of the transmit or receive data. The next 4 bytes of the message define the change of volume. The 4 bytes are signed integer. A value of zero doesn’t change the volume. A value of 1 will double, a value of 2 quadruple, and so on. A value of –1 will halve, a value of –2 will quarter, and so on. The range is –8 … 8. Note: A telephone connected via NT-mode receives the TX data and vice versa.

· CMX_MIX_ON

· CMX_MIX_OFF

Turn mixing of transmit data and conference data on or off. Mixing is not supported by any chip hardware, so it must be enabled here and will be done in software. When mixing is off, the transmit data causes to “overwrite” the conference data. When mixing is on, the audio waves of transmit data and conference data are added.

· BF_ENABLE_KEY

Enable encryption/decryption using blowfish. The next 4-56 byte of the message will specify the key to use. The result will be a message of type PH_CONTROL | INDICATION that has the result flag stored in the first 4 bytes. They are BF_ACCEPT and BF_REJECT, depending on the success of enabling encryption.

· BF_DISABLE

Disable encryption/decryption.

4. References:

The new HiSax driver “mISDN” is required to use this module. The module is part of the driver. Current source for the mISDN driver is: http://www.isdn4linux.de.

This driver is written by Jolly (Andreas Eversberg) (jolly@eversberg.eu).

[1] Only one S/T interface of one chip may be selected. If more than one interface is selected, the module is not loaded and exits with an error. If no S/T interface is selected, synchronization is done automatically. Only synchronization to TE-Mode interfaces make sense, selecting it for NT-Mode causes an error.

[2] This bit must be configured depending on the used S/T module and circuit to match the 400 W pulse mask test. This bit should be 0 for normal operation.

[3] The buffer is used to avoid bit slips caused by jitter. A larger buffer can compensate greater jitter to avoid bit slips, but causes higher delay of processing.