patlooptest: Ignore the first buffered event
[dahdi/tools.git] / README
1 DAHDI Telephony Interface Driver
2 =================================
3 Asterisk Development Team <asteriskteam@digium.com>
4 $Revision$, $Date$
5
6 DAHDI stands for Digium Asterisk Hardware Device Interface. This
7 package contains the userspace 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 There may be cases where you will need a specific version of gcc to build
19 kernel modules.
20
21
22 Extra Libraries
23 ~~~~~~~~~~~~~~~
24 Some libraries are needed for extra utilities that are provided with
25 DAHDI.
26
27 - libusb is needed for building fpga_load, needed for firmware loading of
28   the Xorcom Astribank.
29 - libnewt is needed to build the optional but useful utility dahdi_tool.
30
31
32 Installation
33 ~~~~~~~~~~~~
34 Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
35 ----------------------------------
36 ./configure
37 # optional step: select custom configuration:
38 #make menuselect
39 make
40 make install
41 # To install init scripts and config files:
42 #make config
43 ----------------------------------
44
45
46 Build Tweaks
47 ~~~~~~~~~~~~
48 Partial Build/Install
49 ^^^^^^^^^^^^^^^^^^^^^
50 There are some make targets that are provided to build or install just
51 parts of DAHDI:
52
53 . Build targets:
54   - make: Build DAHDI userspace programs. partial 
55     targets of it:
56     * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`)
57     * make utils: Build libtonezone.
58     * make libs: Build libtonezone.
59 . Install targets:
60   - make install: Installs user space tools into /usr/sbin/ (TODO - list
61     partial targets)
62   - make config: should be run once to configure 
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 th 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 various several tests and based on them generates
79 some files ( build_tools/menuselect-deps and makeopts). You can pass it
80 --with options and variable settings, for 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   ./ocnfig.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 Reference Configuration
120 ~~~~~~~~~~~~~~~~~~~~~~~
121 Sample system.conf
122 ~~~~~~~~~~~~~~~~~~
123 include::system.conf.asciidoc[]
124
125
126 Sample init.conf
127 ~~~~~~~~~~~~~~~~
128 include::init.conf.asciidoc[]
129
130
131 Sample genconf_parameters
132 ~~~~~~~~~~~~~~~~~~~~~~~~~
133 FIXME: still not properly formatted.
134
135 include::genconf_parameters.asciidoc[]
136
137
138 Tonezones
139 ~~~~~~~~~
140 The file zonedata.c contains the information about the tone zones used
141 in libtonezone (and hence also in ztcfg). Here is a list of those zones:
142
143 include::tonezones.txt[]
144
145
146 DAHDI PERL modules
147 ~~~~~~~~~~~~~~~~~~
148 The directory xpp has, in addition to helper utilities for the
149 Xorcom Astribank, a collection of perl modules to provide information
150 related to DAHDI. The perl modules themselves are under xpp/perl_modules/ .
151 In xpp/ there are several utilities that use those modules:
152 - xpp-specific: dahdi_registration, xpp_sync, xpp_blink .
153 - General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers
154
155 The DAHDI perl modules will currently only be automatically installed if you
156 happen to install the xpp directory. Those utilities require the perl modules 
157 to be installed, however they will also look for them in the directory 
158 perl_modules, and thus can be run directly from the DAHDI source tree. For 
159 example:
160
161   ./xpp/dahdi_hardware -v
162
163 To get usage information on a program, you can also use perldoc
164 (sometimes provided in a package separate from perl itself). For
165 instance:
166
167   perldoc ./xpp/lsdahdi
168
169 Some of them are specific for the Xorcom Astribank and described in its
170 docuemntation. the others are:
171
172 lsdahdi:: 
173   A somewhat glorified `cat /proc/dahdi/*`.
174 dahdi_genconf::
175   Generates configuration based on the existing DAHDI channels and on
176   /etc/dahdi/genconf_parameters (replaces genzaptelconf as well).
177 dahdi_drivers::
178   A two-liner script (not installed by default) that simply returns the
179   modules that should be modprobed on this system.
180 dahdi_hardware:: 
181   Uses the information from sysfs and its own knowledge to show
182   what PCI/USB DAHDI hardware is connected and if it is currently used
183   by a driver. Shows also some more information for Astribanks from
184   /proc/xpp .
185
186
187 PPP Support
188 ~~~~~~~~~~~
189 DAHDI digital cards can provide data channels through ppp as
190 point-to-point connections. This requires a plugin to the ppp daemon
191 that is included in the ppp/ subdirectory. To install it:
192
193 1. Make sure you have the PPP source / headers installed. On Debian:
194
195    apt-get install ppp-dev
196
197 2. Run 'make' on the ppp subdirectory:
198
199    make -C ppp 
200    make -C ppp install
201
202 3. Make sure your kernel has support for both PPP (which is common is
203    distribution kernels and for HDLC (much less common) - CONFIG_PPP and
204    CONFIG_HDLC .
205
206
207 include::UPGRADE.txt[]
208
209
210 License
211 -------
212 This package is distributed under the terms of the GNU General Public License
213 Version 2, except for some components which are distributed under the terms of
214 the GNU Lesser General Public License Version 2.1. Both licenses are included
215 in this directory, and each file is clearly marked as to which license applies.
216
217 If you wish to use the DAHDI drivers in an application for which the license
218 terms are not appropriate (e.g. a proprietary embedded system), licenses under
219 more flexible terms can be readily obtained through Digium, Inc. at reasonable
220 cost.
221
222
223 Reporting Bugs
224 --------------
225 Please report bug and patches to the Asterisk bug tracker at
226 http://bugs.digium.com/[] in the "DAHDI" category.
227
228
229 Links
230 -----
231 - http://asterisk.org/[] - The Asterisk PBX
232 - http://voip-info.org/[]
233 - http://voip-info.org/wiki/view/DAHDI[]
234 - http://docs.tzafrir.org.il/dahdi-tools/README.html[Up-to-date HTML version
235   of this file]