Osmocom fork of DAHDI code (with some fixes)
Go to file
Oron Peled f11b937659 xpp: can use modern Asterisk hotplug support
* New asynchronous behavior is used only when two conditions are met:
  - Finding new $ASTERISK_SUPPORTS_DAHDI_HOTPLUG=yes in /etc/dahdi/init.conf
    This should be set only when Asterisk support hotplug and configured
    to use it (no_failed_channels==1).
  - DAHDI auto_assign_spans==0

* Adapt /usr/share/dahdi/astribank_hook:
  - Refactor old twinstar behavior into functions
  - Add new behavior in a function (just enable the Asrribank watchdog)
  - Call the correct function.

* Adapt init script:
  If asynchronous behavior is on, don't wait for all Astribanks to
  finish initialization (it's enough that we saw all/some of them)

Signed-off-by: Tzafrir Cohen <tzafrir.cohen@xorcom.com>
Acked-by: Russ Meyerriecks <rmeyerriecks@digium.com>
2014-11-06 13:29:19 +02:00
build_tools Makefile: new 'make-dist' target 2013-12-02 23:01:17 +02:00
doc hyphen/minus fixes in man pages 2014-01-27 20:29:04 +02:00
hotplug registration-order: Added dahdi_auto_assign_compat 2014-03-25 14:51:29 +02:00
ppp PPP: Fix an incorrect function call that was causing dahdi.so to fail to load 2010-08-31 16:12:53 +00:00
xpp xpp: can use modern Asterisk hotplug support 2014-11-06 13:29:19 +02:00
.gitignore added autoconfig.h to .gitignore 2014-06-29 16:34:24 +03:00
LICENSE Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
LICENSE.LGPL Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
Makefile Makefile: A typo in a comment 2014-06-30 13:47:23 +03:00
README README: udev hooks run scripts from directories 2014-01-28 11:42:33 +02:00
UPGRADE.txt README, UPGRADE.txt, system.conf.sample: Add documentation for using HWEC 2010-12-09 22:44:52 +00:00
acinclude.m4 Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
assigned-spans.conf.sample Terminology rename: "pinned" -> "assigned" 2013-11-24 16:42:15 +02:00
autoconfig.h.in astribank_is_starting: use semop if no semtimedop 2010-10-17 18:41:24 +00:00
bittest.h Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
blacklist.sample wcte43x: Teach tools about the wcte43x driver. 2013-11-11 15:40:11 -06:00
bootstrap.sh Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
config.guess Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
config.sub Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
configure configure: regenerate for 6d10525 2013-11-24 18:11:04 +02:00
configure.ac pinned-spans: remove '--enable-pinned' from configure 2013-11-24 16:13:51 +02:00
dahdi-bash-completion bash_completion: fix dahdi_genconf 2014-01-23 23:16:55 +02:00
dahdi.init xpp: can use modern Asterisk hotplug support 2014-11-06 13:29:19 +02:00
dahdi.rules dahdi.rules: use += for RUN 2013-12-12 23:47:50 +02:00
dahdi.xml Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
dahdi_cfg.c dahdi_cfg: Reduce mass ioctls on non-existing channels 2014-07-23 16:53:38 -05:00
dahdi_diag.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
dahdi_maint.c Fix GCC 4.6 "set but not used" warnings 2011-11-02 21:57:25 +00:00
dahdi_monitor.c dahdi-monitor: Fix broken control-C behavior and -F output option 2012-09-21 17:25:48 +00:00
dahdi_pcap.c dahdi_pcap: Imported user space utility for managing pcap streams 2011-11-01 18:10:14 +00:00
dahdi_scan.c dahdi_scan: Support gaps in channel numbering. 2013-04-16 23:25:28 -05:00
dahdi_span_assignments span_types/assignments: no * in device list 2014-01-20 19:22:03 +02:00
dahdi_span_types improved dahdi_span_types dumpconfig 2014-04-01 21:23:28 +03:00
dahdi_speed.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
dahdi_test.c dahdi_test: Enforce range from 0.0% - 100.0% for accuracy. 2011-09-29 17:00:59 +00:00
dahdi_tool.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
dahdi_tools_version.h Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
dahdi_waitfor_span_assignments new "dahdi_waitfor_span_assignments" tool 2014-01-23 12:35:59 +02:00
fxotune.c fxotune: Now options '-b/-e' also apply with '-s' 2013-11-24 16:35:10 +02:00
fxotune.h Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
fxstest.c fxstest: Use DAHDI_SPECIFY when opening by integer channel number. 2013-05-28 12:34:03 -05:00
hdlcgen.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
hdlcstress.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
hdlctest.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
hdlcverify.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
ifup-hdlc Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
init.conf.sample xpp: can use modern Asterisk hotplug support 2014-11-06 13:29:19 +02:00
install-sh Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
makeopts.in pinned-spans: remove '--enable-pinned' from configure 2013-11-24 16:13:51 +02:00
modprobe.conf.sample Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
modules.sample wcte43xp: Teach tools about te436 and te236 products 2014-07-18 10:41:54 -05:00
patgen.c tools: Allow pattern tools to access channels above the device file limit 2011-06-07 19:44:34 +00:00
patlooptest.c patlooptest: Ignore the first buffered event 2011-07-21 17:29:34 +00:00
pattest.c tools: Allow pattern tools to access channels above the device file limit 2011-06-07 19:44:34 +00:00
sethdlc.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
span-types.conf.sample pinned-spans: fix examples in configuration files 2013-11-24 16:08:31 +02:00
system.conf.sample system.conf.sample: Remove reference to single frequency signalling. 2014-05-05 09:45:02 -05:00
timertest.c Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
tonezone.c tonezone: Fix regression in Australian tone patch 2014-09-16 19:07:17 -05:00
tonezone.h Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
wavformat.h Import DAHDI-Tools r9159 2010-08-18 13:49:24 +00:00
zonedata.c tonezone: Fix congestion tone for Australia 2014-08-01 16:04:00 -05:00


DAHDI Telephony Interface Driver
Asterisk Development Team <asteriskteam@digium.com>
$Revision$, $Date$

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.

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

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.

Extra Libraries
Some libraries are needed for extra utilities that are provided with

- 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.

Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
make install
# To install init scripts and config files:
#make config

Build Tweaks
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.

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.

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

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

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


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

  ./config.status --recheck

Configuration for DAHDI resides under /etc/dahdi . 

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.

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.

Reference Configuration
Sample system.conf

Sample init.conf

Sample genconf_parameters
FIXME: still not properly formatted.


Sample assigned-spans.conf

Sample span-types.conf

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:


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 

  ./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

  perldoc ./xpp/lsdahdi

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

  A somewhat glorified `cat /proc/dahdi/*`.
  Generates configuration based on the existing DAHDI channels and on
  /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
  A two-liner script (not installed by default) that simply returns the
  modules that should be modprobe-d on this system.
  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 .

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:

1. Make sure you have the PPP source / headers installed. On Debian:

   apt-get install ppp-dev

2. Run 'make' on the ppp subdirectory:

   make -C ppp 
   make -C ppp install

3. Make sure your kernel has support for both PPP (which is common is
   distribution kernels and for HDLC (much less common) - CONFIG_PPP and

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).

The dahdi init scripts does the following tasks:

* Loading the module dahdi and any other module listed in
* For xpp (Astribanks) - some specific initializations. See
* Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] after all modules were
* A number of other tools may need to be run:
** link:doc/fxotune.8.html[fxotune]
** dahdihpec_enable

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

(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.

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,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,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
link:doc/dahdi_span_types.8.html[dahdi_span_types] and

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

If you want to disable running this script, add the following line to

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

* If system.conf does not exist, generates a temporary configuration
  for the span using link:doc/dahdi_genconf.8.html[dahdi_genconf

* Runs link:doc/dahdi_cfg.8.html[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

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.


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

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

- http://asterisk.org/[] - The Asterisk PBX
- http://voip-info.org/[]
- http://voip-info.org/wiki/view/DAHDI[]
- http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
  of this file]