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