xpp: README: hwid attribute of the xpd sysfs node
[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 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]