From 39cfc0c033b2342e76a3044fb3fa4017c4b0d3fc Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Mon, 25 Aug 2008 20:31:47 +0000 Subject: Reverting unwanted changes in the README (from r4830) Also fixed ZT references in the ABI compatibility section. The numerical ioctl values need to be recalculated, though. git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@4834 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- README | 176 +++++++++++++++++++++++++++++++---------------------------------- 1 file changed, 85 insertions(+), 91 deletions(-) (limited to 'README') diff --git a/README b/README index 8529e80..12961da 100644 --- a/README +++ b/README @@ -3,9 +3,10 @@ DAHDI Telephony Interface Driver Asterisk Development Team $Revision$, $Date$ -DAHDI stands for Digium Asterisk Hardware Device Interface. This -package contains the kernel modules. For the required userspace tools -see the package dahdi-tools. +DAHDI stands for Digium Asterisk Hardware Device Interface. + +This package contains the kernel modules for DAHDI. For the required +userspace tools see the package dahdi-tools. Supported Hardware ------------------ @@ -49,79 +50,6 @@ 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. @@ -130,15 +58,18 @@ kernel modules. Installation ------------- +~~~~~~~~~~~~ Note: If using `sudo` to build/install, you may need to add /sbin to your PATH. make make install +Note that you'll need the unilities provided in the package dahdi-tools +to configure DAHDI devices on your system. -Building to a Subtree -^^^^^^^^^^^^^^^^^^^^^ + +Installing 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. @@ -161,16 +92,13 @@ attempting to generate device files. In that case, try: Extra Modules ^^^^^^^^^^^^^ -To build extra modules / modules directory not included in the Zaptel +To build extra modules / modules directory not included in the DAHDI 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 ~~~~~~~~~~~~~~~~~ @@ -370,24 +298,90 @@ 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 DAHDI_EXAMPLE _IOWR (DAHDI_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 DAHDI_EXAMPLE_V1 _IOWR (DAHDI_CODE, 62, struct zt_example_v1) +#define DAHDI_EXAMPLE _IOWR (DAHDI_CODE, 62, struct zt_example) +------------------------------------ +We actually have here two different ioctls: the old DAHDI_EXAMPLE would be +0xC0044A3E . DAHDI_EXAMPLE_V1 would have the same value. But the new value +of DAHDI_EXAMPLE would be 0xC0084A3E . +(TODO: fix ioctl values) + +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 DAHDI_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, -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. +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. 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 -- cgit v1.2.3