PIC 4 rev. 7381: fix T1 returning signaling register in non-CAS
[asterisk-tools:sruffells-dahdi-linux.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.
7
8 This package contains the kernel modules for DAHDI. For the required 
9 userspace tools see the package dahdi-tools.
10
11 Supported Hardware
12 ------------------
13 Digital Cards
14 ~~~~~~~~~~~~~
15 - wct4xxp:
16   * Digium TE205P/TE207P/TE210P/TE212P: PCI dual-port T1/E1/J1
17   * Digium TE405P/TE407P/TE410P/TE412P: PCI quad-port T1/E1/J1
18   * Digium TE220: PCI-Express dual-port T1/E1/J1
19   * Digium TE420: PCI-Express quad-port T1/E1/J1
20 - wcte12xp:
21   * Digium TE120P: PCI single-port T1/E1/J1
22   * Digium TE121: PCI-Express single-port T1/E1/J1
23   * Digium TE122: PCI single-port T1/E1/J1
24 - wcte11xp:
25   * Digium TE110P: PCI single-port T1/E1/J1
26 - wct1xxp: 
27   * Digium T100P: PCI single-port T1
28   * Digium E100P: PCI single-port E1
29 - wcb4xxp:
30   * Digium B410: PCI quad-port BRI
31 - tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project
32
33
34 Analog Cards
35 ~~~~~~~~~~~~
36 - wctdm24xxp: 
37   * Digium TDM2400P/AEX2400: up to 24 analog ports
38   * Digium TDM800P/AEX800: up to 8 analog ports
39   * Digium TDM410P/AEX410: up to 4 analog ports
40   * Digium Hx8 Series: Up to 8 analog or BRI ports
41 - wctdm:
42   * Digium TDM400P: up to 4 analog ports
43 - xpp: Xorcom Astribank: a USB connected unit of up to 32 ports
44   (including the digital BRI and E1/T1 modules)
45 - wcfxo: X100P, similar and clones. A simple single-port FXO card
46
47
48 Other Drivers
49 ~~~~~~~~~~~~~
50 - pciradio: Zapata Telephony PCI Quad Radio Interface
51 - wctc4xxp: Digium hardware transcoder cards (also need dahdi_transcode)
52 - dahdi_dynamic_eth: TDM over Ethernet (TDMoE) driver. Requires dahdi_dynamic
53 - dahdi_dynamic_loc: Mirror a local span. Requires dahdi_dynamic
54 - dahdi_dummy: A dummy driver that only provides a DAHDI timing source.
55
56
57 Installation
58 ------------
59 If all is well, you just need to run the following:
60
61   make
62   make install
63
64 You'll need the utilities provided in the package dahdi-tools to 
65 configure DAHDI devices on your system.
66
67 If using `sudo` to build/install, you may need to add /sbin to your PATH.
68
69 If you still have problems, read further.
70
71
72 Build Requirements
73 ~~~~~~~~~~~~~~~~~~
74 gcc and friends. Generally you will need to install the package gcc.
75 There may be cases where you will need a specific version of gcc to build
76 kernel modules.
77
78 TODO: copy build requirement from Zaptel README.
79
80
81 Installing to a Subtree
82 ~~~~~~~~~~~~~~~~~~~~~~~
83 The following may be useful when testing the package or when preparing a
84 package for a binary distribution (such as an rpm package) installing
85 onto a subtree rather than on the real system. 
86
87   make install DESTDIR=targetdir
88
89 This can be useful for any partial install target of the above (e.g:
90 install-modules or install-programs).
91
92 the targetdir must be an absolute path, at least if you install the
93 modules. To install to a relative path you can use something like:
94
95   make install-modules DESTDIR=$PWD/target
96
97
98 Extra Modules
99 ~~~~~~~~~~~~~
100 To build extra modules / modules directory not included in the DAHDI 
101 distribution, use the optional variables MODULES_EXTRA and
102 SUBDIRS_EXTRA:
103
104   make MODULES_EXTRA="mod1 mod2"
105   make MODULES_EXTRA="mod1 mod2" SUBDIRS_EXTRA="subdir1/ subdir1/"
106
107
108 Static Device Files
109 ~~~~~~~~~~~~~~~~~~~
110 Userspace programs communicate with the DAHDI modules through special
111 device files under /dev/dahdi .  Those are normally created by udev, but
112 if you use an embedded-type system and don't wish to use udev, you can
113 generate them with the following script, from the source directory:
114
115   ./build_tools/make_static_devs
116
117 This will generate the device files under /dev/dahdi . If you need to
118 generate them elsewhere (e.g. `tmp/newroot/dev/dahdi`) use the option -d
119 to the script:
120
121   ./build_tools/make_static_devs -d tmp/newroot/dev/dahdi
122
123
124 Installing the B410P drivers with mISDN
125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 DAHDI includes the wcb4xxp driver for the B410P, however, support for the
127 B410P was historically provided by mISDN.  If you would like to use the mISDN
128 driver with the B410P, please comment out the wcb4xxp line in /etc/dahdi/modules.
129 This will prevent DAHDI from loading wcb4xxp which will conflict with the mISDN
130 driver.
131
132 To install the mISDN driver for the B410P, please see http://www.misdn.org for
133 more information, but the following sequence of steps is roughly equivalent to
134 'make b410p' from previous releases.
135
136   wget http://www.misdn.org/downloads/releases/mISDN-1_1_8.tar.gz
137   wget http://www.misdn.org/downloads/releases/mISDNuser-1_1_8.tar.gz
138   tar xfz mISDN-1_1_8.tar.gz
139   tar xfz mISDNuser-1_1_8.tar.gz
140   pushd mISDN-1_1_8
141   make install
142   popd
143   pushd mISDNuser-1_1_8
144   make install
145   popd
146   /usr/sbin/misdn-init config
147
148 You will then also want to make sure /etc/init.d/misdn-init is started
149 automatically with either 'chkconfig --add misdn-init' or 'update-rc.d
150 misdn-init defaults 15 30' depending on your distribution.
151
152 NOTE:  At the time this was written, misdn-1.1.8 is not compatible the
153 2.6.25 kernel.  Please use a kernel version 2.6.25 or earlier.
154
155
156 OSLEC
157 ~~~~~
158 http://www.rowetel.com/ucasterisk/oslec.html[OSLEC] is an 
159 Open Source Line Echo Canceller. It is currently in the staging subtree
160 of the mainline kernel and will hopefully be fully merged at around
161 version 2.6.29. The echo canceller module dahdi_echocan_oslec
162 provides a DAHDI echo canceller module that uses the code from OSLEC. As
163 OSLEC has not been accepted into mainline yet, its interface is not set
164 in stone and thus this driver may need to change. Thus it is not
165 built by default.
166
167 Luckily the structure of the dahdi-linux tree matches that of the kernel
168 tree. Hence you can basically copy drivers/staging/echo and place it
169 under driver/staging/echo . In fact, dahdi_echocan_oslec assumes that
170 this is where the oslec code lies. If it is elsewhere you'll need to fix
171 the #include line.
172
173 Thus for the moment, the simplest way to build OSLEC with dahdi is:
174
175 1. Copy the directory `drivers/staging/echo` from a recent kernel tree 
176    (at least 2.6.28-rc1) to the a subdirectory with the same name in the
177    dahdi-linux tree.
178
179 2. Edit drivers/dahdi/Kbuild and uncomment the two lines related to OSLEC.
180
181 After doing that, you'll see the following when building (running
182 'make')
183
184   ...
185   CC [M] /home/tzafrir/dahdi-linux/drivers/dahdi/dahdi_echocan_oslec.o
186   CC [M] /home/tzafrir/dahdi-linux/drivers/dahdi/../staging/echo/echo.o
187   ...
188
189 As this is an experimental driver, problems building and using it should 
190 be reported on the 
191 https://lists.sourceforge.net/lists/listinfo/freetel-oslec[OSLEC mailing
192 list].
193
194 Live Install
195 ~~~~~~~~~~~~
196 In many cases you already have DAHDI installed on your system but would
197 like to try a different version. E.g. in order to check if the latest
198 version fixes a bug that your current system happens to have.
199
200 DAHDI-linux includes a script to automate the task of installing DAHDI
201 to a subtree and using it instead of the system copy. Module loading
202 through modprobe cannot be used. Thus the script pre-loads the required
203 modules with insmod (which requires some quesswork as for which modules
204 to load). It also sets PATH and other environment variables to make all
205 the commands do the right thing.
206
207 There is an extra mode of operation to copy all the required files to a
208 remote host and run things there, for those who don't like to test code
209 on thir build system.
210
211 Live Install: The Basics
212 ^^^^^^^^^^^^^^^^^^^^^^^^
213 Basic operation is through running
214
215   ./build_tools/live_dahdi
216
217 from the root directory of the dahdi-linux tree. Using DAHDI requires
218 dahdi-tools as well, and the script builds and installs dahdi-tools. By
219 default it assumes the tree of dahdi-tools is in the directory
220 'dahdi-tools' alongside the dahdi-linux tree.  If you want to checkout
221 the trunks from SVN, use:
222
223   svn checkout http://svn.asterisk.org/svn/dahdi/linux/trunk dahdi-linux
224   svn checkout http://svn.asterisk.org/svn/dahdi/tools/trunk dahdi-tools
225   cd dahdi-linux
226
227 If the tools directory resides elsewhere, you'll need to edit
228 live/live.conf (see later on). The usage message of live_dahdi:
229
230  Usage:                    equivalent of:
231  live_dahdi configure      ./configure
232  live_dahdi install        make install
233  live_dahdi config         make config
234  live_dahdi unload         /etc/init.d/dahdi stop
235  live_dahdi load           /etc/init.d/dahdi start
236  live_dahdi reload         /etc/init.d/dahdi restart
237  live_dahdi xpp-firm       (Reset and load xpp firmware)
238  live_dahdi rsync TARGET   (copy filea to /tmp/live in host TARGET)
239  live_dahdi exec  COMMAND  (Run COMMAND in 'live' environment)
240
241 Normally you should run:
242
243  ./build_tools/live_dahdi configure
244  ./build_tools/live_dahdi install
245  ./build_tools/live_dahdi config
246
247 to build and install everything. Up until now no real change was done.
248 This could actually be run by a non-root user. All files are installed
249 under the subdirectory live/ .
250
251 Reloading the modules (and restarting Asterisk) is done by:
252
253  ./build_tools/live_dahdi reload
254
255 Note: this stops Asterisk, unloads the DAHDI modules, loads the DAHDI
256 modules from the live/ subdirectory, configures the system and re-starts
257 Asterisk. This *can* do damage to your system. Furthermore, the DAHDI
258 configuration is generated by dahdi_genconf. It can be influenced by
259 a genconf_parameters file. But it may or may not be what you want.
260
261 If you want to run a command in the environment of the live system, use
262 the command 'exec':
263
264  ./build_tools/live_dahdi lsdahdi
265  ./build_tools/live_dahdi dahdi_hardware -v
266
267 Note however:
268
269  ./build_tools/live_dahdi dahdi_cfg -c live/etc/dahdi/system.conf
270
271 Live Install Remote
272 ^^^^^^^^^^^^^^^^^^^
273 As mentioned above, live_dahdi can also copy all the live system files
274 to a remote system and run from there. This requires rsync installed on
275 both system and assumes you can connect to the remove system through
276 ssh.
277
278   tzafrir@hilbert $ ./build_tools/live_dahdi rsync root@david
279   root@david's password:
280   <f+++++++++ live_dahdi
281   cd+++++++++ live/
282   <f+++++++++ live/live.conf
283   cd+++++++++ live/dev/
284   cd+++++++++ live/dev/dahdi/
285   cd+++++++++ live/etc/
286   cd+++++++++ live/etc/asterisk/
287   cd+++++++++ live/etc/dahdi/
288   <f+++++++++ live/etc/dahdi/genconf_parameters
289   <f+++++++++ live/etc/dahdi/init.conf 
290   ...
291
292 As you can see, it copies the script itselfand the whole live/
293 subdirectory. The target directory is /tmp/live on the target directory
294 (changing it should probably be simple, but I never needed that).
295
296 Then, on the remove computer:
297
298   root@david:/tmp# ./live_dahdi reload
299
300
301 Configuring a Live Install
302 ^^^^^^^^^^^^^^^^^^^^^^^^^^
303 The live_dahdi script reads a configuration file in 'live/live.conf' if
304 it exists. This file has the format of a shell script snippet:
305
306  var1=value # a '#' sign begins a comment
307  var2='value'
308
309  # comments and empty lines are ignored
310  var3="value"
311
312 The variables below can also be overriden from the environment:
313
314  var1='value' ./build_tools/live_dahdi
315
316 ===== LINUX_DIR
317 The relative path to the dahdi-linux tree. The default is '.' and normally
318 there's no reason to override it.
319
320 ===== TOOLS_DIR
321 The relative path to the dahdi-tools tree. The default is 'dahdi-tools'.
322
323 ===== XPP_SYNC
324 Set a syncing astribank. See xpp_sync(8). Default is 'auto'.
325
326 ===== AST_SCRIPT
327 The command for an init.d script to start/stop Asterisk. Should accept 
328 'start' and 'stop' commands. Use 'true' if you want to make that a
329 no-op. Defaults to '/etc/init.d/asterisk' .
330
331 ===== MODULES_LOAD
332 Manual list of modules. They will be loaded by insmod. If reside in a 
333 subdir, add it explicitly. Modules for the drivers that are detected on
334 the system will be added by the script. Default: 'dahdi
335 dahdi_echocan_mg2'
336
337 ===== REMOVE_MODULES
338 A list of modules to remove when unloading. Will be resolved
339 recursively. The default is 'dahdi'. You may also want to have 'oslec'
340 or 'hpec' there if you use them.
341
342
343 Module Parameters
344 -----------------
345 The kernel modules can be configured through module parameters. Module
346 parameters can optionally be set at load time. They are normally set (if
347 needed) by a line in a file under /etc/modprobe.d/ or in the file
348 /etc/modprobe.conf.
349
350 Example line:
351
352   options dahdi debug=1
353
354 The module parameters can normally be modified at runtime through sysfs:
355
356   pungenday:~# cat /sys/module/dahdi/parameters/debug 
357   0
358   pungenday:~# echo 1 >/sys/module/dahdi/parameters/debug
359   pungenday:~# cat /sys/module/dahdi/parameters/debug 
360   1
361
362 Viewing and setting parameters that way is possible as of kernel 2.6 .
363 In kernels older than 2.6.10, the sysfs "files" for the parameters
364 reside directly under /sys/module/'module_name' .
365
366 Useful module parameters:
367
368 debug (most modules)::
369   Sets debug mode / debug level. With most modules 'debug' can be either
370   disabled (0, the default value) or enabled (any other value). 
371   +
372   +
373   wctdm and wcte1xp print several extra debugging messages if the value
374   of debug is more than 1.
375   +
376   +
377   Some modules have "debugging flags" bits - the value of debug is a
378   bitmask and several messages are printed if some bits are set:
379   - dahdi_dummy:
380     * 1: DEBUG_GENERAL - general error messages.
381     * 2: DEBUG_TICKS - Show that the module is alive :-)
382   - wctdm24xxp:
383     * 1: DEBUG_CARD
384     * 2: DEBUG_ECHOCAN
385   - wct4xxp:
386     * 1: DEBUG_MAIN
387     * 2: DEBUG_DTMF
388     * 4: DEBUG_REGS
389     * 8: DEBUG_TSI
390     * 16: DEBUG_ECHOCAN
391     * 32: DEBUG_RBS
392     * 64: DEBUG_FRAMER
393   - xpp: See also README.Astribank:
394     * 1: GENERAL - General debug comments.
395     * 2: PCM - PCM-related messages. Tend to flood logs.
396     * 4: LEDS - Anything related to the LEDs status control. The driver
397       produces a lot of messages when the option is enabled.
398     * 8: SYNC - Synchronization related messages.
399     * 16: SIGNAL - DAHDI signalling related messages.
400     * 32: PROC - Messages related to the procfs interface.
401     * 64: REGS - Reading and writing to chip registers. Tends to flood
402           logs.
403     * 128: DEVICES - Device instantiation, destruction and such.
404     * 256 - COMMANDS - Protocol commands. Tends to flood logs.
405
406 deftaps (dahdi)::
407   The default size for the echo canceller. The number is in "taps", that
408   is "samples", 1/8 ms. The default is 64 - for a tail size of 8 ms.
409   +
410   +
411   Asterisk's chan_dahdi tends to pass its own value anyway, with a
412   different default size. So normally setting this doesn't change
413   anything.
414
415 To get a list of parameters supported by a module, use 
416
417   modinfo module_name
418
419 Or, for a module you have just built:
420
421   modinfo ./module_name.ko
422
423 For the xpp modules this will also include the description and default
424 value of the module. You can find a list of useful xpp module parameters
425 in README.Astribank .
426
427
428 Internals
429 ---------
430 DAHDI Device Files
431 ~~~~~~~~~~~~~~~~~~
432 Userspace programs will usually interact with DAHDI through device
433 files under the /dev/dahdi directory (pedantically: character device files 
434 with major number 196) . Those device files can be generated statically
435 or dynamically through the udev system.
436
437 * /dev/dahdi/ctl (196:0) - a general device file for various information and
438   control operations on the DAHDI channels.
439 * /dev/dahdi/NNN (196:NNN) - for NNN in the range 1-249. A device file for
440   DAHDI channel NNN. It can be used to read data from the channel
441   and write data to the channel.
442 * /dev/dahdi/transcode (196:250) - Used to connect to a DAHDI transcoding
443   device.
444 * /dev/dahdi/timer (196:253) - Allows setting timers. Used anywhere?
445 * /dev/dahdi/channel (196:254) - Can be used to open an arbitrary DAHDI
446   channel. This is an alternative to /dev/dahdi/NNN that is not limited to
447   249 channels.
448 * /dev/dahdi/pseudo (196:255) - A timing-only device. Every time you open
449   it, a new DAHDI channel is created. That DAHDI channel is "pseudo" -
450   DAHDI receives no data in it, and only sends garbage data with the
451   same timing as the DAHDI timing master device.
452
453
454 DAHDI Timing
455 ~~~~~~~~~~~~
456 A PBX system should generally have a single clock. If you are connected to a
457 telephony provider via a digital interface (e.g: E1, T1) you should also
458 typically use the provider's clock (as you get through the interface). Hence
459 one important job of Asterisk is to provide timing to the PBX. 
460
461 DAHDI "ticks" once per millisecond (1000 times per second). On each tick every
462 active DAHDI channel reads and 8 bytes of data. Asterisk also uses this for
463 timing, through a DAHDI pseudo channel it opens.
464
465 However, not all PBX systems are connected to a telephony provider via a T1 or
466 similar connection. With an analog connection you are not synced to the other
467 party. And some systems don't have DAHDI hardware at all.  Even a digital card
468 may be used for other uses or is simply not connected to a provider. DAHDI
469 cards are also capable of providing timing from a clock on card. Cheap x100P
470 clone cards are sometimes used for that purpose.
471
472 If all the above fail, you can use the module dahdi_dummy to provide timing
473 alone without needing any DAHDI hardware. It will work with most systems and
474 kernels.
475
476 You can check the DAHDI timing source with dahdi_test, which is a small
477 utility that is included with DAHDI. It runs in cycles. In each such cycle it
478 tries to read 8192 bytes, and sees how long it takes. If DAHDI is not loaded
479 or you don't have the device files, it will fail immediately. If you lack a
480 timing device it will hang forever in the first cycle. Otherwise it will just
481 give you in each cycle the percent of how close it was. Also try running it
482 with the option -v for a verbose output.
483
484 To check the clock source that is built into dahdi_dummy, you can either look
485 at title of its span in /proc/dahdi file for a "source:" in the description.
486 Or even run:
487
488   strings dahdi.ko | grep source:
489
490
491 Spans and Channels
492 ~~~~~~~~~~~~~~~~~~
493 DAHDI provides telephony *channels* to the userspace applications. 
494 Those channels are channels are incorporated into logical units called
495 *spans*.
496
497 With digital telephony adapters (e.g: E1 or T1), a span normally 
498 represents a single port. With analog telephony a span typically
499 represents a PCI adapter or a similar logical unit.
500
501 Both channels and spans are identified by enumerating numbers (beginning
502 with 1). The number of the channel is the lowest unused one when it is
503 generated, and ditto for spans.
504
505 There are up to 128 spans and 1024 channels. This is a hard-wired limit
506 (see dahdi/user.h . Several places throuout the code assume a channel
507 number fits in a 16 bits number). Channel and span numbers start at 1.
508
509
510 Dynamic Spans
511 ~~~~~~~~~~~~~
512 Dynamic spans are spans that are not represented by real hardware.
513 Currently there are two types of them:
514
515 tdmoe::
516   TDM over Ethernet. A remote span is identified by an ethernet (MAC)
517   address.
518
519 local::
520   Generates a span that is actually a loopback to a different local
521   span.
522
523 Modules that support the dynamic spans are typically loaded at the time
524 the ioctl DAHDI_DYNAMIC_CREATE is called. This is typically called by
525 dahdi_cfg when it has a line such as:
526
527   dynamic,somename,params
528
529 in /etc/dahdi/system.conf . In that case it will typically try to load
530 (through modprobe) the modules dahdi_dynamic and
531 dahdi_dynamic_'somename'. It will then pass 'params' to it.
532
533 Dynamic spans are known to be tricky and are some of the least-tested
534 parts of DAHDI.
535
536
537 Echo Cancellers
538 ~~~~~~~~~~~~~~~
539 (To be documented later)
540
541
542 Tone Zones
543 ~~~~~~~~~~
544 (To be documented later)
545
546
547 PROCFS Interface: /proc/dahdi
548 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
549 A simple way to get the current list of spans and channels each span contains
550 is the files under /proc/dahdi . /proc/dahdi is generated by DAHDI as it
551 loads. As each span registers to DAHDI, a file under /proc/dahdi is created
552 for it. The name of that file is the number of that span.
553
554 Each file has a 1-line title for the span followed by a few optional
555 general counter lines, an empty line and then a line for each channel of
556 the span. 
557
558 The title line shows the number of the span, its name and title, and 
559 (potentially) the alarms in which it is.
560
561 The title shows the span number and name, followed by any alarms the
562 span may have: For example, here is the first span in my system (with no
563 alarms):
564
565   Span 1: XBUS-00/XPD-00 "Xorcom XPD #0/0: FXS"
566
567 There are several extra optional keywords that may be added there:
568
569 (Master)::
570   This span is the master span. See <<_dahdi_timing,DAHDI Timing>>.
571 ClockSource::
572   The clock source among several spans that belong to a single E1/J1/T1
573   card.
574 RED/YELLOW/RED/NOTOPEN/LOOP/RECOVERING::
575   The span is in alarm
576
577 Following that line there may be some optional lines about IRQ misses,
578 timing slips and such, if there are any.
579
580 The channel line for each channel shows its channel number, name and the
581 actual signalling assigned to it through dahdi_cfg. Before being configured by
582 dahdi_cfg: This is DAHDI channel 2, whose name is 'XPP_FXS/0/0/1'.
583
584            2 XPP_FXS/0/0/1
585
586 After being configured by dahdi_cfg: the signalling 'FXOLS' was added. FXS
587 channels have FXO signalling and vice versa:
588
589            2 XPP_FXS/0/0/1 FXOLS
590
591 If the channel is in use (typically opened by Asterisk) then you will
592 see an extra '(In use)':
593
594            2 XPP_FXS/0/0/1 FXOLS (In use)
595
596
597 User-space Interface
598 ~~~~~~~~~~~~~~~~~~~~
599 User-space programs can only work with DAHDI channels. The basic
600 operation is 'read()' to read audio from the device and write() to write
601 audio to it. Audio can be encoded as either alaw (G.711a) or (m)ulaw
602 (G.711u). See the ioctl DAHDI_SETLAW.
603
604 While it is technically possible to use /dev/dahdi/NUMBER directly, this
605 will only work for channel numbers up to 249. Generally you should use:
606
607   int channo = CHAN_NUMBER_TO_OPEN;
608   int rc;
609   int fd = open("/dev/dahdi/channel", O_RDRW, 0600);
610   // Make sure fd >= 0
611   rc = ioctl(fd, DAHDI_SPECIFY, &channo) < 0);
612   // Make sure this rc >= 0
613
614 FIXME: there's more to tell about the user-space interface.
615
616
617 Configuration
618 ~~~~~~~~~~~~~
619 Most of the configuration is applied from userspace using the tool
620 'dahdi_cfg' in the package dahdi_tools. This section will not cover the
621 specifics of that file. Rather it will cover the way configuration from
622 this file is applied. Also note that there are other methods to
623 configure DAHDI drivers: there are <<_module_parameters,Module
624 Parameters>>. The xpp driver have their own separate initialization
625 scripts and xpp.conf that arecovered in README.Astribank.
626
627 When a span is registered, it is considered "unconfigured". Only after
628 dahdi_cfg has been run to apply configuration, the span is ready to run.
629 The only exception to that is 'dahdi_dummy', which does not need any
630 configuration.
631
632 Some of the configuration is handled by the DAHDI core. Some of it is
633 handled by callbacks, which are function pointers in the `struct
634 dahdi_span': 'spanconfig', 'chanconfig' and (in a way) 'startup'.
635
636 Dahdi_cfg starts by reading the configuration from the configuration
637 file ('/etc/dahdi/system.conf', by default), and creating a local
638 configuration to apply. If you use -v, at this stage it will pront the
639 configuration that is "about to be configured". Then it will start to
640 actually apply the configuration.
641
642 Before actually applying configuration, it destroys any existing
643 <<_dynamic_spans,dynamic spans>> and generates new ones (if so
644 configured. FIXME: what about running DAHDI_SPANCONFIG for new dynamic
645 spans?).
646
647 Next thing it will do is apply the parameters from *span* lines using
648 the ioctl DAHDI_SPANCONFIG. Some generic processing of parameters passed
649 in DAHDI_SPANCONFIG is done in the DAHDI core, in the callback function
650 spanconfig in , but most of it is left to 'spanconfig' callback of the
651 span (if it exists. This one typically does not exists on analog cards).
652
653 Now dahdi_cfg will ask each existing channel for its existing
654 configuration and apply configuration if configuration changes are
655 needed. Configuration is applied to the channels using the ioctl call
656 DAHDI_CHANCONFIG ioctl. As in the case of the span configuration, part
657 of it is applied by the DAHDI core, and then it is handed over to the
658 span's chanconfig callback. Typically all spans will have such a
659 callback.
660
661 <<_echo_cancellers,Echo cancellers>> and <<_tone_zones,tone-zones>> are
662 handled separately later. 
663
664 Once everything is done, the ioctl DAHDI_STARTUP is called for every
665 span. This is also translated to a call to the optional span callback
666 'startup'.
667
668 Finally the ioctl DAHDI_HDLC_RATE is called for every channel (that is:
669 if '56k' is not set for the channel, it will be explicitly set to the
670 standard HDLC rate of 64k).
671
672
673 Low-Level Drivers
674 ~~~~~~~~~~~~~~~~~
675 Low-level drivers create spans ('struct dahdi_span'). They register the
676 spans with the DAHDI core using 'dahdi_register()'.
677
678 'struct dahdi_span' has a number of informative members that are updated
679 solely by the low-level driver:
680
681 name::
682   A concise span name. E.g.: Foo/1
683 desc::
684   A slightly longer span name.
685 spantype::
686   Span type in text form.
687 manufacturer::
688   Span's device manufacturer
689 devicetype::
690   Span's device type
691 location::
692   span device's location in system
693 irq::
694   IRQ for this span's hardware
695 irqmisses::
696   Interrupt misses
697 timingslips::
698   Clock slips
699
700 There are various function pointers in the struct 'dahdi_span' which are
701 used by the DAHDI core to call the low-level driver. Most of them are
702 optional.
703
704 The following apply to a span:
705
706 setchunksize::
707   FIXME: seems to be unused.
708
709 spanconfig::
710   Basic span configuration (called from dahdi_cfg).
711         
712 startup::
713   Last minute initialization after the configuration was applied.
714         
715 shutdown::
716   Explicit shutdown (e.g. for dynamic spans). Normally not needed.
717         
718 maint::
719   Enable/disable maintinance mode (FIXME: document).
720
721 sync_tick::
722   Get notified that the master span has ticked.
723
724 The following apply to a single channel.
725
726 chanconfig::
727   Configure the channel (called from dahdi_cfg).
728
729 open::
730   Channel was opened for read/write from user-space.
731
732 close::
733   Channel was closed by user-space.
734
735 ioctl::
736   Handle extra ioctls. Should return -ENOTTY if ioctl is not known to
737   the channel
738
739 echocan_create::
740   Create a custom echo canceller. Normally used for providing a hardware
741   echo canceller. If NULL, the standard DAHDI echo canceller modules
742   will be used.
743
744 rbsbits::
745   Copy signalling bits to device. See below on signalling.
746
747 hooksig::
748   Implement RBS-like signalling-handling. See below on signalling.
749
750 sethook::
751   Handle signalling yourself. See below on signalling.
752
753 hdlc_hard_xmit::
754   Used to tell an onboard HDLC controller that there is data ready to
755   transmit.
756
757 audio_notify::
758   (if DAHDI_AUDIO_NOTIFY is set) - be notified when the channel is (or
759   isn't) in audio mode. Which may mean (for an ISDN B-channel) that its
760   data need not be sent.
761
762 There are several alternative methods for a span to use for
763 signalling. One of them should be used.
764
765 Signalling: rbsbits
766 ^^^^^^^^^^^^^^^^^^^
767 If the device is a CAS interface, the driver should copy the signalling
768 bits to and from the other side, and DAHDI will handle the signalling.
769 The driver just need to provide a 'rbsbits' and set DAHDI_FLAG_RBS in
770 the span->flags.
771
772 Note that 'rbs' (Robed Bits Signalling) here merely refers to the (up
773 to) 4 signalling bits of the channel. In T1 they are transmitted by
774 "robbing" bits from the channels and hence the name. In E1 they are
775 transmitted in a timeframe of their own.
776
777 The driver should then signal a change in the signalling bits in a
778 channel using dahdi_rbsbits().
779
780
781 Signalling: hooksig
782 ^^^^^^^^^^^^^^^^^^^
783 If the device does not know about signalling bits, but has their
784 equivalents (i.e. can disconnect battery, detect off hook, generate
785 ring, etc directly) then the driver can specify a 'sethook' function and
786 set DAHDI_FLAG_RBS in span->flags. In that case DAHDI will call that
787 function whenever the signalling state changes.
788
789 The hooksig function is only used if the rbsbits function is not set.
790
791 The span should notify DAHDI of a change of signalling in a channel using
792 dahdi_hooksig().
793
794
795 Signalling: sethook
796 ^^^^^^^^^^^^^^^^^^^
797 Alternatively, if DAHDI_FLAG_RBS is not set in the flags of the span (to
798 use either rbsbits or hooksig), the DAHDI core will try to call the
799 'sethook' function of the span (if it exists) to handle individual hook
800 states.
801
802 The span should then notify DAHDI of a change in the signalling state
803 using dahdi_sethook().
804
805 FIXME: anybody using this one?
806
807
808 ABI Compatibility
809 ~~~~~~~~~~~~~~~~~
810 Like any other kernel code, DAHDI strives to maintain a stable interface to
811 userspace programs. The API of DAHDI to userspace programs, dahdi/user.h, has
812 remained backward-compatible for a long time and is expected to remain so in
813 the future. With the ABI (the bits themselves) things are slightly trickier.
814
815 DAHDI's interface to userspace is mostly ioctl(3) calls. Ioctl calls
816 are identified by a number that stems from various things, one of which
817 is the size of the data structure passed between the kernel and
818 userspace. 
819
820 Many of the DAHDI ioctl-s use some specific structs to pass information
821 between kernel and userspace. In some cases the need arose to pass a few
822 more data members in each call. Simply adding a new member to the struct
823 would have meant a new number for the ioctl, as its number depends on
824 the size of the data passed.
825
826 Thus we would add a new ioctl with the same base number and with the
827 original struct.
828
829 So suppose we had the following ioctl:
830 ----------------------------------
831 struct dahdi_example {
832         int sample;
833 }
834
835 #define DAHDI_EXAMPLE     _IOWR (DAHDI_CODE, 62, struct dahdi_example)
836 ----------------------------------
837
838 And we want to add the field 'int onemore', we won't just add it to the
839 struct. We will do something that is more complex:
840 ------------------------------------
841 /* The original, unchanged: */
842 struct dahdi_example_v1 {
843         int sample;
844 }
845
846 /* The new struct: */
847 struct dahdi_example {
848         int sample;
849         int onemore;
850 }
851
852 #define DAHDI_EXAMPLE_V1  _IOWR(DAHDI_CODE, 62, struct dahdi_example_v1)
853 #define DAHDI_EXAMPLE     _IOWR(DAHDI_CODE, 62, struct dahdi_example)
854 ------------------------------------
855 We actually have here two different ioctls: the old DAHDI_EXAMPLE would be
856 0xC004DA3E . DAHDI_EXAMPLE_V1 would have the same value. But the new value
857 of DAHDI_EXAMPLE would be 0xC008DA3E .
858
859 Programs built with the original dahdi/user.h (before the change) use the
860 original ioctl, whether or not the kernel code is actually of the newer
861 version. Thus in most cases there are no compatibility issues.
862
863 When can we have compatibility issues? If we have code built with the new
864 dahdi/user.h, but the loaded kernel code (modules) are of the older version.
865 Thus the userspace program will try to use the newer DAHDI_EXAMPLE (0xC008DA3E).
866 But the kernel code has no handler for that ioctl. The result: the error 25,
867 ENOTTY, which means "Inappropriate ioctl for device".
868
869 As a by-product of that method, for each interface change a new #define is
870 added. That definition is for the old version and thus it might appear
871 slightly confusing in the code, but it is useful for writing code that works
872 with all versions of DAHDI. 
873
874 Past Incompatibilities
875 ^^^^^^^^^^^^^^^^^^^^^^
876 .DAHDI 2.3:
877 DAHDI_SPANINFO_V1 (extra members added). This will typically only be
878 used on ISDN (PRI/BRI) spans in Asterisk.
879
880 .DAHDI 2.2:
881 * DAHDI_GET_PARAMS_V1, DAHDI_GETCONF_V1, DAHDI_SETCONF_V1,
882   DAHDI_GETGAINS_V1 ('direction' changed from 'R' to 'RW' to fix
883   FreeBSD support).
884 * DAHDI_CONFDIAG_V1, DAHDI_CHANDIAG_V1 (fixed direction).
885
886
887 Alarm Types
888 ~~~~~~~~~~~
889 An alarm indicates that a port is not available for some reason. Thus it
890 is probably not a good idea to try to call out through it.
891
892
893 Red Alarm
894 ^^^^^^^^^
895 Your T1/E1 port will go into red alarm when it cannot maintain
896 synchronization with the remote switch.  A red alarm typically
897 indicates either a physical wiring problem, loss of connectivity, or a
898 framing and/or line-coding mismatch with the remote switch.  When your
899 T1/E1 port loses sync, it will transmit a yellow alarm to the remote
900 switch to indicate that it's having a problem receiving signal from
901 the remote switch.
902
903 The easy way to remember this is that the R in red stands for "right
904 here" and "receive"... indicating that we're having a problem right
905 here receiving the signal from the remote switch.
906
907
908 Yellow Alarm 
909 ^^^^^^^^^^^^
910 (RAI -- Remote Alarm Indication)
911
912 Your T1/E1 port will go into yellow alarm when it receives a signal
913 from the remote switch that the port on that remote switch is in red
914 alarm. This essentially means that the remote switch is not able to
915 maintain sync with you, or is not receiving your transmission.
916
917 The easy way to remember this is that the Y in yellow stands for
918 "yonder"... indicating that the remote switch (over yonder) isn't able
919 to see what you're sending.
920
921
922 Blue Alarm
923 ^^^^^^^^^^
924 (AIS -- Alarm Indication Signal)
925
926 Your T1/E1 port will go into blue alarm when it receives all unframed
927 1s on all timeslots from the remote switch.  This is a special signal
928 to indicate that the remote switch is having problems with its
929 upstream connection.  dahdi_tool and Asterisk don't correctly indicate
930 a blue alarm at this time.  The easy way to remember this is that
931 streams are blue, so a blue alarm indicates a problem upstream from
932 the switch you're connected to.
933
934
935 Recovering from Alarm
936 ^^^^^^^^^^^^^^^^^^^^^
937 TODO: explain.
938
939
940 Loopback
941 ^^^^^^^^
942 Not really an alarm. Indicates that a span is not available, as the port 
943 is in either a local or remote loopback mode.
944
945
946 Not Open
947 ^^^^^^^^
948 Something is not connected. Used by e.g. the drivers of the Astribank to
949 indicate a span that belongs to a device that has been disconnected 
950 but is still being used by userspace programs and thus can't e
951 destroyed.
952
953
954 License
955 -------
956 This package is distributed under the terms of the GNU General Public License
957 Version 2, except for some components which are distributed under the terms of
958 the GNU Lesser General Public License Version 2.1. Both licenses are included
959 in this directory, and each file is clearly marked as to which license applies.
960
961 If you wish to use the DAHDI drivers in an application for which the license
962 terms are not appropriate (e.g. a proprietary embedded system), licenses under
963 more flexible terms can be readily obtained through Digium, Inc. at reasonable
964 cost.
965
966 Known Issues
967 ------------
968
969 KB1 does not function when echocancel > 128
970 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
971 KB1 was not designed to function at greater than 128 taps, and if configured
972 this way, will result in the destruction of audio.  Ideally DAHDI would return
973 an error when a KB1 echocanceller is configured with greater than 128 taps.
974
975
976 Reporting Bugs
977 --------------
978 Please report bug and patches to the Asterisk bug tracker at
979 http://issues.asterisk.org in the "DAHDI" category.
980
981 Links
982 -----
983 - http://asterisk.org/[] - The Asterisk PBX
984 - http://voip-info.org/[]
985 - http://voip-info.org/wiki/view/DAHDI[]
986 - http://docs.tzafrir.org.il/dahdi-linux/README.html[Up-to-date HTML version
987   of this file]