From ea748028eb713e18a431fcb450c95c580adbce44 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Tue, 5 Aug 2008 15:55:32 +0000 Subject: Copy tools README over to the linux package git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@4702 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- README | 559 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 559 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..1892dbf --- /dev/null +++ b/README @@ -0,0 +1,559 @@ +DAHDI Telephony Interface Driver +================================= +Asterisk Development Team +$Revision$, $Date$ + +DAHDI stands for Digium Asterisk Hardware Device Interface. This +package contains the userspace tools to configure the kernel modules +included in the package dahdi-linux. + +Supported Hardware +------------------ +Digital Cards +~~~~~~~~~~~~~ +- wct4xxp: + * Digium TE205P/TE207P/TE210P/TE212P: PCI dual-port T1/E1/J1 + * Digium TE405P/TE407P/TE410P/TE412P: PCI quad-port T1/E1/J1 + * Digium TE220: PCI-Express dual-port T1/E1/J1 + * Digium TE420: PCI-Express quad-port T1/E1/J1 +- wcte12xp: + * Digium TE120P: PCI single-port T1/E1/J1 + * Digium TE121: PCI-Express single-port T1/E1/J1 + * Digium TE122: PCI single-port T1/E1/J1 +- wcte11xp: + * Digium TE110P: PCI single-port T1/E1/J1 +- wct1xxp: + * Digium T100P: PCI single-port T1 + * Digium E100P: PCI single-port E1 +- tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project + + +Analog Cards +~~~~~~~~~~~~ +- wctdm24xxp: + * Digium TDM2400P/AEX2400: up to 24 analog ports + * Digium TDM800P/AEX800: up to 8 analog ports + * Digium TDM410P: up to 4 analog ports +- wctdm: + * Digium TDM400P: up to 4 analog ports +- xpp: Xorcom Astribank: a USB connected unit of up to 32 ports + (including the digital BRI and E1/T1 modules) +- wcfxo: X100P, similar and clones. A simple single-port FXO card + + +Other Drivers +~~~~~~~~~~~~~ +- pciradio: Zapata Telephony PCI Quad Radio Interface +- wctc4xxp: Digium hardware transcoder cards (also need dahdi_transcode) +- dahdi_dynamic_eth: TDM over Ethernet (TDMoE) driver. Requires dahdi_dynamic +- dahdi_dynamic_loc: Mirror a local span. Requires dahdi_dynamic +- dahdi_dummy: A dummy driver that only provides a DAHDI timing source. + + +Build Requirements +------------------ +This package needs the headers from dahdi-linux. Thus you should install +dahdi-linux before building dahdi-tools. + +The script install_prereq should help you install the +required packages. To see what it suggests, run: + + ./install_prereq test + +You can either copy/paste that code to a terminal to run it, or just +run: + + ./install_prereq install + + +A Build System +~~~~~~~~~~~~~~ +gcc and friends. Generally you will need to install the package gcc. +There may be cases where you will need a specific version of gcc to build +kernel modules. + + +Extra Libraries +~~~~~~~~~~~~~~~ +Some libraries are needed for extra utilities that are provided with +DAHDI. + +- libusb is needed for building fpga_load, needed for firmware loading of + the Xorcom Astribank. +- libnewt is needed to build the optional but useful utility dahdi_tool. + + +Distribution-Specific Instructions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TO BE WRITTEN + + +Installation +------------ +Note: If using `sudo` to build/install, you may need to add /sbin to your PATH. +---------------------------------- +./configure +# optional step: select custom configuration: +#make menuconfig +make +make install +# To install init scripts and config files: +#make config +---------------------------------- + + +Build Tweaks +~~~~~~~~~~~~ +Partial Build/Install +^^^^^^^^^^^^^^^^^^^^^ +There are some make targets that are provided to build or install just +parts of DAHDI: + +. Build targets: + - make: Build DAHDI userspace programs. partial + targets of it: + * make 'utilname': builds 'utilname' alone (e.g: `make dahdi_diag`) + * make utils: Build libtonezone. + * make libs: Build libtonezone. +. Install targets: + - make install: Installs user space tools into /usr/sbin/ (TODO - list + partial targets) + - make config: should be run once to configure + +Building to a Subtree +^^^^^^^^^^^^^^^^^^^^^ +The following may be useful when testing the package or when preparing a +package for a binary distribution (such as an rpm package) installing +onto a subtree rather than on th real system. + + make install DESTDIR=targetdir + +This can be useful for any partial install target of the above (e.g: +install-modules or install-programs). + +the targetdir must be an absolute path, at least if you install the +modules. To install to a relative path you can use something like: + + make install-modules DESTDIR=$PWD/target + +The 'install' target might fail if run as a user to a DESTDIR when +attempting to generate device files. In that case, try: + + make install DESTDIR=$PWD/target DYNFS= + + +./configure Options +^^^^^^^^^^^^^^^^^^^ +The configure script various several tests and based on them generates +some files ( build_tools/menuselect-deps and makeopts). You can pass it +--with options and variable settings, for instance: + + ./configure --without-ncurses CC="gcc-4.10" + +If you just want to recreate the same files without a full detection +run, use: + + ./config.status + +To re-run ./configure with the same parameters it was run with last +time, use: + + ./ocnfig.status --recheck + +TODO: building with a local copy of DAHDI? + + +Configuration +------------- +Configuration for DAHDI resides under /etc/dahdi . + +/etc/dahdi/system.conf +~~~~~~~~~~~~~~~~~~~~~~ +The main method to configure DAHDI devices is using the utility +*dahdi_cfg*. dahdi_cfg reads data from the configuration file +/etc/dahdi/system.conf , figures out what configuration to send to +channels, and send it to the kernel. + +A sample annotated system.conf is included in this directory and +installed by default. Edit it to suit your configuration. Alternatively +use the script dahdi_genconf to generate one that should work with your +system. + + +/etc/dahdi/init.conf +~~~~~~~~~~~~~~~~~~~~ +The configuration file of the dahdi init.d script is +/etc/dahdi/init.conf . That file is used to override defaults that are +set at the beginning of the init.d script. + + +Module Parameters +~~~~~~~~~~~~~~~~~ +The kernel modules can be configured through module parameters. Module +parameters can optionally be set at load time. They are normally set (if +needed) by a line in a file under /etc/modprobe.d/ or in the file +/etc/modprobe.conf. + +Example line: + + options dahdi debug=1 + +The module parameters can normally be modified at runtime through sysfs: + + pungenday:~# cat /sys/module/dahdi/parameters/debug + 0 + pungenday:~# echo 1 >/sys/module/dahdi/parameters/debug + pungenday:~# cat /sys/module/dahdi/parameters/debug + 1 + +Viewing and setting parameters that way is possible as of kernel 2.6 . +In kernels older than 2.6.10, the sysfs "files" for the parameters +reside directly under /sys/module/'module_name' . + +Useful module parameters: + +debug (most modules):: + Sets debug mode / debug level. With most modules 'debug' can be either + disabled (0, the default value) or enabled (any other value). + + + + + wctdm and wcte1xp print several extra debugging messages if the value + of debug is more than 1. + + + + + Some modules have "debugging flags" bits - the value of debug is a + bitmask and several messages are printed if some bits are set: + - dahdi_dummy: + * 1: DEBUG_GENERAL - general error messages. + * 2: DEBUG_TICKS - Show that the module is alive :-) + - wctdm24xxp: + * 1: DEBUG_CARD + * 2: DEBUG_ECHOCAN + - wct4xxp: + * 1: DEBUG_MAIN + * 2: DEBUG_DTMF + * 4: DEBUG_REGS + * 8: DEBUG_TSI + * 16: DEBUG_ECHOCAN + * 32: DEBUG_RBS + * 64: DEBUG_FRAMER + - xpp: See also README.Astribank: + * 1: GENERAL - General debug comments. + * 2: PCM - PCM-related messages. Tend to flood logs. + * 4: LEDS - Anything related to the LEDs status control. The driver + produces a lot of messages when the option is enabled. + * 8: SYNC - Synchronization related messages. + * 16: SIGNAL - DAHDI signalling related messages. + * 32: PROC - Messages related to the procfs interface. + * 64: REGS - Reading and writing to chip registers. Tends to flood + logs. + * 128: DEVICES - Device instantiation, destruction and such. + * 256 - COMMANDS - Protocol commands. Tends to flood logs. + +deftaps (dahdi):: + The default size for the echo canceller. The number is in "taps", that + is "samples", 1/8 ms. The default is 64 - for a tail size of 8 ms. + + + + + Asterisk's chan_dahdi tends to pass its own value anyway, with a + different default size. So normally setting this doesn't change + anything. + +To get a list of parameters supported by a module, use + + modinfo module_name + +Or, for a module you have just built: + + modinfo ./module_name.ko + +For the xpp modules this will also include the description and default +value of the module. You can find a list of useful xpp module parameters +in README.Astribank . + + +Reference Configuration +----------------------- +Sample system.conf +~~~~~~~~~~~~~~~~~~ +include::system.conf.asciidoc[] + + +Sample init.conf +~~~~~~~~~~~~~~~~ +include::init.conf.asciidoc[] + + +Tonezones +~~~~~~~~~ +The file zonedata.c contains the information about the tone zones used +in libtonezone (and hence also in ztcfg). Here is a list of those zones: + +include::tonezones.txt[] + + +DAHDI PERL modules +------------------- +The directory xpp has, in addition to helper utilities for the +Xorcom Astribank, a collection of perl modules to provide information +related to DAHDI. The perl modules themselves are under xpp/perl_modules/ . +In xpp/ there are several utilities that use those modules: +- xpp-specific: dahdi_registration, xpp_sync, xpp_blink . +- General: lsdahdi, dahdi_genconf, dahdi_hardware, dahdi_drivers + +The DAHDI perl modules will currently only be automatically installed if you +happen to install the xpp directory. Those utilities require the perl modules +to be installed, however they will also look for them in the directory +perl_modules, and thus can be run directly from the DAHDI source tree. For +example: + + ./xpp/dahdi_hardware -v + +To get usage information on a program, you can also use perldoc +(sometimes provided in a package separate from perl itself). For +instance: + + perldoc ./xpp/lsdahdi + +Some of them are specific for the Xorcom Astribank and described in its +docuemntation. the others are: + +lsdahdi:: + A somewhat glorified `cat /proc/dahdi/*`. +dahdi_genconf:: + Generates configuration based on the existing DAHDI channels and on + /etc/dahdi/genconf_parameters (replaces genzaptelconf as well). +dahdi_drivers:: + A two-liner script (not installed by default) that simply returns the + modules that should be modprobed on this system. +dahdi_hardware:: + Uses the information from sysfs and its own knowledge to show + what PCI/USB DAHDI hardware is connected and if it is currently used + by a driver. Shows also some more information for Astribanks from + /proc/xpp . + +Internals +--------- +DAHDI Device Files +~~~~~~~~~~~~~~~~~~~ +Userspace programs will usually interact with DAHDI through device +files under the /dev/dahdi directory (pedantically: characted device files +with major number 196) . Those device files can be generated statically +or dynamically through the udev system. + +* /dev/dahdi/ctl (196:0) - a general device file for various information and + control operations on the DAHDI channels. +* /dev/dahdi/NNN (196:NNN) - for NNN in the range 1-249. A device file for + DAHDI channel NNN. It can be used to read data from the channel + and write data to the channel. +* /dev/dahdi/transcode (196:250) - Used to connect to a DAHDI transcoding + device. +* /dev/dahdi/timer (196:253) - Allows setting timers. Used anywhere? +* /dev/dahdi/channel (196:254) - Can be used to open an arbitrary DAHDI + channel. This is an alternative to /dev/dahdi/NNN that is not limited to + 249 channels. +* /dev/dahdi/pseudo (196:255) - A timing-only device. Every time you open + it, a new DAHDI channel is created. That DAHDI channel is "pseudo" - + DAHDI recieves no data in it, and only sends garbage data with the + same timing as the DAHDI timing master device. + + +DAHDI Timing +~~~~~~~~~~~~~ +A PBX system should generally have a single clock. If you are connected to a +telephony provider via a digital interface (e.g: E1, T1) you should also +typically use the provider's clock (as you get through the interface). Hence +one important job of Asterisk is to provide timing to the PBX. + +DAHDI "ticks" once per millisecond (1000 times per second). On each tick every +active DAHDI channel reads and 8 bytes of data. Asterisk also uses this for +timing, through a DAHDI pseudo channel it opens. + +However, not all PBX systems are connected to a telephony provider via a T1 or +similar connection. With an analog connection you are not synced to the other +party. And some systems don't have DAHDI hardware at all. Even a digital card +may be used for other uses or is simply not connected to a provider. DAHDI +cards are also capable of providing timing from a clock on card. Cheap x100P +clone cards are sometimes used for that pupose. + +If all the above fail, you can use the module dahdi_dummy to provide timing +alone without needing any DAHDI hardware. It will work with most systems and +kernels. + +You can check the DAHDI timing source with dahdi_test, which is a small +utility that is included with DAHDI. It runs in cycles. In each such cycle it +tries to read 8192 bytes, and sees how long it takes. If DAHDI is not loaded +or you don't have the device files, it will fail immediately. If you lack a +timing device it will hang forever in the first cycle. Otherwise it will just +give you in each cycle the percent of how close it was. Also try running it +with the option -v for a verbose output. + +To check the clock source that is built into dahdi_dummy, you can either look +at title of its span in /proc/dahdi file for a "source:" in the description. +Or even run: + + strings dahdi.ko | grep source: + + +Spans and Channels +~~~~~~~~~~~~~~~~~~ +DAHDI provides telephony *channels* to the userspace applications. +Those channels are channels are incorperated into logical units called +*spans*. + +With digital telephony adapters (e.g: E1 or T1), a span normally +represents a single port. With analog telephony a span typically +represents a PCI adapter or a similar logical unit. + +Both channels and spans are identified by enumerating numbers (beginning +with 1). The number of the channel is the lowest unused one when it is +generated, and ditto for spans. + + +PROCFS Interface: /proc/dahdi +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A simple way to get the current list of spans and channels each span contains +is the files under /proc/dahdi . /proc/dahdi is generated by DAHDI as it +loads. As each span registers to DAHDI, a file under /proc/dahdi is created +for it. The name of that file is the number of that span. + +Each file has a 1-line title for the span followed by an empty line and +then a line for each channel of the span. + +The title line shows the number of the span, its name and title, and +(potentially) the alarms in which it is. + +The title shows the span number and name, followed by any allarms the +span may have: For example, here is the first span in my system (with no +alarms): + + Span 1: XBUS-00/XPD-00 "Xorcom XPD #0/0: FXS" + +The channel line for each channel shows its channel number, name and the +actual signalling assigned to it through dahdi_cfg. Before being configured by +dahdi_cfg: This is DAHDI channel 2, whose name is 'XPP_FXS/0/0/1'. + + 2 XPP_FXS/0/0/1 + +After being configured by dahdi_cfg: the signalling 'FXOLS' was added. FXS +channels have FXO signalling and vice versa: + + 2 XPP_FXS/0/0/1 FXOLS + +If the channel is in use (typically opened by Asterisk) then you will +see an extra '(In use)': + + 2 XPP_FXS/0/0/1 FXOLS (In use) + + +ABI Compatibility +~~~~~~~~~~~~~~~~~ +Like any other kernel code, DAHDI strives to maintain a stable interface to +userspace programs. The API of DAHDI to userspace programs, dahdi/user.h, has +remained backword-compatible for a long time and is expected to remain so in +the future. With the ABI (the bits themselves) things are slightly trickier. + +DAHDI's interface to userspace is mostly ioctl(3) calls. Ioctl calls +are identified by a number that stems from various things, one of which +is the size of the data structure passed between the kernel and +userspace. + +Many of the DAHDI ioctl-s use some sepcific structs to pass information +between kernel and userspace. In some cases the need arose to pass a few +more data members in each call. Simply adding a new member to the struct +would have meant a new number for the ioctl, as its number depends on +the size of the data passed. + +Thus we would add a new ioctl with the same base number and with the +original struct. + +So suppose we had the following ioctl: +---------------------------------- +struct zt_example { + int sample; +} + +#define ZT_EXAMPLE _IOWR (ZT_CODE, 62, struct zt_example) +---------------------------------- + +And we want to add the field 'int onemore', we won't just add it to the +struct. We will do something that is more complex: +------------------------------------ +/* The original, unchanged: */ +struct zt_example_v1 { + int sample; +} + +/* The new struct: */ +struct zt_example { + int sample; + int onemore; +} + +#define ZT_EXAMPLE_V1 _IOWR (ZT_CODE, 62, struct zt_example_v1) +#define ZT_EXAMPLE _IOWR (ZT_CODE, 62, struct zt_example) +------------------------------------ +We actually have here two different ioctls: the old ZT_EXAMPLE would be +0xC0044A3E . ZT_EXAMPLE_V1 would have the same value. But the new value +of ZT_EXAMPLE would be 0xC0084A3E . + +Programs built with the original dahdi/user.h (before the change) use the +original ioctl, whether or not the kernel code is actually of the newer +version. Thus in most cases there are no compatibility issues. + +When can we have compatibility issues? If we have code built with the new +dahdi/user.h, but the loaded kernel code (modules) are of the older version. +Thus the userspace program will try to use the newer ZT_EXAMPLE (0xC0084A3E). +But the kernel code has no handler for that ioctl. The result: the error 25, +ENOTTY, which means "Inappropriate ioctl for device". + +As a by-product of that method, for each interface change a new #define is +added. That definition is for the old version and thus it might appear +slightly confusing in the code, but it is useful for writing code that works +with all versions of DAHDI. + + +PPP Support +----------- +DAHDI digital cards can provide data channels through ppp as +point-to-point connections. This requires a plugin to the ppp daemon +that is included in the ppp/ subdirectory. To install it: + +1. Make sure you have the PPP source / headers installed. On Debian: + + apt-get install ppp-dev + +2. Run 'make' on the ppp subdirectory: + + make -C ppp + make -C ppp install + +3. Make sure your kernel has support for both PPP (which is common is + distribution kernels and for HDLC (much less common) - CONFIG_PPP and + CONFIG_HDLC . + + +License +------- +libpri is distributed under the terms of the GNU General Public License, +which permit its use and linking with other GPL'd software only. +The GNU GPL is included in the file LICENSE in this directory. + +If you wish to use the DAHDI drivers in an application for which the GPL is +not appropriate (e.g. a proprietary embedded system), licenses under more +flexible terms can be readily obtained through Digium, Inc.at reasonable cost. + + +Reporting Bugs +-------------- +Please report bug and patches to the Asterisk.org bug tracker at +http://bugs.digium.com in the "DAHDI" category. + + +Links +----- +- http://asterisk.org/[] - The Asterisk PBX +- http://voip-info.org/[] +- http://voip-info.org/wiki/view/Asterisk+Zaptel+Installation[] +- http://docs.tzafrir.org.il/dahdi/README.html[Up-to-date HTML version + of this file] -- cgit v1.2.3