From a6a5c89fa7b5406bbc0ad19f026fa29eae7a286e Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Thu, 10 Jul 2008 20:55:53 +0000 Subject: * Include init.conf in the README as well. * Initial support for referencing configuration directives from the asciidoc-ed README. * Ignore files generated while making documentation. git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@4602 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- README | 218 ++++++++++++----------------------------------------------------- 1 file changed, 40 insertions(+), 178 deletions(-) (limited to 'README') diff --git a/README b/README index c5063ac..51e7df7 100644 --- a/README +++ b/README @@ -3,7 +3,9 @@ Zapata Telephony Interface Driver Asterisk Development Team $Revision$, $Date$ -Zaptel is a short for ZAPata TELephony. +DAHDI stands for Digium Advanced Hardware Digital Interface. This +package contains the userspace tools to configure the kernel modules +included in the package dahdi-linux. Supported Hardware ------------------ @@ -24,7 +26,6 @@ Digital Cards * Digium T100P: PCI single-port T1 * Digium E100P: PCI single-port E1 - tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project -- torisa: The old dual-span ISA T1 card from Zapata Telephony Analog Cards @@ -38,22 +39,21 @@ Analog Cards - xpp: Xorcom Astribank: a USB connected unit of up to 32 ports (includeing the digital BRI and E1/T1 modules) - wcfxo: X100P, similar and clones. A simple single-port FXO card -- wcusb: Digium S100U: A simple single-port USB FXS unit Other Drivers ~~~~~~~~~~~~~ - pciradio: Zapata Telephony PCI Quad Radio Interface - wctc4xxp: Digium hardware transcoder cards (also need zttranscode) -- ztd-eth: TDM over Ethernet (TDMoE) driver. Requires ztdynamic -- ztd-loc: Mirror a local span. Requires ztdynamic -- ztdummy: A dummy driver that only provides a zaptel timing source. +- dahdi_dynamic_eth: TDM over Ethernet (TDMoE) driver. Requires ztdynamic +- dahdi_dynamic_loc: Mirror a local span. Requires ztdynamic +- dahdi_dummy: A dummy driver that only provides a zaptel timing source. Build Requirements ------------------ -You will need a matching kernel source tree and a working Linux build -system. Some of the programs require some additional libraries. +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: @@ -66,60 +66,6 @@ run: ./install_prereq install -Kernel Source / "Headers" -~~~~~~~~~~~~~~~~~~~~~~~~~ -- Building zaptel requires a kernel build tree. -- This should basically be at least a partial kernel source tree and - most importantly, the exact kernel .config file used for the build as - well as several files generated at kernel build time. -- KERNEL_VERSION is the output of the command `uname -r` -- If you build your own kernel, you need to point to the exact kernel - build tree. Luckily for you, this will typically be pointed by the - symbolic link /lib/modules/KERNEL_VERSION/build which is the location - zaptel checks by default. -- If you use a kernel from your distribution you will typically have a - package with all the files required to build a kernel modules for your - kernel image. - * On Debian Etch and above and any Ubuntu this is - +++ linux-headers-`uname -r` +++ - * On Fedora, RHEL and compatibles (e.g. CentOS) this is the - kernel-devel package. Or if you run kernel-smp or kernel-xen, you - need kernel-smp-devel or kernel-xen-devel, respectively. - * On SUSE you seem to need the package kernel-source . - * In some distributions (e.g.: in RHEL/CentOS, Fedora, Ubuntu) the - installation of the kernel-devel / kernel-headers package will - be of a version that is newer than the one you currently run. In - such a case you may need to upgrade the kernel package itself as - well and reboot. -- To point explicitly to a different build tree: set KSRC to the kernel - source tree and KVERS to the exact kernel version: - - make KVERS=2.6.18.Custom KSRC=/home/tzafrir/kernels/2.6.18 - - -Kernel Configuration -~~~~~~~~~~~~~~~~~~~~ -If you build a custom kernel, note the following configuration items: - -- CONFIG_CRC_CCITT must be enabled ('y' or 'm'). On 2.6 kernels this can - be selected These can be selected from the "Library Routines" submenu - during kernel configuration via "make menuconfig". -- If you don't have any zaptel hardware, you need ztdummy. ztdummy takes - its timing from the kernel. It can use either of the following: - * ztdummy on i386/x86_64 with kernels >= 2.6.22 can (and should) use - high resolution times (CONFIG_HIGH_RES_TIMERS), and (if available, - the system HPET. This shows as "source: HRTimer". This is - recommended. - * ztdummy on i386/x86_64 and later kernels (>= 2.6.15) can use the - system's RTC (Real Time Clock). This shows as "source: RTC". - * Failing that, on Linux 2.6 kernels with HZ=1000 (was the default - before 2.6.13). This shows as "source: Linux26". - * Alternatives to that for ztdummy are a UHCI USB controller (USB - controllers made by Intel or VIA) or a kernel that has HZ=1000 - (default on kernels 2.6.0-2.6.12, optional on newer kernels. Not - possible on 2.4). This shows as: "source: UHCI". - - A Build System ~~~~~~~~~~~~~~ gcc and friends. Generally you will need to install the package gcc. @@ -139,36 +85,7 @@ Zaptel Distribution-Specific Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -==== Debian 4.0 (Etch) - apt-get install linux-headers-`uname -r` build-essential libnewt-dev libusb-dev - -==== Debian 3.1 (Sarge) - apt-get install kernel-headers-`uname -r` build-essential libnewt-dev libusb-dev - -==== RHEL4 / CentOS 4 -You need the following non-kernel-related packages: - - yum install gcc newt-devel libusb-devel - -If the following command produces an error, you need to install -the kernel devel package: - - ls /lib/modules/`uname -r`/build/.config - -The right one depends on your kernel version. If the following command -produces output you have an SMP kernel: - - uname -r | grep smp - -and thus need to run: - - yum install kernel-smp kernel-smp-devel - -If that command produced no output, you have a non-SMP kernel: - - yum install kernel kernel-devel - -At this point you should probably reboot to get the new kernel in effect. +TO BE WRITTEN Installation @@ -187,41 +104,18 @@ make install Build Tweaks ~~~~~~~~~~~~ -Selecting Modules and Utilities -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can select the modules and utilities you wish to build and firmwares -you wish to download by running `make menuselect` . The selection of modules -that you build (or rather: not build) is saved in the file -`menuselect.makeopts`. - - -Extra Modules -^^^^^^^^^^^^^ -To build extra modules / modules directory not included in the Zaptel -distribution, use the optional variables MODULES_EXTRA and -SUBDIRS_EXTRA: - - make MODULES_EXTRA="mod1 mod2" - make MODULES_EXTRA="mod1 mod2" SUBDIRS_EXTRA="subdir1/ subdir1/" - -Note that those names are not guaranteed to continue to work on newer -versions. Hopefully there will be no need for such extra configuration. - Partial Build/Install ^^^^^^^^^^^^^^^^^^^^^ There are some make targets that are provided to build or install just parts of Zaptel: . Build targets: - - make modules: build just the kernel modules. - make programs: Build just the Zaptel userspace programs. partial targets of it: * make 'utilname': builds 'utilname' alone (e.g: `make ztdiag`) * make utils: Build libtonezone. * make libs: Build libtonezone. . Install targets: - - make install-modules: install just kernel modules. - - make firmware: download and install firmwares for Digium cards - make install-programs: Userspace: Partial targets of it are: * make install-utils: install Zaptel userspace programs and and basic support files. @@ -251,41 +145,6 @@ attempting to generate device files. In that case, try: make install DESTDIR=$PWD/target DYNFS= -Test Install: live_zap -^^^^^^^^^^^^^^^^^^^^^^ -If you need to test a version of Zaptel without touching the version -installed on your system, you can use the script live_zap . Note, -however, that it may take some extra configuration to be used right. - -Basic usage: - - ./configure - make - ./live_zap install # instead of 'make install' - ./live_zap config # instead of 'make config' - ./live_zap unload # instead of '/etc/init.d/zaptel stop' - ./live_zap load # instead of '/etc/init.d/zaptel start' - -Everything is installed under the subdirectory live/ . You will probably -need to adjust MODULES . Generally you should not edit the script -itself, but , rather, edit live/live.conf . Please let me know if you -needed to change anything in the script beyond changing live.conf so I -can include useful fixes. - -Testing on a different maching: - - ./configure - make - ./live_zap install # instead of 'make install' - ./live_zap config # instead of 'make config' - ./live_zap rsync root@remotehost - ssh root@remotehost - # in the remote host: - cd /tmp - ./live_zap unload - ./live_zap load - - ./configure Options ^^^^^^^^^^^^^^^^^^^ The configure script various several tests and based on them generates @@ -304,35 +163,31 @@ time, use: ./ocnfig.status --recheck +TODO: building with a local copy of DAHDI? + Configuration ------------- -zaptel.conf -~~~~~~~~~~~ -The main method to configure Zaptel devices is using the utility -*ztcfg*. ztcfg reads data from the configuration file /etc/zaptel.conf , -figures out what configuration to send to channels, and send it. - -A sample annotated zaptel.conf is included in this directory and -installed by default to /etc/zaptel.conf . Edit it to suit your -configuration. Alternatively use the script genzaptelconf to generate -one that should work with your system. +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. -sysconfig/default -~~~~~~~~~~~~~~~~~ -The configuration file of the zaptel init.d script is either -/etc/default/zaptel (Debian systems) or /etc/sysconfig/zaptel (most -others). That file is used to override defaults that are set at the -beginning of the init.d script. - -For instance, to define for the init.d script to load the modules wctdm -and xpp_usb (in that order) add the following line to that file: - MODULES="wctdm xpp_usb" +/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. -Currently that file must set "TELEPHONY=yes" for the zaptel init.d to -work. Module Parameters ~~~~~~~~~~~~~~~~~ @@ -370,7 +225,7 @@ debug (most modules):: + Some modules have "debugging flags" bits - the value of debug is a bitmask and several messages are printed if some bits are set: - - ztdummy: + - dahdi_dummy: * 1: DEBUG_GENERAL - general error messages. * 2: DEBUG_TICKS - Show that the module is alive :-) - wctdm24xxp: @@ -384,8 +239,7 @@ debug (most modules):: * 16: DEBUG_ECHOCAN * 32: DEBUG_RBS * 64: DEBUG_FRAMER - - xpp: Previously (before 1.2.26 / 1.4.11) it was called "print_dbg". - See also README.Astribank: + - 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 @@ -398,12 +252,12 @@ debug (most modules):: * 128: DEVICES - Device instantiation, destruction and such. * 256 - COMMANDS - Protocol commands. Tends to flood logs. -deftaps (zaptel):: +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_zap tends to pass its own value anyway, with a + Asterisk's chan_dahdi tends to pass its own value anyway, with a different default size. So normally setting this doesn't change anything. @@ -422,7 +276,15 @@ in README.Astribank . Reference Configuration ----------------------- -include::zaptel.conf.asciidoc[] +Sample system.conf +~~~~~~~~~~~~~~~~~~ +include::system.conf.asciidoc[] + + +Sample init.conf +~~~~~~~~~~~~~~~~~~ +include::init.conf.asciidoc[] + Tonezones ~~~~~~~~~ -- cgit v1.2.3