Copying over README from the original 1.4. Now let's start trimming.

git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@4587 a0bf4364-ded3-4de4-8d8a-66a801d63aff

1 files changed, 734 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..c5063ac
--- /dev/null
+++ b/README
@@ -0,0 +1,734 @@
+Zapata Telephony Interface Driver
+=================================
+Asterisk Development Team <asteriskteam@digium.com>
+$Revision$, $Date$
+
+Zaptel is a short for ZAPata TELephony.
+
+Supported Hardware
+------------------
+Digital Cards
+~~~~~~~~~~~~~
+- wct4xxp:
+  * Digium TE205P/TE207P/TE210P/TE212P: PCI dual-port T1/E1/J1
+  * Digium TE405P/TE407P/TE410P/TE412P: PCI quad-port T1/E1/J1
+  * Digium TE220: PCI-Express dual-port T1/E1/J1
+  * Digium TE420: PCI-Express quad-port T1/E1/J1
+- wcte12xp:
+  * Digium TE120P: PCI single-port T1/E1/J1
+  * Digium TE121: PCI-Express single-port T1/E1/J1
+  * Digium TE122: PCI single-port T1/E1/J1
+- wcte11xp:
+  * Digium TE110P: PCI single-port T1/E1/J1
+- wct1xxp: 
+  * Digium T100P: PCI single-port T1
+  * Digium E100P: PCI single-port E1
+- tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project
+- torisa: The old dual-span ISA T1 card from Zapata Telephony
+
+
+Analog Cards
+~~~~~~~~~~~~
+- wctdm24xxp: 
+  * Digium TDM2400P/AEX2400: up to 24 analog ports
+  * Digium TDM800P/AEX800: up to 8 analog ports
+  * Digium TDM410: up to 4 analog ports
+- wctdm:
+  * Digium TDM400P: up to 4 analog ports
+- xpp: Xorcom Astribank: a USB connected unit of up to 32 ports
+  (includeing the digital BRI and E1/T1 modules)
+- wcfxo: X100P, similar and clones. A simple single-port FXO card
+- wcusb: Digium S100U: A simple single-port USB FXS unit
+
+
+Other Drivers
+~~~~~~~~~~~~~
+- pciradio: Zapata Telephony PCI Quad Radio Interface
+- wctc4xxp: Digium hardware transcoder cards (also need zttranscode)
+- ztd-eth: TDM over Ethernet (TDMoE) driver. Requires ztdynamic
+- ztd-loc: Mirror a local span. Requires ztdynamic
+- ztdummy: A dummy driver that only provides a zaptel timing source.
+
+
+Build Requirements
+------------------
+You will need a matching kernel source tree and a working Linux build 
+system. Some of the programs require some additional libraries.
+
+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:
+
+  make KVERS=2.6.18.Custom KSRC=/home/tzafrir/kernels/2.6.18
+
+
+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 times (CONFIG_HIGH_RES_TIMERS), and (if available, 
+    the system HPET. This shows as "source: HRTimer". This is
+    recommended.
+  * ztdummy on i386/x86_64 and later 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".
+
+
+A 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.
+
+
+Extra Libraries
+~~~~~~~~~~~~~~~
+Some libraries are needed for extra utilities that are provided with
+Zaptel
+
+- libusb is needed for building fpga_load, needed for firmware loading of
+  the Xorcom Astribank.
+- libnewt is needed to build the optional but useful utility zttool.
+
+
+Distribution-Specific Instructions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==== Debian 4.0 (Etch)
+  apt-get install linux-headers-`uname -r` build-essential libnewt-dev libusb-dev
+
+==== Debian 3.1 (Sarge)
+  apt-get install kernel-headers-`uname -r` build-essential libnewt-dev libusb-dev
+
+==== RHEL4 / CentOS 4
+You need the following non-kernel-related packages:
+
+  yum install gcc newt-devel libusb-devel
+
+If the following command produces an error, you need to install
+the kernel devel package:
+
+  ls /lib/modules/`uname -r`/build/.config
+
+The right one depends on your kernel version. If the following command
+produces output you have an SMP kernel:
+
+  uname -r | grep smp
+
+and thus need to run:
+
+  yum install kernel-smp kernel-smp-devel
+
+If that command produced no output, you have a non-SMP kernel:
+
+  yum install kernel kernel-devel
+
+At this point you should probably reboot to get the new kernel in effect.
+
+
+Installation
+------------
+Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
+----------------------------------
+./configure
+# optional step: select custom configuration:
+#make menuconfig
+make
+make install
+# To install init scripts and config files:
+#make config
+----------------------------------
+
+
+Build Tweaks
+~~~~~~~~~~~~
+Selecting Modules and Utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can select the modules and utilities you wish to build and firmwares
+you wish to download by running `make menuselect` . The selection of modules 
+that you build (or rather: not build) is saved in the file 
+`menuselect.makeopts`. 
+
+
+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.
+
+Partial Build/Install
+^^^^^^^^^^^^^^^^^^^^^
+There are some make targets that are provided to build or install just
+parts of Zaptel:
+
+. Build targets:
+  - make modules: build just the kernel modules.
+  - make programs: Build just the Zaptel userspace programs. partial 
+    targets of it:
+    * make 'utilname': builds 'utilname' alone (e.g: `make ztdiag`)
+    * make utils: Build libtonezone.
+    * make libs: Build libtonezone.
+. Install targets:
+  - make install-modules: install just kernel modules.
+  - make firmware: download and install firmwares for Digium cards
+  - make install-programs: Userspace: Partial targets of it are:
+    * make install-utils: install Zaptel userspace programs and
+      and basic support files.
+    * make install-libs: install libtonezone
+    * make install-include: install zaptel.h
+  - make config: should be run once to configure 
+
+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. 
+
+  make install DESTDIR=targetdir
+
+This can be useful for any partial install target of the above (e.g:
+install-modules or install-programs).
+
+the targetdir must be an absolute path, at least if you install the
+modules. To install to a relative path you can use something like:
+
+  make install-modules DESTDIR=$PWD/target
+
+The 'install' target might fail if run as a user to a DESTDIR when
+attempting to generate device files. In that case, try:
+
+  make install DESTDIR=$PWD/target DYNFS=
+
+
+Test Install: live_zap
+^^^^^^^^^^^^^^^^^^^^^^
+If you need to test a version of Zaptel without touching the version
+installed on your system, you can use the script live_zap . Note,
+however, that it may take some extra configuration to be used right.
+
+Basic usage:
+
+  ./configure
+  make
+  ./live_zap install # instead of 'make install'
+  ./live_zap config  # instead of 'make config'
+  ./live_zap unload  # instead of '/etc/init.d/zaptel stop'
+  ./live_zap load    # instead of '/etc/init.d/zaptel start'
+
+Everything is installed under the subdirectory live/ . You will probably
+need to adjust MODULES . Generally you should not edit the script
+itself, but , rather, edit live/live.conf . Please let me know if you
+needed to change anything in the script beyond changing live.conf so I
+can include useful fixes.
+
+Testing on a different maching:
+
+  ./configure
+  make
+  ./live_zap install # instead of 'make install'
+  ./live_zap config  # instead of 'make config'
+  ./live_zap rsync root@remotehost
+  ssh root@remotehost
+  # in the remote host:
+  cd /tmp
+  ./live_zap unload
+  ./live_zap load
+
+
+./configure Options
+^^^^^^^^^^^^^^^^^^^
+The configure script various several tests and based on them generates
+some files ( build_tools/menuselect-deps and makeopts). You can pass it
+--with options and variable settings, for instance:
+
+  ./configure --without-ncurses CC="gcc-4.10"
+
+If you just want to recreate the same files without a full detection
+run, use:
+
+  ./config.status
+
+To re-run ./configure with the same parameters it was run with last
+time, use:
+
+  ./ocnfig.status --recheck
+
+
+Configuration
+-------------
+zaptel.conf
+~~~~~~~~~~~
+The main method to configure Zaptel devices is using the utility
+*ztcfg*. ztcfg reads data from the configuration file /etc/zaptel.conf ,
+figures out what configuration to send to channels, and send it. 
+
+A sample annotated zaptel.conf is included in this directory and
+installed by default to /etc/zaptel.conf . Edit it to suit your
+configuration. Alternatively use the script genzaptelconf to generate
+one that should work with your system.
+
+
+sysconfig/default
+~~~~~~~~~~~~~~~~~
+The configuration file of the zaptel init.d script is either
+/etc/default/zaptel (Debian systems) or /etc/sysconfig/zaptel (most
+others). That file is used to override defaults that are set at the
+beginning of the init.d script.
+
+For instance, to define for the init.d script to load the modules wctdm
+and xpp_usb (in that order) add the following line to that file:
+
+  MODULES="wctdm xpp_usb"
+
+Currently that file must set "TELEPHONY=yes" for the zaptel init.d to
+work.
+
+Module Parameters
+~~~~~~~~~~~~~~~~~
+The kernel modules can be configured through module parameters. Module
+parameters can optionally be set at load time. They are normally set (if
+needed) by a line in a file under /etc/modprobe.d/ or in the file
+/etc/modprobe.conf (Or /etc/modules.conf in kernel 2.4).
+
+Example line:
+
+  options zaptel debug=1
+
+The module parameters can normally be modified at runtime through sysfs:
+
+  pungenday:~# cat /sys/module/zaptel/parameters/debug 
+  0
+  pungenday:~# echo 1 >/sys/module/zaptel/parameters/debug
+  pungenday:~# cat /sys/module/zaptel/parameters/debug 
+  1
+
+Viewing and setting parameters that way is possible as of kernel 2.6 .
+In kernels older than 2.6.10, the sysfs "files" for the parameters
+reside directly under /sys/module/'module_name' .
+
+Useful module parameters:
+
+debug (most modules)::
+  Sets debug mode / debug level. With most modules 'debug' can be either
+  disabled (0, the default value) or enabled (any other value). 
+  +
+  +
+  wctdm and wcte1xp print several extra debugging messages if the value
+  of debug is more than 1.
+  +
+  +
+  Some modules have "debugging flags" bits - the value of debug is a
+  bitmask and several messages are printed if some bits are set:
+  - ztdummy:
+    * 1: DEBUG_GENERAL - general error messages.
+    * 2: DEBUG_TICKS - Show that the module is alive :-)
+  - wctdm24xxp:
+    * 1: DEBUG_CARD
+    * 2: DEBUG_ECHOCAN
+  - wct4xxp:
+    * 1: DEBUG_MAIN
+    * 2: DEBUG_DTMF
+    * 4: DEBUG_REGS
+    * 8: DEBUG_TSI
+    * 16: DEBUG_ECHOCAN
+    * 32: DEBUG_RBS
+    * 64: DEBUG_FRAMER
+  - xpp: Previously (before 1.2.26 / 1.4.11) it was called "print_dbg". 
+    See also README.Astribank:
+    * 1: GENERAL - General debug comments.
+    * 2: PCM - PCM-related messages. Tend to flood logs.
+    * 4: LEDS - Anything related to the LEDs status control. The driver
+      produces a lot of messages when the option is enabled.
+    * 8: SYNC - Synchronization related messages.
+    * 16: SIGNAL - Zaptel signalling related messages.
+    * 32: PROC - Messages related to the procfs interface.
+    * 64: REGS - Reading and writing to chip registers. Tends to flood
+          logs.
+    * 128: DEVICES - Device instantiation, destruction and such.
+    * 256 - COMMANDS - Protocol commands. Tends to flood logs.
+
+deftaps (zaptel)::
+  The default size for the echo canceller. The number is in "taps", that
+  is "samples", 1/8 ms. The default is 64 - for a tail size of 8 ms.
+  +
+  +
+  Asterisk's chan_zap tends to pass its own value anyway, with a
+  different default size. So normally setting this doesn't change
+  anything.
+
+To get a list of parameters supported by a module, use 
+
+  modinfo module_name
+
+Or, for a module you have just built:
+
+  modinfo ./module_name.ko
+
+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 .
+
+
+Reference Configuration
+-----------------------
+include::zaptel.conf.asciidoc[]
+
+Tonezones
+~~~~~~~~~
+The file zonedata.c contains the information about the tone zones used
+in libtonezone (and hence also in ztcfg). Here is a list of those zones:
+
+include::tonezones.txt[]
+
+
+Zaptel PERL modules
+-------------------
+The directory xpp/utils has, in addition to helper utilities for the
+Xorcom Astribank, a collection of perl modules to provide information
+related to Zaptel. The perl modules themselves are under xpp/utils/zconf .
+In xpp/utils there are several utilities that use those modules:
+- xpp-specific: zt_registration, xpp_sync, xpp_blink .
+- General: lszaptel, zapconf, zaptel_hardware
+
+The zaptel perl modules will currently only be automatically installed
+if you happen to isntall the xpp module. This should be the defualt, but
+you can also initiate it manually by running:
+
+  make -C xpp/utils install
+
+Those utilities require the perl modules to be installed, however they
+will also look for them in the directory zconf, and thus can be run
+directly from the zaptel source tree. For example:
+
+  ./xpp/utils/zaptel_hardware
+
+To get usage information on a program, you can also use perldoc
+(sometimes provided in a package separate from perl itself). For
+instance:
+
+  perldoc ./xpp/utils/lszaptel
+
+Some of them are specific for the Xorcom Astribank and described in its
+docuemntation. the others are:
+
+lszaptel:: 
+  A somewhat glorified `cat /proc/zaptel/*`.
+zapconf:: 
+  An currently experimental and intended to eventually replace
+  genzaptelconf by a more maintainable code.
+zaptel_drivers::
+  A two-liner script (not installed by default) that simply returns the
+  modules that should be modprobed on this system.
+zaptel_hardware:: 
+  Uses the information from sysfs and its own knowledge to show
+  what PCI/USB Zaptel hardware is connected and if it is currently used
+  by a driver. Shows also some more information for Astrobanks from
+  /proc/xpp .
+
+Internals
+---------
+Zaptel Device Files
+~~~~~~~~~~~~~~~~~~~
+Userspace programs will usually interact with Zaptel through device
+files under the /dev/zap directory (pedantically: characted device files 
+with major number 196) . Those device files can be generated statically
+or dynamically through the udev system.
+
+* /dev/zap/ctl (196:0) - a general device file for various information and
+  control operations on the zaptel channels.
+* /dev/zap/NNN (196:NNN) - for NNN in the range 1-249. A device file for
+  zaptel channel NNN. It can be used to read data from the channel
+  and write data to the channel.
+* /dev/zap/transcode (196:250) - Used to connect to a zaptel transcoding
+  device.
+* /dev/zap/timer (196:253) - Allows setting timers. Used anywhere?
+* /dev/zap/channel (196:254) - Can be used to open an arbitrary zaptel
+  channel. This is an alternative to /dev/zap/NNN that is not limited to
+  249 channels.
+* /dev/zap/pseudo (196:255) - A timing-only device. Every time you open
+  it, a new Zaptel channel is created. That Zaptel channel is "pseudo" -
+  Zaptel recieves no data in it, and only sends garbage data with the
+  same timing as the Zaptel timing master device.
+
+
+Zaptel Timing
+~~~~~~~~~~~~~
+A PBX system should generally have a single clock. If you are connected
+to a telephony provider via a digital interface (e.g: E1, T1) you should
+also typically use the provider's clock (as you get through the
+interface). Hence one important job of Asterisk is to provide timing to
+the PBX. 
+
+Zaptel "ticks" once per millisecond (1000 times per second). On each
+tick every active zaptel channel reads and 8 bytes of data. Asterisk
+also uses this for timing, through a zaptel pseudo channel it opens.
+
+However, not all PBX systems are connected to a telephony provider via
+a T1 or similar connection. With an analog connection you are not synced
+to the other party. And some systems don't have Zaptel hardware at all.
+Even a digital card may be used for other uses or is simply not
+connected to a provider. Zaptel cards are also capable of providing timing 
+from a clock on card. Cheap x100P clone cards are sometimes used for
+that pupose.
+
+If all the above fail, you can use the module ztdummy to provide timing
+alone without needing any zaptel hardware. It will work with most
+systems and kernels.
+
+You can check the zaptel timing source with zttest, which is a small 
+utility that is included with zaptel. It runs in cycles. In each such
+cycle it tries to read 8192 bytes, and sees how long it takes. If zaptel
+is not loaded or you don't have the device files, it will fail
+immedietly. If you lack a timing device it will hang forever in the
+first cycle. Eitherwise it will just give you in each cycle the percent
+of how close it was. Also try running it with the option -v for a
+verbose output.
+
+To check the clock source that is built into ztdummy, you can either
+look at title of its span in /proc/zaptel file for a "source:" in the
+description. Or even run:
+
+  strings zaptel.ko | grep source:
+
+
+Spans and Channels
+~~~~~~~~~~~~~~~~~~
+Zaptel provides telephony *channels* to the userspace applications. 
+Those channels are channels are incoreperated into logical units called
+*spans*.
+
+With digital telephony adapters (e.g: E1 or T1), a span normally 
+represents a single port. With analog telephony a span typically
+represents a PCI adapter or a similar logical unit.
+
+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/zaptel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A simple way to get the current list of spans and channels each span
+contains is the files under /proc/zaptel . /proc/zaptel is generated by
+zaptel as it loads. As each span registers to Zaptel, a file under
+/proc/zaptel is created for it. The name of that file is the number of
+that span.
+
+Each file has a 1-line title for the span followed by an empty line and
+then a line for each channel of the span. 
+
+The title line shows the number of the span, its name and title, and 
+(potentially) the alarms in which it is.
+
+The title shows the span number and name, followed by any allarms the
+span may have: For example, here is the first span in my system (with no
+alarms):
+
+  Span 1: XBUS-00/XPD-00 "Xorcom XPD #0/0: FXS"
+
+The channel line for each channel shows its channel number, name and the
+actual signalling assigned to it through ztcfg. Before being configured
+by ztcfg: This is Zaptel channel 2, whose name is 'XPP_FXS/0/0/1'.
+
+           2 XPP_FXS/0/0/1
+
+After being configured by ztcfg: the signalling 'FXOLS' was added. FXS
+channels have FXO signalling and vice versa:
+
+           2 XPP_FXS/0/0/1 FXOLS
+
+If the channel is in use (typically opened by Asterisk) then you will
+see an extra '(In use)':
+
+           2 XPP_FXS/0/0/1 FXOLS (In use)
+
+
+ABI Compatibility
+~~~~~~~~~~~~~~~~~
+Like any other kernel code, Zaptel strives to maintain a stable
+interface to userspace programs. The API of Zaptel to userspace
+programs, zaptel.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.
+
+Zaptel'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 Zaptel 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 zaptel.h (before the change) use the
+original ioctl, whether or not the kerenl 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 zaptel.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 both versions of Zaptel. 
+
+
+Past Incompatibilities
+^^^^^^^^^^^^^^^^^^^^^^
+
+.Zaptel 1.4.10:
+* Semantics of ZT_LOADZONE. Using newer ztcfg with older modules will
+  yield -EINVAL with the kernel message 'Invalid tone (96) defined'
+
+.Zaptel 1.4.8:
+* ZT_GET_PARAMS_V1
+* ZT_SET_PARAMS_V1
+* ZT_SPANINFO_V2
+
+.Zaptel 1.4.6:
+* ZT_SPANINFO_V1
+
+ZT_SPANINFO_V1 was originally called (up to zaptel 1.4.8)
+"ZT_SPANINFO_COMPAT".
+
+
+PPP Support
+-----------
+Zaptel digital cards can provide data channels through ppp as
+point-to-point connections. This requires a plugin to the ppp daemon
+that is included in the ppp/ subdirectory. To install it:
+
+1. Make sure you have the PPP source / headers installed. On Debian:
+
+   apt-get install ppp-dev
+
+2. Run 'make' on the ppp subdirectory:
+
+   make -C ppp 
+   make -C ppp install
+
+3. 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 .
+
+
+What is the license for the zaptel driver?
+------------------------------------------
+libpri is distributed under the terms of the GNU General Public License, 
+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 zaptel 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.
+
+
+How do I report bugs or contribute?
+-----------------------------------
+Please report bug and patches to the Asterisk.org bug tracker at
+http://bugs.digium.com in the "zaptel" category.
+
+
+Does anything use this library so far?
+--------------------------------------
+Yes, the Asterisk Open Source PBX does. http://www.asterisk.org
+
+
+Links
+-----
+- http://asterisk.org/[] - The Asterisk PBX
+- http://voip-info.org/[]
+- http://voip-info.org/wiki/view/Asterisk+Zaptel+Installation[]
+- http://www.zapatatelephony.org/[] - A historical site.
+- http://rapid.tzafrir.org.il/docs/README.html[Up-to-date HTML version
+  of this file]