You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Harald Welte 7160050851 remove dependency to dahdi-linux 9 months ago
build_tools make_version: cut off slashes in git 6 years ago
debian remove dependency to dahdi-linux 9 months ago
doc New upstream version 3.0.0 2 years ago
hotplug New upstream version 3.0.0 2 years ago
m4 A placeholder for the m4 directory 6 years ago
ppp automake: full ppp/ support 6 years ago
xpp New upstream version 3.0.0 2 years ago
.gitignore New upstream version 3.0.0 2 years ago
.version New upstream version 3.1.0 11 months ago
LICENSE Import DAHDI-Tools r9159 11 years ago
LICENSE.LGPL Import DAHDI-Tools r9159 11 years ago
Makefile.am build fix: external CFLAGS are ignored 5 years ago
Makefile.legacy New upstream version 3.0.0 2 years ago
README README: document the need for autoreconf 6 years ago
UPGRADE.txt README, UPGRADE.txt, system.conf.sample: Add documentation for using HWEC 11 years ago
acinclude.m4 Import DAHDI-Tools r9159 11 years ago
assigned-spans.conf.sample Terminology rename: "pinned" -> "assigned" 8 years ago
bittest.h Import DAHDI-Tools r9159 11 years ago
blacklist.sample wcte43x: Teach tools about the wcte43x driver. 8 years ago
bootstrap.sh Import DAHDI-Tools r9159 11 years ago
configure.ac link libtonezone directly to libm 6 years ago
dahdi-bash-completion New upstream version 3.0.0 2 years ago
dahdi.init xpp: can use modern Asterisk hotplug support 7 years ago
dahdi.rules dahdi.rules: use += for RUN 8 years ago
dahdi.xml Import DAHDI-Tools r9159 11 years ago
dahdi_cfg.c dahdi_cfg: -S has assumtions on system.conf order 6 years ago
dahdi_diag.c Import DAHDI-Tools r9159 11 years ago
dahdi_maint.c Fix GCC 4.6 "set but not used" warnings 10 years ago
dahdi_monitor.c dahdi-monitor: Fix broken control-C behavior and -F output option 9 years ago
dahdi_pcap.c dahdi_pcap: Imported user space utility for managing pcap streams 10 years ago
dahdi_scan.c dahdi_scan: Support gaps in channel numbering. 8 years ago
dahdi_span_assignments New upstream version 3.0.0 2 years ago
dahdi_span_types New upstream version 3.0.0 2 years ago
dahdi_speed.c Import DAHDI-Tools r9159 11 years ago
dahdi_test.c New upstream version 3.0.0 2 years ago
dahdi_tool.c Import DAHDI-Tools r9159 11 years ago
dahdi_tools_version.h Import DAHDI-Tools r9159 11 years ago
dahdi_waitfor_span_assignments new "dahdi_waitfor_span_assignments" tool 8 years ago
fxotune.c fxotune: Now options '-b/-e' also apply with '-s' 8 years ago
fxotune.h Import DAHDI-Tools r9159 11 years ago
fxstest.c fxstest: Use DAHDI_SPECIFY when opening by integer channel number. 8 years ago
hdlcgen.c automake: migrated "--enable-dev-mode" 6 years ago
hdlcstress.c automake: migrated "--enable-dev-mode" 6 years ago
hdlctest.c Import DAHDI-Tools r9159 11 years ago
hdlcverify.c Import DAHDI-Tools r9159 11 years ago
ifup-hdlc Import DAHDI-Tools r9159 11 years ago
init.conf.sample xpp: can use modern Asterisk hotplug support 7 years ago
install-sh Import DAHDI-Tools r9159 11 years ago
makeopts.in Disable menuselect in dahdi-tools 10 years ago
modprobe.conf.sample Import DAHDI-Tools r9159 11 years ago
modules.sample wcb4xxp: Adds support for b43x/b23x products 6 years ago
patgen.c Remove rcsid: Unused since move to Git 6 years ago
patlooptest.c automake: migrated "--enable-dev-mode" 6 years ago
pattest.c Remove rcsid: Unused since move to Git 6 years ago
sethdlc.c Import DAHDI-Tools r9159 11 years ago
span-types.conf.sample pinned-spans: fix examples in configuration files 8 years ago
system.conf.sample system.conf.sample: Remove reference to single frequency signalling. 7 years ago
timertest.c Import DAHDI-Tools r9159 11 years ago
tonezone.c tonezone: Fix regression in Australian tone patch 7 years ago
tonezone.h Import DAHDI-Tools r9159 11 years ago
version.c.in build: generate version.c during configure 6 years ago
wavformat.h Import DAHDI-Tools r9159 11 years ago
zonedata.c tonezone: Fix congestion tone for Australia 7 years ago

README

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.

Autotools (autoconf, automake and libtool) are needed if you clone from
Git.


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

- libusb is needed for building astribank_hexload, needed for firmware
loading of the Xorcom Astribank.
- libnewt is needed to build the optional but useful utility dahdi_tool.
- libpcap is needed for building dahdi_pcap.
- pppd is needed to build the dahdi pppd plugin.


Installation
~~~~~~~~~~~~
Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
----------------------------------
# Only if you cloned from git:
autoreconf -i

./configure
make
make install
# To install some extra configuration files:
#make install-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.
- make docs: Generate some extra documentation files.
. Install targets:
- make install: Install everything
- make install-config: install configuration files


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 the build will depend on
their result. 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


Configuration
-------------
Configuration for DAHDI resides under /etc/dahdi .

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

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

/etc/dahdi/assigned-spans.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Assigns span number and initial channel number for spans in each device.
Just like system.conf it may be generated with dahdi_genconf:

dahdi_span_assignments auto
dahdi_genconf

It may also be edited manually to allow reserving span and channel
numbers for specific devices.

/etc/dahdi/span-types.conf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Theoretically, this file is similar to assigned-spans.conf. It allows
setting the type (E1/T1) of a "PRI" span. This cannot be configured
anywhere else: it needs to be done before the span is assigned as it
changes the number of channels the span has.

In practice most systems don't mix E1 and T1 and thus this file will
typically have at most a single wild-card line setting all cards to be
either E1 or T1.


Reference Configuration
~~~~~~~~~~~~~~~~~~~~~~~
Sample system.conf
^^^^^^^^^^^^^^^^^^
include::system.conf.asciidoc[]


Sample init.conf
^^^^^^^^^^^^^^^^
include::init.conf.asciidoc[]


Sample genconf_parameters
^^^^^^^^^^^^^^^^^^^^^^^^^
FIXME: still not properly formatted.

include::genconf_parameters.asciidoc[]


Sample assigned-spans.conf
^^^^^^^^^^^^^^^^^^^^^^^^^^
include::assigned-spans.conf.asciidoc[]


Sample span-types.conf
^^^^^^^^^^^^^^^^^^^^^^
include::span-types.conf.asciidoc[]


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:

include::tonezones.txt[]


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 .


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


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

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 link:doc/dahdi_cfg.8.html[dahdi_cfg] after all modules were
loaded.
* 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.


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.

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


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 link:doc/dahdi_genconf.8.html[dahdi_genconf
system].

* 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
`/etc/dahdi/init.conf`:
.............................
DAHDI_UDEV_DISABLE_SPANS=yes
.............................


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.


include::UPGRADE.txt[]


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.


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


Links
-----
- 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]