A README that will actually help users a bit.

git-svn-id: http://svn.digium.com/svn/zaptel/branches/1.4@2662 5390a7c7-147a-4af0-8ec9-7488f05a26cb

1 files changed, 149 insertions, 32 deletions

diff --git a/README b/README
index a97f2fe..7ac7827 100644
--- a/README
+++ b/README
@@ -1,8 +1,144 @@
 Zapata Telephony Interface Driver
+=================================
+Asterisk Development Team <asteriskteam@digium.com>
+$Revision$, $Date$
+
+Zaptel is a short for ZAPata Telephony.
+
+Supported Hardware
+------------------
+PRI Cards
+~~~~~~~~~
+- wct4xxp: 
+  - Digium newer quad-span T1/E1 cards: Wildcard TE420P/TE410P/TE405P 
+  - Digium newer dual-span T1/E1 cards: Wildcard TE220P/TE210P/TE425P 
+- wcte12xp: Digium Wildcard TE12xP single-span T1/E1 card
+- wcte11xp: Digium Wildcard TE110P T1/E1
+- wct1xxp: 
+  - Wildcard T100P (old single-span T1)
+  - Wildcard E100P (old single-span 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 card: up to 24 analog ports
+  - Digium TDM800P card: up to 8 analog ports
+- wctdm: Digium TDM400P card: up to 4 analog ports
+- xpp: Xorcom Astribank: a USB connected unit of up to 32 ports
+  (also BRI)
+- wcfxo: X100P, similar and clones. A simple single-port FXO card
+- wcfxs: 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.
+
+
+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 .
+- 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".
+- ztdummy on i386/amd64 and later kernels (>= 2.6.15) can (and should)
+  use the system's RTC (Real Time Clock).
+- 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).
+
+
+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.
+
+On Debian and similar distributions run:
+
+   apt-get install build-essential
+
+On Centos and Fedora:
+
+  apt-get install gcc
+
+
+Extra Libraries
+~~~~~~~~~~~~~~~
+Some libraries are needed for extra utilities that are provided with
+Zaptel
+
+- libusb is needed for building fpgaload, needed for firmware loading of
+  the Xorcom Astribank.
+- libnewt is needed to build the optional but useful utility zttool.
+- For building usbfxstest you will need the zapata library. TODO:
+  Needed?
+
+Installing the first two on Debian:
+
+  apt-get install libusb-dev libnewt-dev
+
+Installing the first two on Centos/Fedora:
+
+  yum install libusb-devel libnewt-devel
+
+
+Installation
+------------
+
+  ./configure
+  # optional step: 
+  #make menuconfig
+  make
+  make install
+  # To install init scripts and config files:
+  #make config
+
+
 
 Note:
 See
-http://www.voip-info.org/tiki-index.php?page=Asterisk%20Zaptel%20Installation
+http://www.voip-info.org/wiki/view/Asterisk+Zaptel+Installation
 for more verbose and updated version of this document.
 
 Requirements:
@@ -16,34 +152,9 @@ To install:
 
 Here is a list of what module to use with what hardware
 
-Module Name	Hardware
-tor2		T400P - Quad Span T1 Card
-		E400P - Quad Span E1 Card
-
-wct4xxp		TE405P - Quad Span T1/E1 Card (5v version)
-		TE410P - Quad Span T1/E1 Card (3.3v version)
-
-wct1xxp		T100P - Single Span T1 Card
-		E100P - Single Span E1 Card
-
-wcte11xp	TE110P - Single Span T1/E1 Card
-
-wcfxo		X100P - Single port FXO interface
-		X101P - Single port FXO interface 
-
-wctdm or	TDM400P - Modular FXS/FXO interface (1-4 ports)
-wcfxs
-
-wcusb or	S100U - Single port FXS USB Interface
-wcfxsusb	
-
-torisa		Old Tormenta1 ISA Card
-
-ztdummy		UHCI USB Zaptel Timing Only Interface
-
 
 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.
@@ -55,11 +166,10 @@ at reasonable cost.
 
 
 Brief F.A.Q
-===========
-
+-----------
 Q. Zaptel compiled with no errors but when I try to modprobe zaptel I
 receive "FATAL: Error insering zaptel (/lib/modules/2.6.x.x/misc/zaptel.ko):
-Unknown symol in module or unknown parameter (see dmesg)
+Unknown symbol in module or unknown parameter (see dmesg)
 
 A. You need to recompile your kernel with CONFIG_CRC_CCITT=y or
 CONFIG_CRC_CCITT=m. To do this, run 'make menuconfig' and change it under 
@@ -67,11 +177,18 @@ CONFIG_CRC_CCITT=m. To do this, run 'make menuconfig' and change it under
 load it, otherwise reboot.
 
 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.