| 1 |
DAHDI Telephony Interface Driver |
| 2 |
================================= |
| 3 |
Asterisk Development Team <[email protected]> |
| 4 |
$Revision$, $Date$ |
| 5 |
|
| 6 |
DAHDI stands for Digium Asterisk Hardware Device Interface. This |
| 7 |
package contains the user-space tools to configure the kernel modules |
| 8 |
included in the package dahdi-linux. |
| 9 |
|
| 10 |
Build Requirements |
| 11 |
------------------ |
| 12 |
This package needs the headers from dahdi-linux. Thus you should install |
| 13 |
dahdi-linux before building dahdi-tools. |
| 14 |
|
| 15 |
Build System |
| 16 |
~~~~~~~~~~~~ |
| 17 |
GCC and friends. Generally you will need to install the package gcc. |
| 18 |
|
| 19 |
Autotools (autoconf, automake and libtool) are needed if you clone from |
| 20 |
Git. |
| 21 |
|
| 22 |
|
| 23 |
Extra Libraries |
| 24 |
~~~~~~~~~~~~~~~ |
| 25 |
Some libraries are needed for extra utilities that are provided with |
| 26 |
DAHDI. |
| 27 |
|
| 28 |
- libusb is needed for building astribank_hexload, needed for firmware |
| 29 |
loading of the Xorcom Astribank. |
| 30 |
- libnewt is needed to build the optional but useful utility dahdi_tool. |
| 31 |
- libpcap is needed for building dahdi_pcap. |
| 32 |
- pppd is needed to build the dahdi pppd plugin. |
| 33 |
|
| 34 |
|
| 35 |
Installation |
| 36 |
~~~~~~~~~~~~ |
| 37 |
Note: If using `sudo` to build/install, you may need to add /sbin to your PATH. |
| 38 |
---------------------------------- |
| 39 |
# Only if you cloned from git: |
| 40 |
autoreconf -i |
| 41 |
|
| 42 |
./configure |
| 43 |
make |
| 44 |
make install |
| 45 |
# To install some extra configuration files: |
| 46 |
#make install-config |
| 47 |
---------------------------------- |
| 48 |
|
| 49 |
|
| 50 |
Build Tweaks |
| 51 |
~~~~~~~~~~~~ |
| 52 |
Partial Build/Install |
| 53 |
^^^^^^^^^^^^^^^^^^^^^ |
| 54 |
There are some make targets that are provided to build or install just |
| 55 |
parts of DAHDI: |
| 56 |
|
| 57 |
. Build targets: |
| 58 |
- make: Build DAHDI user-space programs and libraries. |
| 59 |
- make docs: Generate some extra documentation files. |
| 60 |
. Install targets: |
| 61 |
- make install: Install everything |
| 62 |
- make install-config: install configuration files |
| 63 |
|
| 64 |
|
| 65 |
Installation to a Subtree |
| 66 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 67 |
The following may be useful when testing the package or when preparing a |
| 68 |
package for a binary distribution (such as an rpm package) installing |
| 69 |
onto a subtree rather than on the real system. |
| 70 |
|
| 71 |
make install DESTDIR=targetdir |
| 72 |
|
| 73 |
This can be useful for any partial install target from the list above. |
| 74 |
|
| 75 |
|
| 76 |
Options For ./configure |
| 77 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 78 |
The configure script executes various tests and the build will depend on |
| 79 |
their result. You can pass it --with options and variable settings, for |
| 80 |
instance: |
| 81 |
|
| 82 |
./configure --without-ncurses CC="gcc-4.10" |
| 83 |
|
| 84 |
If you just want to recreate the same files without a full detection |
| 85 |
run, use: |
| 86 |
|
| 87 |
./config.status |
| 88 |
|
| 89 |
To re-run ./configure with the same parameters it was run with last |
| 90 |
time, use: |
| 91 |
|
| 92 |
./config.status --recheck |
| 93 |
|
| 94 |
|
| 95 |
Configuration |
| 96 |
------------- |
| 97 |
Configuration for DAHDI resides under /etc/dahdi . |
| 98 |
|
| 99 |
/etc/dahdi/system.conf |
| 100 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 101 |
The main method to configure DAHDI devices is using the utility |
| 102 |
*dahdi_cfg*. dahdi_cfg reads data from the configuration file |
| 103 |
/etc/dahdi/system.conf , figures out what configuration to send to |
| 104 |
channels, and send it to the kernel. |
| 105 |
|
| 106 |
A sample annotated system.conf is included in this directory and |
| 107 |
installed by default. Edit it to suit your configuration. Alternatively |
| 108 |
use the script dahdi_genconf to generate one that should work with your |
| 109 |
system. Note that while dahdi_genconf will generate a working configuration, |
| 110 |
it will not automatically detect hardware echo cancellation modules. These |
| 111 |
will have to be enabled manually in system.conf. |
| 112 |
|
| 113 |
/etc/dahdi/init.conf |
| 114 |
~~~~~~~~~~~~~~~~~~~~ |
| 115 |
The configuration file of the dahdi init.d script is |
| 116 |
/etc/dahdi/init.conf . That file is used to override defaults that are |
| 117 |
set at the beginning of the init.d script. |
| 118 |
|
| 119 |
/etc/dahdi/assigned-spans.conf |
| 120 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 121 |
Assigns span number and initial channel number for spans in each device. |
| 122 |
Just like system.conf it may be generated with dahdi_genconf: |
| 123 |
|
| 124 |
dahdi_span_assignments auto |
| 125 |
dahdi_genconf |
| 126 |
|
| 127 |
It may also be edited manually to allow reserving span and channel |
| 128 |
numbers for specific devices. |
| 129 |
|
| 130 |
/etc/dahdi/span-types.conf |
| 131 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 132 |
Theoretically, this file is similar to assigned-spans.conf. It allows |
| 133 |
setting the type (E1/T1) of a "PRI" span. This cannot be configured |
| 134 |
anywhere else: it needs to be done before the span is assigned as it |
| 135 |
changes the number of channels the span has. |
| 136 |
|
| 137 |
In practice most systems don't mix E1 and T1 and thus this file will |
| 138 |
typically have at most a single wild-card line setting all cards to be |
| 139 |
either E1 or T1. |
| 140 |
|
| 141 |
|
| 142 |
Reference Configuration |
| 143 |
~~~~~~~~~~~~~~~~~~~~~~~ |
| 144 |
Sample system.conf |
| 145 |
^^^^^^^^^^^^^^^^^^ |
| 146 |
include::system.conf.asciidoc[] |
| 147 |
|
| 148 |
|
| 149 |
Sample init.conf |
| 150 |
^^^^^^^^^^^^^^^^ |
| 151 |
include::init.conf.asciidoc[] |
| 152 |
|
| 153 |
|
| 154 |
Sample genconf_parameters |
| 155 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 156 |
FIXME: still not properly formatted. |
| 157 |
|
| 158 |
include::genconf_parameters.asciidoc[] |
| 159 |
|
| 160 |
|
| 161 |
Sample assigned-spans.conf |
| 162 |
^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 163 |
include::assigned-spans.conf.asciidoc[] |
| 164 |
|
| 165 |
|
| 166 |
Sample span-types.conf |
| 167 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 168 |
include::span-types.conf.asciidoc[] |
| 169 |
|
| 170 |
|
| 171 |
Tonezones |
| 172 |
~~~~~~~~~ |
| 173 |
The file zonedata.c contains the information about the tone zones used |
| 174 |
in libtonezone (and hence also in dahdi_cfg). Here is a list of those zones: |
| 175 |
|
| 176 |
include::tonezones.txt[] |
| 177 |
|
| 178 |
|
| 179 |
DAHDI PERL modules |
| 180 |
~~~~~~~~~~~~~~~~~~ |
| 181 |
The directory xpp has, in addition to helper utilities for the |
| 182 |
Xorcom Astribank, a collection of PERL modules to provide information |
| 183 |
related to DAHDI. The PERL modules themselves are under xpp/perl_modules/ . |
| 184 |
In xpp/ there are several utilities that use those modules: |
| 185 |
- xpp-specific: dahdi_registration, xpp_sync, xpp_blink . |
| 186 |
- General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers |
| 187 |
|
| 188 |
The DAHDI PERL modules will currently only be automatically installed if you |
| 189 |
happen to install the xpp directory. Those utilities require the PERL modules |
| 190 |
to be installed, however they will also look for them in the directory |
| 191 |
perl_modules, and thus can be run directly from the DAHDI source tree. For |
| 192 |
example: |
| 193 |
|
| 194 |
./xpp/dahdi_hardware -v |
| 195 |
|
| 196 |
To get usage information on a program, you can also use perldoc |
| 197 |
(sometimes provided in a package separate from perl itself). For |
| 198 |
instance: |
| 199 |
|
| 200 |
perldoc ./xpp/lsdahdi |
| 201 |
|
| 202 |
Some of them are specific for the Xorcom Astribank and described in its |
| 203 |
documentation. the others are: |
| 204 |
|
| 205 |
lsdahdi:: |
| 206 |
A somewhat glorified `cat /proc/dahdi/*`. |
| 207 |
dahdi_genconf:: |
| 208 |
Generates configuration based on the existing DAHDI channels and on |
| 209 |
/etc/dahdi/genconf_parameters (replaces genzaptelconf as well). |
| 210 |
dahdi_drivers:: |
| 211 |
A two-liner script (not installed by default) that simply returns the |
| 212 |
modules that should be modprobe-d on this system. |
| 213 |
dahdi_hardware:: |
| 214 |
Uses the information from SysFS and its own knowledge to show |
| 215 |
what PCI/USB DAHDI hardware is connected and if it is currently used |
| 216 |
by a driver. Shows also some more information for Astribanks from |
| 217 |
/proc/xpp . |
| 218 |
|
| 219 |
|
| 220 |
PPP Support |
| 221 |
~~~~~~~~~~~ |
| 222 |
DAHDI digital cards can provide data channels through PPP as |
| 223 |
point-to-point connections. This requires a plug-in to the PPP daemon |
| 224 |
that is included in the ppp/ subdirectory. To install it: |
| 225 |
|
| 226 |
1. Make sure you have the PPP source / headers installed. On Debian: |
| 227 |
|
| 228 |
apt-get install ppp-dev |
| 229 |
|
| 230 |
2. Run 'make' on the ppp subdirectory: |
| 231 |
|
| 232 |
make -C ppp |
| 233 |
make -C ppp install |
| 234 |
|
| 235 |
3. Make sure your kernel has support for both PPP (which is common is |
| 236 |
distribution kernels and for HDLC (much less common) - CONFIG_PPP and |
| 237 |
CONFIG_HDLC . |
| 238 |
|
| 239 |
|
| 240 |
Initialization |
| 241 |
-------------- |
| 242 |
This section documents the start up sequence of the DAHDI modules. |
| 243 |
|
| 244 |
There are generally two options: explicit (using an init script) and |
| 245 |
implicit (run from UDEV hook scripts). |
| 246 |
|
| 247 |
Explicit |
| 248 |
~~~~~~~~ |
| 249 |
The dahdi init scripts does the following tasks: |
| 250 |
|
| 251 |
* Loading the module dahdi and any other module listed in |
| 252 |
/etc/dahdi/modules. |
| 253 |
* For xpp (Astribanks) - some specific initializations. See |
| 254 |
README.Astribank. |
| 255 |
* Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] after all modules were |
| 256 |
loaded. |
| 257 |
* A number of other tools may need to be run: |
| 258 |
** link:doc/fxotune.8.html[fxotune] |
| 259 |
** dahdihpec_enable |
| 260 |
|
| 261 |
Only at this point Asterisk (or any other user of DAHDI) can be run. |
| 262 |
|
| 263 |
|
| 264 |
Implicit |
| 265 |
~~~~~~~~ |
| 266 |
(Also known as "hot-plug" or "pinned-spans". This requires: |
| 267 |
|
| 268 |
* dahdi >= 2.8.0 |
| 269 |
* Setting the module parameter auto_assign_spans of dahdi to 0 |
| 270 |
* (Recommended) Asterisk >= 12 - which supports "dahdi create channels". |
| 271 |
|
| 272 |
When a device driver of a DAHDI device finishes initialization, it |
| 273 |
creates a dahdi_device kernel object. A dahdi_device represents a single |
| 274 |
DAHDI device (such as a PCI card) and may have several spans. If the |
| 275 |
value of auto_assign_spans is 1 when dahdi_device is created, spans are |
| 276 |
assigned automatically - each new span gets the first available span |
| 277 |
number and range of channels. However if it is set to 0, spans will not |
| 278 |
get assigned, and user space programs need to assign them. The |
| 279 |
low-level interface for doing so is explained in the section "Span |
| 280 |
Assignment" in the README of DAHDI-Linux. |
| 281 |
|
| 282 |
New Devices |
| 283 |
^^^^^^^^^^^ |
| 284 |
When a kernel object is created or destroyed, the kernel sends an event |
| 285 |
to user space. Those events are normally handled by udevd. Configurations |
| 286 |
for udevd ("udev rules") may be placed in /etc/udev/rules.d or |
| 287 |
/lib/udev/rules.d. This package installs rules that instruct udevd to |
| 288 |
run the script `/usr/share/dahdi/dahdi_handle_device` on each new |
| 289 |
device, which runs all the scripts in `/usr/share/dahdi/handle_device.d`. |
| 290 |
Those scripts will: |
| 291 |
|
| 292 |
* If `/etc/dahdi/span-types.conf` exists, apply it to the device. It is |
| 293 |
used for E1/T1/J1 settings. See |
| 294 |
<<_sample_span_types_conf,sample span-types.conf>>. |
| 295 |
|
| 296 |
* If `/etc/dahdi/assigned-spans.conf` exists, assign the span according |
| 297 |
to it (if it is not specified there: don't assign it). |
| 298 |
used for E1/T1/J1 settings. See |
| 299 |
<<_sample_assigned_spans_conf,sample assigned-spans.conf>>. |
| 300 |
|
| 301 |
* But if that file does not exist, assign the span to the first |
| 302 |
available place. |
| 303 |
|
| 304 |
This script mainly uses the commands |
| 305 |
link:doc/dahdi_span_types.8.html[dahdi_span_types] and |
| 306 |
link:doc/dahdi_span_assignments.8.html[dahdi_span_assignments]. |
| 307 |
|
| 308 |
DAHDI devices are listed under `/sys/bus/dahdi_devices/devices`. |
| 309 |
|
| 310 |
If you want to disable running this script, add the following line to |
| 311 |
`/etc/dahdi/init.conf`: |
| 312 |
............................. |
| 313 |
DAHDI_UDEV_DISABLE_DEVICES=yes |
| 314 |
............................. |
| 315 |
|
| 316 |
|
| 317 |
New Spans |
| 318 |
^^^^^^^^^ |
| 319 |
Once a span is assigned, a kernel object will appear for it. It will be |
| 320 |
listed under its device. As a new kernel object was created, an event is |
| 321 |
sent to udev. |
| 322 |
|
| 323 |
The standard DAHDI udev rules instruct udevd to run the script |
| 324 |
`/usr/share/dahdi/dahdi_span_config` which runs all the scripts in |
| 325 |
`/usr/share/dahdi/span_config.d`. Those script configures the new |
| 326 |
span: |
| 327 |
|
| 328 |
* If system.conf does not exist, generates a temporary configuration |
| 329 |
for the span using link:doc/dahdi_genconf.8.html[dahdi_genconf |
| 330 |
system]. |
| 331 |
|
| 332 |
* Runs link:doc/dahdi_cfg.8.html[dahdi_cfg] on the new span (using `-S` |
| 333 |
and -C`). |
| 334 |
|
| 335 |
* Runs `asterisk -rx 'dahdi create channels'` to add the new channels |
| 336 |
and spans to Asterisk (if they were configured in advance). |
| 337 |
|
| 338 |
If you want to disable running this script, add the following line to |
| 339 |
`/etc/dahdi/init.conf`: |
| 340 |
............................. |
| 341 |
DAHDI_UDEV_DISABLE_SPANS=yes |
| 342 |
............................. |
| 343 |
|
| 344 |
|
| 345 |
New Channels |
| 346 |
^^^^^^^^^^^^ |
| 347 |
DAHDI channels have their own representation in the kernel. The standard |
| 348 |
udev rules that dahdi-tools includes for them, however, don't run a |
| 349 |
script for each device. Each DAHDI channel creates a block device file |
| 350 |
at /dev/dahdi/chan/'span'/'rel-chan', where 'span' and 'rel-chan' are |
| 351 |
each three-digit numbers (e.g: 035). 'span' is the span number and |
| 352 |
'rel-chan' is the channel number relative to the span. |
| 353 |
|
| 354 |
The udev rules generate the following extra symlinks under /dev/dahdi: |
| 355 |
|
| 356 |
* /dev/dahdi/'num' - the channel number. As it was originally (but |
| 357 |
continues beyond 250). |
| 358 |
* /dev/dahdi/devices/'hardware_id'/'rel-span'/'rel-chan' - if the DAHDI |
| 359 |
device has a hardware ID field, provide listing of the device's span |
| 360 |
and channels. |
| 361 |
* /dev/dahdi/devices/@'hardware_id'/'rel-span'/'rel-chan' - likewise for |
| 362 |
the connector field. It has a "@" prefix. |
| 363 |
|
| 364 |
|
| 365 |
include::UPGRADE.txt[] |
| 366 |
|
| 367 |
|
| 368 |
License |
| 369 |
------- |
| 370 |
This package is distributed under the terms of the GNU General Public License |
| 371 |
Version 2, except for some components which are distributed under the terms of |
| 372 |
the GNU Lesser General Public License Version 2.1. Both licenses are included |
| 373 |
in this directory, and each file is clearly marked as to which license applies. |
| 374 |
|
| 375 |
If you wish to use the DAHDI drivers in an application for which the license |
| 376 |
terms are not appropriate (e.g. a proprietary embedded system), licenses under |
| 377 |
more flexible terms can be readily obtained through Digium, Inc. at reasonable |
| 378 |
cost. |
| 379 |
|
| 380 |
|
| 381 |
Reporting Bugs |
| 382 |
-------------- |
| 383 |
Please report bug and patches to the Asterisk bug tracker at |
| 384 |
http://bugs.digium.com/[] in the "DAHDI" category. |
| 385 |
|
| 386 |
|
| 387 |
Links |
| 388 |
----- |
| 389 |
- http://asterisk.org/[] - The Asterisk PBX |
| 390 |
- http://voip-info.org/[] |
| 391 |
- http://voip-info.org/wiki/view/DAHDI[] |
| 392 |
- http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version |
| 393 |
of this file] |