DAHDI Telephony Interface Driver

DAHDI stands for Digium Asterisk Hardware Device Interface. This package contains the user-space tools to configure the kernel modules included in the package dahdi-linux.

1. Build Requirements

This package needs the headers from dahdi-linux. Thus you should install dahdi-linux before building dahdi-tools.

1.1. Build System

GCC and friends. Generally you will need to install the package gcc. There may be cases where you will need a specific version of gcc to build kernel modules.

1.2. Extra Libraries

Some libraries are needed for extra utilities that are provided with DAHDI.

libusb is needed for building fpga_load, needed for firmware loading of the Xorcom Astribank.
libnewt is needed to build the optional but useful utility dahdi_tool.

1.3. Installation

Note: If using sudo to build/install, you may need to add /sbin to your PATH.

./configure
make
make install
# To install init scripts and config files:
#make config

1.4. Build Tweaks

1.4.1. Partial Build/Install

There are some make targets that are provided to build or install just parts of DAHDI:

Build targets:
- make: Build DAHDI user-space programs and libraries. partial targets of it:
  - make utilname: builds utilname alone (e.g: make dahdi_diag)
  - make utils: Build just the programs.
  - make libs: Build libtonezone.
  - make tests: Build testing binaries.
Install targets:
- make install: Install everything. Sub-targets of it:
  - make install-utils: Installs most things.
  - make install-libs: Installs libtonezone.
- make config: install configuration files (overriding existing ones).
- make install-test: Install testing binaries.

1.4.2. Installation to a Subtree

The following may be useful when testing the package or when preparing a package for a binary distribution (such as an rpm package) installing onto a subtree rather than on the real system.

make install DESTDIR=targetdir

This can be useful for any partial install target from the list above.

1.4.3. Options For ./configure

The configure script executes various tests and based on them generates makeopts. You can pass it --with options and variable settings, for instance:

./configure --without-ncurses CC="gcc-4.10"

If you just want to recreate the same files without a full detection run, use:

./config.status

To re-run ./configure with the same parameters it was run with last time, use:

./config.status --recheck

2. Configuration

Configuration for DAHDI resides under /etc/dahdi .

2.1. /etc/dahdi/system.conf

The main method to configure DAHDI devices is using the utility dahdi_cfg. dahdi_cfg reads data from the configuration file /etc/dahdi/system.conf , figures out what configuration to send to channels, and send it to the kernel.

A sample annotated system.conf is included in this directory and installed by default. Edit it to suit your configuration. Alternatively use the script dahdi_genconf to generate one that should work with your system. Note that while dahdi_genconf will generate a working configuration, it will not automatically detect hardware echo cancellation modules. These will have to be enabled manually in system.conf.

2.2. /etc/dahdi/init.conf

The configuration file of the dahdi init.d script is /etc/dahdi/init.conf . That file is used to override defaults that are set at the beginning of the init.d script.

2.3. Reference Configuration

2.3.1. Sample system.conf

DAHDI Configuration File

This file is parsed by the DAHDI Configurator, dahdi_cfg

Span Configuration

First come the span definitions, in the format

span=<span num>,<timing source>,<line build out (LBO)>,<framing>,<coding>[,yellow]

All T1/E1/BRI spans generate a clock signal on their transmit side. The <timing source> parameter determines whether the clock signal from the far end of the T1/E1/BRI is used as the master source of clock timing. If it is, our own clock will synchronise to it. T1/E1/BRI connected directly or indirectly to a PSTN provider (telco) should generally be the first choice to sync to. The PSTN will never be a slave to you. You must be a slave to it.

Choose 1 to make the equipment at the far end of the E1/T1/BRI link the preferred source of the master clock. Choose 2 to make it the second choice for the master clock, if the first choice port fails (the far end dies, a cable breaks, or whatever). Choose 3 to make a port the third choice, and so on. If you have, say, 2 ports connected to the PSTN, mark those as 1 and 2. The number used for each port should be different.

If you choose 0, the port will never be used as a source of timing. This is appropriate when you know the far end should always be a slave to you. If the port is connected to a channel bank, for example, you should always be its master. Likewise, BRI TE ports should always be configured as a slave. Any number of ports can be marked as 0.

Incorrect timing sync may cause clicks/noise in the audio, poor quality or failed faxes, unreliable modem operation, and is a general all round bad thing.

Note	The B410P card cannot reliably connect one of its four ports configured in TE mode to another one configured in NT mode. It will not reliably sync clock from itself. Please use another physical card and configure one to provide clock and one to recover clock in any B410P test environments.

The line build-out (or LBO) is an integer, from the following table:

0: 0 db (CSU) / 0-133 feet (DSX-1)
1: 133-266 feet (DSX-1)
2: 266-399 feet (DSX-1)
3: 399-533 feet (DSX-1)
4: 533-655 feet (DSX-1)
5: -7.5db (CSU)
6: -15db (CSU)
7: -22.5db (CSU)

If the span is a BRI port the line build-out is not used and should be set to 0.

framing

one of d4 or esf for T1 or cas or ccs for E1. Use ccs for BRI. d4 could be referred to as sf or superframe

coding

one of ami or b8zs for T1 or ami or hdb3 for E1. Use ami for BRI.

For E1 there is the optional keyword crc4 to enable CRC4 checking.
If the keyword yellow follows, yellow alarm is transmitted when no channels are open.
```
#span=1,0,0,esf,b8zs
#span=2,1,0,esf,b8zs
#span=3,0,0,ccs,hdb3,crc4
```

Dynamic Spans

Next come the dynamic span definitions, in the form:

dynamic=<driver>,<address>,<numchans>,<timing>

Where <driver> is the name of the driver (e.g. eth), <address> is the driver specific address (like a MAC for eth), <numchans> is the number of channels, and <timing> is a timing priority, like for a normal span. use "0" to not use this as a timing source, or prioritize them as primary, secondard, etc. Note that you MUST have a REAL DAHDI device if you are not using external timing.

dynamic=eth,eth0/00:02:b3:35:43:9c,24,0

If a non-zero timing value is used, as above, only the last span should have the non-zero value.

Channel Configuration

Next come the definitions for using the channels. The format is: <device>=<channel list>

Valid devices are:

e&m

Channel(s) are signalled using E&M signalling on a T1 line. Specific implementation, such as Immediate, Wink, or Feature Group D are handled by the userspace library.

e&me1

Channel(s) are signalled using E&M signalling on an E1 line.

fxsls

Channel(s) are signalled using FXS Loopstart protocol.

fxsgs

Channel(s) are signalled using FXS Groundstart protocol.

fxsks

Channel(s) are signalled using FXS Koolstart protocol.

fxols

Channel(s) are signalled using FXO Loopstart protocol.

fxogs

Channel(s) are signalled using FXO Groundstart protocol.

fxoks

Channel(s) are signalled using FXO Koolstart protocol.

unused

No signalling is performed, each channel in the list remains idle

clear

Channel(s) are bundled into a single span. No conversion or signalling is performed, and raw data is available on the master.

bchan

Like clear except all channels are treated individually and are not bundled. inclear is an alias for this.

rawhdlc

The DAHDI driver performs HDLC encoding and decoding on the bundle, and the resulting data is communicated via the master device.

dchan

The DAHDI driver performs HDLC encoding and decoding on the bundle and also performs incoming and outgoing FCS insertion and verification. fcshdlc is an alias for this.

hardhdlc

The hardware driver performs HDLC encoding and decoding on the bundle and also performs incoming and outgoing FCS insertion and verification. Is subject to limitations and support of underlying hardware. BRI spans serviced by the wcb4xxp driver must use hardhdlc channels for the signalling channels.

nethdlc

The DAHDI driver bundles the channels together into an hdlc network device, which in turn can be configured with sethdlc (available separately). In 2.6.x kernels you can also optionally pass the name for the network interface after the channel list. Syntax:

  nethdlc=<channel list>[:interface name]
Use original names, don't use the names which have been already registered
in system e.g eth.

dacs

The DAHDI driver cross connects the channels starting at the channel number listed at the end, after a colon

dacsrbs

The DAHDI driver cross connects the channels starting at the channel number listed at the end, after a colon and also performs the DACSing of RBS bits

The channel list is a comma-separated list of channels or ranges, for example:

1,3,5 (channels one, three, and five)
16-23, 29 (channels 16 through 23, as well as channel 29)

So, some complete examples are:

e&m=1-12

nethdlc=13-24

fxsls=25,26,27,28

fxols=29-32

An example of BRI port:

span=1,1,0,ccs,ami

bchan=1,2

hardhdlc=3

Note	When using BRI channels in asterisk, use the bri_cpe, bri_net, or bri_cpe_ptmp (for point to multipoint mode). libpri does not currently support point to multipoint when in NT mode. Otherwise, the bearer channel are configured identically to other DAHDI channels.

#fxoks=1-24
#bchan=25-47

#dchan=48
#fxols=1-12
#fxols=13-24
#e&m=25-29
#nethdlc=30-33

#clear=44
#clear=45
#clear=46
#clear=47

#fcshdlc=48

#dacs=1-24:48

#dacsrbs=1-24:48

Tone Zone Data

Finally, you can preload some tone zones, to prevent them from getting overwritten by other users (if you allow non-root users to open /dev/dahdi/* interfaces anyway. Also this means they won’t have to be loaded at runtime. The format is "loadzone=<zone>" where the zone is a two letter country code.

You may also specify a default zone with "defaultzone=<zone>" where zone is a two letter country code.

An up-to-date list of the zones can be found in the file zonedata.c

loadzone = us
#loadzone = us-old

#loadzone=gr
#loadzone=it
#loadzone=fr
#loadzone=de
#loadzone=uk
#loadzone=fi
#loadzone=jp
#loadzone=sp
#loadzone=no
#loadzone=hu
#loadzone=lt
#loadzone=pl

defaultzone=us

PCI Radio Interface

(see http://www.zapatatelephony.org/app_rpt.html)

The PCI Radio Interface card interfaces up to 4 two-way radios (either a base/mobile radio or repeater system) to DAHDI channels. The driver may work either independent of an application, or with it, through the driver;s ioctl() interface. This file gives you access to specify load-time parameters for Radio channels, so that the driver may run by itself, and just act like a generic DAHDI radio interface.

Unlike the rest of this file, you specify a block of parameters, and then the channel(s) to which they apply. CTCSS is specified as a frequency in tenths of hertz, for example 131.8 HZ is specified as 1318. DCS for receive is specified as the code directly, for example 223. DCS for transmit is specified as D and then the code, for example D223.

The hardware supports a "community" CTCSS decoder system that has arbitrary transmit CTCSS or DCS codes associated with them, unlike traditional "community" systems that encode the same tone they decode.

this example is a single tone DCS transmit and receive

specify the transmit tone (in DCS mode this stays constant):

#tx=D371

specify the receive DCS code:

#dcsrx=223

this example is a "community" CTCSS (if you only want a single tone, then only specify 1 in the ctcss list)

specify the default transmit tone (when not receiving):

#tx=1000

Specify the receive freq, the tag (use 0 if none), and the transmit code. The tag may be used by applications to determine classification of tones. The tones are to be specified in order of presedence, most important first. Currently, 15 tones may be specified..

#ctcss=1318,1,1318
#ctcss=1862,1,1862

The following parameters may be omitted if their default value is acceptible

Set the receive debounce time in milliseconds:

#debouncetime=123

set the transmit quiet dropoff burst time in milliseconds:

#bursttime=234

set the COR level threshold (specified in tenths of millivolts) valid values are {3125,6250,9375,12500,15625,18750,21875,25000}

#corthresh=12500

Invert COR signal {y,n}

#invertcor=y

Set the external tone mode; yes, no, internal {y,n,i}

#exttone=y

Now apply the configuration to the specified channels:

We are all done with our channel parameters, so now we specify what channels they apply to

#channels=1-4

Overiding PCM encoding

Usually the channel driver sets the encoding of the PCM for the channel (mulaw / alaw. That is: g711u or g711a). However there are some cases where you would like to override that. mulaw and alaw set different such encoding. Use them for channels you have already defined with e.g. bchan or fxoks.

#mulaw=1-4

#alaw=1-4

deflaw is similar, but resets the encoding to the channel driver’s default. It must be useful for something, I guess.

#mulaw=1-10

#deflaw=5

Echo Cancellers

DAHDI uses modular echo cancellers that are configured per channel. The echo cancellers are compiled and installed as part of the dahdi-linux package. You can specify in this file the echo canceller to be used for each channel. The default behavior is for there to be NO echo canceller on any channel, so it is very important that you specify one here.

Valid echo cancellers are: hwec, mg2, kb1, sec2, and sec. hwec is a special echo canceller that should be used if hardware echo cancellation is desired on and available on the specified channels. If compiled, hpec is also a valid echo canceller.

To configure the default echo cancellers, use the format: echocanceller=<echocanceller name>,<channel(s)>

Example: Configure channels 1 through 8 to use the mg2 echo canceller

#echocanceller=mg2,1-8

And change channel 2 to use the kb1 echo canceller.

#echocanceller=kb1,2

2.3.2. Sample init.conf

Shell settings for Dahdi initialization scripts. This replaces the old/per-platform files (/etc/sysconfig/zaptel, /etc/defaults/zaptel)

The maximal timeout (seconds) to wait for udevd to finish generating device nodes after the modules have loaded and before running dahdi_cfg.

#DAHDI_DEV_TIMEOUT=40

A list of modules to unload when stopping. All of their dependencies will be unloaded as well.

#DAHDI_UNLOAD_MODULES=""              # Disable module unloading
#DAHDI_UNLOAD_MODULES="dahdi echo"    # If you use OSLEC

Override settings for xpp_fxloader

#XPP_FIRMWARE_DIR=/usr/share/dahdi

#XPP_HOTPLUG_DISABLED=yes

#XPP_HOTPLUG_DAHDI=yes

Disable udev handling:

#DAHDI_UDEV_DISABLE_DEVICES=yes

#DAHDI_UDEV_DISABLE_SPANS=yes

2.3.3. Sample genconf_parameters

FIXME: still not properly formatted.

/etc/dahdi/genconf_parameters

This file contains parameters that affect the dahdi_genconf configuration generator.

Syntax: * A comment from # to end of line * Blank lines ignored * Whitespace at end of line trimmed * Single valued items: key <whitespace…> value * List valued items: key <whitespace…>value1 <whitespace…>value2 …

When generating extensions for chan_dahdi.conf or users.conf etc: the extension number will be channel_number+base_exten . The default is:

#base_exten           4000

Make FXS (analog phones) extensions answer immediately (sets immediate = yes for them in chan_dahdi.conf). Don’t enable this before you’re read documentation about this option.

#fxs_immediate                yes

For FXS (analog phones) - use KS or LS? ks is the only method for Asterisk to provide disconnect supervision and thus it would normally be preferred and is the default.

#fxs_default_start    ls

For FXO (analog lines) - use KS or LS? KS is the default and is normally the better choice as it allows detecting hang-ups on many lines.

#fxo_default_start    ls

Set tone zone values. This is used for playing tones (busy, dial-tone and such). The default is us. This sets the value for both loadzone and defaultzone in system.conf .

#lc_country           il

The dialplan context into which to send trunks in chan_dahdi.conf or users.conf. The default value is:

#context_lines                from-pstn

The dialplan context into which to send extensions in chan_dahdi.conf or users.conf. The default value is:

#context_phones               from-internal

Two extra contexts for the input ports and output ports of an Astribank. Default values are:

#context_input                astbank-input
#context_output               astbank-output

A group to put all analog phones in. By default 0, so you can dial to the first phone available using Dahdi/g5 .

#group_phones         5

A group in which to put all the channels belonging to some trunk. Thus you can dial through "some trunk" using Dahdi/G0/NUMBER

#group_lines          0

Channels of digital trunk of span N are also added to group 10+N (that is: 14 for channels of span 4).

Do we want to use PtP (bri) or PtMP (bri_ptmp) for BRI? PtMP allows connecting several CPE devices on the same network device (several BRI phones on the same line, kind of like several analog phones on the same analog line). However it is generally brings unnecessary complexity for a pbx-pbx connection. It is still the default as this is normally what you get for a BRI PSTN connection.

#bri_sig_style                bri

If this option is set (that is: not remmed-out), BRI NT ports will also be set as overlap. This is useful if you want to connect ISDN phones.

#brint_overlap

The echo canceler to use. If you have a hardware echo canceler, just leave it be, as this one won’t be used anyway.

The default is mg2, but it may change in the future. E.g: a packager that bundles a better echo canceler may set it as the default, or dahdi_genconf will scan for the "best" echo canceler.

#echo_can             hpec
#echo_can             oslec
#echo_can             none  # to avoid echo canceler altogether

bri_hardhdlc: yes - forces BRI cards to use hardhdlc signalling. no - forces BRI cards to use dchan (an alias for fcshdlc). It is usefull only for dahdi with the bristuff patch.

If it is left out or set to auto: * Information supplied by the driver is used to decide: - Currently implemented for Astribanks. - Taken from /sys/bus/xpds/drivers/bri/dchan_hardhdlc. * Without this info, falls back to hardhdlc.

#bri_hardhdlc         auto

For MFC/R2 Support: R2 will make E1 spans CAS and with the r2_idle_bits bit in system.conf . It will also make dahdi_genconf default to generating the channels of this card in unicall.conf rather than in chan_dahdi.conf . The meaning of this may be extended somehow to support R2 through openr2/chan_dahdi later on.

#pri_connection_type  R2
#pri_connection_type  CAS

Explicitly set the idle bits for E1 CAS (Sample value is the default):

#r2_idle_bits         1101

Set T1 framing type to d4 instead of esf:

#tdm_framing          d4

Use E&M on CAS (default is FXS/FXO). If set, E1 spans will be used as E&M-E1 and T1 will use the requested type:

#em_signalling em
#em_signalling em_w
#em_signalling featd
#em_signalling featdtmf
#em_signalling featdtmf_ta
#em_signalling featb
#em_signalling fgccama
#em_signalling fgccamamf

pri_termtype contains a list of settings: Currently the only setting is for TE or NT (the default is TE). This sets two different but normally related configuration items:

A TE span will have *_cpe signalling in Asterisk and will also get timing from the remote party.

A NT span will have *_new signalling in Asterisk and will provide timing to the remote party.

pri_termtype is a list if span specs and configuration (TE/NT) for them. The first spec that matches is used. The matching is of perl regular expressions, but with * and ? have their meaning from basic regular expressions.

#pri_termtype

SPAN/2 NT SPAN/4 NT

#pri_termtype

SPAN/* NT

Astribanks can be matched by span and also by their: LABEL + XPD number: this is burned into the Astribank and won’t change if it’s connected via different USB port/hub CONNECTOR + XPD number: The USB path to which the Astribank is connected. Replacing an Astribank and connecting to the same USB port/hub would not change this property. However, any change in USB wiring (e.g: adding another hub) may alter this. NUM (XBUS number) + XPD number: The XBUS number. This is not stable and may even change between boots.

#pri_termtype

LABEL/usb:INT01216/XPD-0[123] NT LABEL/usb:INT00375/XPD-0[123] NT CONNECTOR/@usb-0000:00:1d.7-1/XPD-0[123] NT CONNECTOR/@usb-0000:00:1d.7-2/XPD-0[123] NT NUM/XBUS-01/XPD-0[123] NT NUM/XBUS-03/XPD-0[123] NT

2.3.4. Sample assigned-spans.conf

/etc/dahdi/assigned-spans.conf:

This file assigns span and channel numbers to dahdi devices

Built as a table keyed by <id>: <id> <spanspec>….

Where: * The <id> field may be either: hardware_id @location devpath (in sysfs) * Shell-style globbing is allowed for the <id> field * There may one or more of <spanspec> * Each <spanspec> is composed as: <local_spanno>:<assigned_spanno>:<base_channo>

Examples:

Astribank with two spans: FXS * 8 channels + 4 digital inputs 2 digital outputs FXO * 8 channels

#usb:QA-1             1:1:1
#usb:QA-1             2:2:15

Same Astribank in one-liner

#usb:QA-1             1:1:1 2:2:15

Astribank with 4*PRI spans and 3*FXS*8 spans Note that channels are NOT globally contigous each span get its own 50 numbers. Also, skip Channel number 250…

#usb:INT03165         1:1:1   # E1
#usb:INT03165         2:2:51  # E1
#usb:INT03165         3:3:151 # E1
#usb:INT03165         4:4:201 # E1
#usb:INT03165         5:5:301 # FXS * 8 channels
#usb:INT03165         6:6:351 # FXS * 8 channels
#usb:INT03165         7:7:401 # FXS * 8 channels

Alternatively — all in one-line

#usb:INT03165         1:1:1 2:2:51 3:3:151 4:4:201 5:5:301 6:6:351 7:7:401

Astribank with 4*BRI without hardware_id :-( We use the location on the bus (ie: where it is physically located). Note the @ prefix that indicate the location key.

#@usb-0000:00:1d.7-3  1:1:50
#@usb-0000:00:1d.7-3  2:2:100
#@usb-0000:00:1d.7-3  3:3:150
#@usb-0000:00:1d.7-3  4:4:200

Same configuration with globbing:

#/sys/*/usb1/1-6/*    1:1:50
#/sys/*/usb1/1-6/*    2:2:100
#/sys/*/usb1/1-6/*    3:3:150
#/sys/*/usb1/1-6/*    4:4:200

2.3.5. Sample span-types.conf

/etc/dahdi/spantype.conf: Set E1/T1/J1 per-device

Built as a table of two columns: <id> <local_spanno>:<type>

Where: * The <id> field may be either: hardware_id @location devpath (in sysfs) * The <local_spanno> is the relative span number in the device (starting from 1) In this filed globbing rules apply. E.g: - * are all the spans in this device - [12] are the first two spans in this device * The <type> may be E1, T1 or J1

Examples: Set the first two spans of a specific Astribank to T1

#usb:000156 [12]:T1

Set all spans of another Astribank to T1

#usb:INT03165         *:E1

Set the first two spans of an Astribank to T1. The
Astribanks is specified by its location instead of hardware_id

#@usb-0000:00:1d.7-3 [12]:T1

2.4. Tonezones

The file zonedata.c contains the information about the tone zones used in libtonezone (and hence also in dahdi_cfg). Here is a list of those zones:

us United States / North America
au Australia
fr France
nl Netherlands
uk United Kingdom
fi Finland
es Spain
jp Japan
no Norway
at Austria
nz New Zealand
it Italy
us-old United States Circa 1950 / North America
gr Greece
tw Taiwan
cl Chile
se Sweden
be Belgium
sg Singapore
il Israel
br Brazil
hu Hungary
lt Lithuania
pl Poland
za South Africa
pt Portugal
ee Estonia
mx Mexico
in India
de Germany
ch Switzerland
dk Denmark
cz Czech Republic
cn China
ar Argentina
my Malaysia
th Thailand
bg Bulgaria
ve Venezuela
ph Philippines
ru Russian Federation
tr Turkey
pa Panama
mo Macao,China
cr Costa Rica
ae United Arab Emirates

2.5. DAHDI PERL modules

The directory xpp has, in addition to helper utilities for the Xorcom Astribank, a collection of PERL modules to provide information related to DAHDI. The PERL modules themselves are under xpp/perl_modules/ . In xpp/ there are several utilities that use those modules: - xpp-specific: dahdi_registration, xpp_sync, xpp_blink . - General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers

The DAHDI PERL modules will currently only be automatically installed if you happen to install the xpp directory. Those utilities require the PERL modules to be installed, however they will also look for them in the directory perl_modules, and thus can be run directly from the DAHDI source tree. For example:

./xpp/dahdi_hardware -v

To get usage information on a program, you can also use perldoc (sometimes provided in a package separate from perl itself). For instance:

perldoc ./xpp/lsdahdi

Some of them are specific for the Xorcom Astribank and described in its documentation. the others are:

lsdahdi: A somewhat glorified cat /proc/dahdi/*.
dahdi_genconf: Generates configuration based on the existing DAHDI channels and on /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
dahdi_drivers: A two-liner script (not installed by default) that simply returns the modules that should be modprobe-d on this system.
dahdi_hardware: Uses the information from SysFS and its own knowledge to show what PCI/USB DAHDI hardware is connected and if it is currently used by a driver. Shows also some more information for Astribanks from /proc/xpp .

2.6. PPP Support

DAHDI digital cards can provide data channels through PPP as point-to-point connections. This requires a plug-in to the PPP daemon that is included in the ppp/ subdirectory. To install it:

Make sure you have the PPP source / headers installed. On Debian:
```
apt-get install ppp-dev
```
Run make on the ppp subdirectory:
```
make -C ppp
make -C ppp install
```
Make sure your kernel has support for both PPP (which is common is distribution kernels and for HDLC (much less common) - CONFIG_PPP and CONFIG_HDLC .

3. Initialization

This section documents the start up sequence of the DAHDI modules.

There are generally two options: explicit (using an init script) and implicit (run from UDEV hook scripts).

3.1. Explicit

The dahdi init scripts does the following tasks:

Loading the module dahdi and any other module listed in /etc/dahdi/modules.
For xpp (Astribanks) - some specific initializations. See README.Astribank.
Runs dahdi_cfg after all modules were loaded.
A number of other tools may need to be run:
- fxotune
- dahdihpec_enable

Only at this point Asterisk (or any other user of DAHDI) can be run.

3.2. Implicit

(Also known as "hot-plug" or "pinned-spans". This requires:

dahdi >= 2.8.0
Setting the module parameter auto_assign_spans of dahdi to 0
(Recommended) Asterisk >= 12 - which supports "dahdi create channels".

When a device driver of a DAHDI device finishes initialization, it creates a dahdi_device kernel object. A dahdi_device represents a single DAHDI device (such as a PCI card) and may have several spans. If the value of auto_assign_spans is 1 when dahdi_device is created, spans are assigned automatically - each new span gets the first available span number and range of channels. However if it is set to 0, spans will not get assigned, and user space programs need to assign them. The low-level interface for doing so is explained in the section "Span Assignment" in the README of DAHDI-Linux.

3.2.1. New Devices

When a kernel object is created or destroyed, the kernel sends an event to user space. Those events are normally handled by udevd. Configurations for udevd ("udev rules") may be placed in /etc/udev/rules.d or /lib/udev/rules.d. This package installs rules that instruct udevd to run the script /usr/share/dahdi/dahdi_handle_device on each new device, which runs all the scripts in /usr/share/dahdi/handle_device.d. Those scripts will:

If /etc/dahdi/span-types.conf exists, apply it to the device. It is used for E1/T1/J1 settings. See sample span-types.conf.
If /etc/dahdi/assigned-spans.conf exists, assign the span according to it (if it is not specified there: don’t assign it). used for E1/T1/J1 settings. See sample assigned-spans.conf.
But if that file does not exist, assign the span to the first available place.

This script mainly uses the commands dahdi_span_types and dahdi_span_assignments.

DAHDI devices are listed under /sys/bus/dahdi_devices/devices.

If you want to disable running this script, add the following line to /etc/dahdi/init.conf:

DAHDI_UDEV_DISABLE_DEVICES=yes

3.2.2. New Spans

Once a span is assigned, a kernel object will appear for it. It will be listed under its device. As a new kernel object was created, an event is sent to udev.

The standard DAHDI udev rules instruct udevd to run the script /usr/share/dahdi/dahdi_span_config which runs all the scripts in /usr/share/dahdi/span_config.d. Those script configures the new span:

If system.conf does not exist, generates a temporary configuration for the span using dahdi_genconf system.
Runs dahdi_cfg on the new span (using -S and -C`).
Runs asterisk -rx 'dahdi create channels' to add the new channels and spans to Asterisk (if they were configured in advance).

If you want to disable running this script, add the following line to /etc/dahdi/init.conf:

DAHDI_UDEV_DISABLE_SPANS=yes

3.2.3. New Channels

DAHDI channels have their own representation in the kernel. The standard udev rules that dahdi-tools includes for them, however, don’t run a script for each device. Each DAHDI channel creates a block device file at /dev/dahdi/chan/span/rel-chan, where span and rel-chan are each three-digit numbers (e.g: 035). span is the span number and rel-chan is the channel number relative to the span.

The udev rules generate the following extra symlinks under /dev/dahdi:

/dev/dahdi/num - the channel number. As it was originally (but continues beyond 250).
/dev/dahdi/devices/hardware_id/rel-span/rel-chan - if the DAHDI device has a hardware ID field, provide listing of the device’s span and channels.
/dev/dahdi/devices/@hardware_id/rel-span/rel-chan - likewise for the connector field. It has a "@" prefix.

4. Upgrade Notes

Information for upgrading from Zaptel 1.2 or 1.4 to DAHDI 2.0

Upgrading from Zaptel to DAHDI is fairly straightforward; install this package using the installation instructions, and then reconfigure and rebuild Asterisk; Asterisk 1.4 releases later than 1.4.21, and all releases of Asterisk 1.6, will automatically use DAHDI in preference to Zaptel, even if Zaptel is still installed on the system.

Important notes about upgrading:

The Zaptel package, which included both kernel modules and userspace tools for configuring and managing the modules, has been split into two packages:

dahdi-linux: kernel modules
dahdi-tools: userspace tools

In addition, there is a dahdi-linux-complete package that contains both dahdi-linux and dahdi-tools for simplified installation.

Note

The dahdi-linux and dahdi-tools packages have separate version numbers; they will not be released in sync, and it is perfectly acceptable to use (for example) dahdi-tools 2.0.6 with dahdi-linux 2.0.11. The dahdi-linux-complete package version number will always include both of these version numbers so that you will know what is included in it.

4.1. DAHDI-Linux

4.1.1. Module Names

The primary kernel modules have changed names; the new names are:

zaptel.ko      ->      dahdi.ko
ztd-eth.ko     ->      dahdi_dynamic_eth.ko
ztd-loc.ko     ->      dahdi_dynamic_loc.ko
ztdummy.ko     ->      dahdi_dummy.ko
ztdynamic.ko   ->      dahdi_dynamic.ko
zttranscode.ko ->      dahdi_transcode.ko

The kernel modules for card drivers have not changed names, although the wcusb and torisa drivers are no longer included.
This package no longer includes the menuselect utility for choosing which modules to build; all modules that can be built are built automatically.

4.1.2. Echo Canceller Modules

It is no longer possible and needed to select a software echo canceler at compile time to build into dahdi.ko; all four included echo cancelers (MG2, KB1, SEC and SEC2) are built as loadable modules. If the Digium HPEC binary object file has been placed into the proper directory the HPEC module will be built as well.

Any or all of these modules can be loaded at the same time, and the echo canceler to be used on the system’s channels can be configured using the dahdi_cfg tool from the dahdi-tools package.

Important

It is mandatory to configure an echo canceler for the system’s channels using dahdi_cfg. There is no default echo canceler with DAHDI, not even hardware echo cancellation modules. See section on echo cancellers in sample system.conf.

4.2. DAHDI-Tools

Many tool names have changed:

ztcfg      ->  dahdi_cfg
ztmonitor  ->  dahdi_monitor
ztscan     ->  dahdi_scan
ztspeed    ->  dahdi_speed
zttest     ->  dahdi_test
zttool     ->  dahdi_tool
zapconf    ->  dahdi_genconf (deprecates genzaptelconf)

The system configuration file has moved from /etc/zaptel.conf to /etc/dahdi/system.conf.
The dahdi_cfg tool can now be used to select an echo canceler on a channel-by-channel basis in the system configuration file; see system.conf.sample for examples of how to do this.
The configuration for XPP init_card_* scripts is done now in /etc/dahdi/xpp.conf and uses a simple syntax (example included). For PRI modules, the pri_protocol setting, determines how to configure it (E1/T1).
In Astribank PRI modules, the LED behaviour represents which ports are CLOCK MASTER (red color) and which are CLOCK SLAVE (green color). Usually (but not always), this corresponds to the NT/TE settings in Asterisk.
The /etc/sysconfig/zaptel (or /etc/default/zaptel file, depending on your distribution) is now split into two separate files: /etc/dahdi/modules control which modules are loaded and module options are set via /etc/modprobe.d/dahdi.

5. License

This package is distributed under the terms of the GNU General Public License Version 2, except for some components which are distributed under the terms of the GNU Lesser General Public License Version 2.1. Both licenses are included in this directory, and each file is clearly marked as to which license applies.

If you wish to use the DAHDI drivers in an application for which the license terms are not appropriate (e.g. a proprietary embedded system), licenses under more flexible terms can be readily obtained through Digium, Inc. at reasonable cost.

6. Reporting Bugs

Please report bug and patches to the Asterisk bug tracker at http://bugs.digium.com/ in the "DAHDI" category.