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

1 files changed, 85 insertions, 91 deletions

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 <asteriskteam@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 @@ 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