From 4a584b12b8064cf27c5b6dcf7442a04a8fd41480 Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Mon, 25 Aug 2008 18:05:55 +0000 Subject: Make the README file more relevant to modules. git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@4830 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- README | 210 ++++++++++++++++++++++++++++++++++------------------------------- 1 file changed, 110 insertions(+), 100 deletions(-) (limited to 'README') diff --git a/README b/README index 1aa9ffb..8529e80 100644 --- a/README +++ b/README @@ -3,7 +3,9 @@ DAHDI Telephony Interface Driver Asterisk Development Team $Revision$, $Date$ -DAHDI stands for Digium Asterisk Hardware Device Interface. +DAHDI stands for Digium Asterisk Hardware Device Interface. This +package contains the kernel modules. For the required userspace tools +see the package dahdi-tools. Supported Hardware ------------------ @@ -25,6 +27,7 @@ Digital Cards * Digium E100P: PCI single-port E1 - tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project + Analog Cards ~~~~~~~~~~~~ - wctdm24xxp: @@ -37,6 +40,7 @@ Analog Cards (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 @@ -45,21 +49,96 @@ Other Drivers - 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 + + +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: + +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 timers (CONFIG_HIGH_RES_TIMERS), and (if available), + the system HPET. This shows as "source: HRTimer". This is + recommended. + * ztdummy on i386/x86_64 with 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". + make KVERS=2.6.18.Custom KSRC=/home/tzafrir/kernels/2.6.18 +- For ppp support: 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 . See the documentation of dahdi-tools for + setup instruction. + + 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. + Installation -~~~~~~~~~~~~ +------------ Note: If using `sudo` to build/install, you may need to add /sbin to your PATH. ----------------------------------- -# make -# make install + + make + make install + 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. @@ -79,27 +158,19 @@ attempting to generate device files. In that case, try: make install DESTDIR=$PWD/target DYNFS= -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. +Extra Modules +^^^^^^^^^^^^^ +To build extra modules / modules directory not included in the Zaptel +distribution, use the optional variables MODULES_EXTRA and +SUBDIRS_EXTRA: -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. + 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. -/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 ~~~~~~~~~~~~~~~~~ @@ -185,6 +256,7 @@ 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 . + Internals --------- DAHDI Device Files @@ -210,6 +282,7 @@ or dynamically through the udev system. 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 @@ -246,6 +319,7 @@ Or even run: strings dahdi.ko | grep source: + Spans and Channels ~~~~~~~~~~~~~~~~~~ DAHDI provides telephony *channels* to the userspace applications. @@ -260,6 +334,7 @@ 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 @@ -295,93 +370,28 @@ 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. License ------- -This package is distributed under the terms of the GNU General Public License -Version 2, except for some components which are distributed under the terms of -the GNU Lesser General Public License Version 2.1. Both licenses are included -in this directory, and each file is clearly marked as to which license applies. +This package is distributed under the terms of the GNU General Public License Version 2, +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. -If you wish to use the DAHDI drivers in an application for which the license -terms are 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 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 +- http://voip-info.org/wiki/view/DAHDI[] +- http://docs.tzafrir.org.il/dahdi-linux/README.html[Up-to-date HTML version of this file] -- cgit v1.2.3