[dahdi-commits] tzafrir: linux/trunk r4834 - /linux/trunk/README
SVN commits to the DAHDI project
dahdi-commits at lists.digium.com
Mon Aug 25 15:31:48 CDT 2008
Author: tzafrir
Date: Mon Aug 25 15:31:47 2008
New Revision: 4834
URL: http://svn.digium.com/view/dahdi?view=rev&rev=4834
Log:
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.
Modified:
linux/trunk/README
Modified: linux/trunk/README
URL: http://svn.digium.com/view/dahdi/linux/trunk/README?view=diff&rev=4834&r1=4833&r2=4834
==============================================================================
--- linux/trunk/README (original)
+++ linux/trunk/README Mon Aug 25 15:31:47 2008
@@ -3,9 +3,10 @@
Asterisk Development Team <asteriskteam at digium.com>
$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 @@
- 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 @@
Installation
-------------
+~~~~~~~~~~~~
Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
make
make install
-
-Building to a Subtree
-^^^^^^^^^^^^^^^^^^^^^
+Note that you'll need the unilities provided in the package dahdi-tools
+to configure DAHDI devices on your system.
+
+
+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,15 +92,12 @@
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,23 +298,89 @@
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
-----
More information about the dahdi-commits
mailing list