[dahdi-commits] tzafrir: linux/trunk r4830 - /linux/trunk/README

SVN commits to the DAHDI project dahdi-commits at lists.digium.com
Mon Aug 25 13:05:55 CDT 2008 

Author: tzafrir
Date: Mon Aug 25 13:05:55 2008
New Revision: 4830

URL: http://svn.digium.com/view/dahdi?view=rev&rev=4830
Log:
Make the README file more relevant to modules.

Modified:
    linux/trunk/README

Modified: linux/trunk/README
URL: http://svn.digium.com/view/dahdi/linux/trunk/README?view=diff&rev=4830&r1=4829&r2=4830
==============================================================================
--- linux/trunk/README (original)
+++ linux/trunk/README Mon Aug 25 13:05:55 2008
@@ -3,7 +3,9 @@
 Asterisk Development Team <asteriskteam at digium.com>
 $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 @@
   * 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 @@
   (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 @@
 - 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 @@
 
   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.
-
-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.
+
+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.
+
 
 Module Parameters
 ~~~~~~~~~~~~~~~~~
@@ -185,6 +256,7 @@
 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 @@
   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 @@
 
   strings dahdi.ko | grep source:
 
+
 Spans and Channels
 ~~~~~~~~~~~~~~~~~~
 DAHDI provides telephony *channels* to the userspace applications. 
@@ -259,6 +333,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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -295,93 +370,28 @@
 
            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.
-
-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.
+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.
+
 
 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]

More information about the dahdi-commits mailing list