* Include init.conf in the README as well.

* Initial support for referencing configuration directives from the
  asciidoc-ed README.
* Ignore files generated while making documentation.


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

1 files changed, 40 insertions, 178 deletions

diff --git a/README b/README
index c5063ac..51e7df7 100644
--- a/README
+++ b/README
@@ -3,7 +3,9 @@ Zapata Telephony Interface Driver
 Asterisk Development Team <asteriskteam@digium.com>
 $Revision$, $Date$
 
-Zaptel is a short for ZAPata TELephony.
+DAHDI stands for Digium Advanced Hardware Digital Interface. This
+package contains the userspace tools to configure the kernel modules
+included in the package dahdi-linux.
 
 Supported Hardware
 ------------------
@@ -24,7 +26,6 @@ Digital Cards
   * 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
@@ -38,22 +39,21 @@ Analog Cards
 - 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.
+- dahdi_dynamic_eth: TDM over Ethernet (TDMoE) driver. Requires ztdynamic
+- dahdi_dynamic_loc: Mirror a local span. Requires ztdynamic
+- dahdi_dummy: 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.
+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:
@@ -66,60 +66,6 @@ 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.
@@ -139,36 +85,7 @@ Zaptel
 
 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.
+TO BE WRITTEN
 
 
 Installation
@@ -187,41 +104,18 @@ make install
 
 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.
@@ -251,41 +145,6 @@ 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
@@ -304,35 +163,31 @@ time, use:
 
   ./ocnfig.status --recheck
 
+TODO: building with a local copy of DAHDI?
+
 
 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.
+Configuration for DAHDI resides under /etc/dahdi . 
+/etc/dahdi/system.conf
+~~~~~~~~~~~~~~~~~~~~~~
+The main method to configure DAHDI devices is using the utility
+*dahdi_cfg*. dahdi_cfg reads data from the configuration file 
+/etc/dahdi/system.conf , figures out what configuration to send to 
+channels, and send it to the kernel.
 
+A sample annotated system.conf is included in this directory and
+installed by default. Edit it to suit your configuration. Alternatively 
+use the script dahdi_genconf 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"
+/etc/dahdi/init.conf
+~~~~~~~~~~~~~~~~~~~~
+The configuration file of the dahdi init.d script is
+/etc/dahdi/init.conf . That file is used to override defaults that are 
+set at the beginning of the init.d script.
 
-Currently that file must set "TELEPHONY=yes" for the zaptel init.d to
-work.
 
 Module Parameters
 ~~~~~~~~~~~~~~~~~
@@ -370,7 +225,7 @@ debug (most modules)::
   +
   Some modules have "debugging flags" bits - the value of debug is a
   bitmask and several messages are printed if some bits are set:
-  - ztdummy:
+  - dahdi_dummy:
     * 1: DEBUG_GENERAL - general error messages.
     * 2: DEBUG_TICKS - Show that the module is alive :-)
   - wctdm24xxp:
@@ -384,8 +239,7 @@ debug (most modules)::
     * 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:
+  - xpp: 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
@@ -398,12 +252,12 @@ debug (most modules)::
     * 128: DEVICES - Device instantiation, destruction and such.
     * 256 - COMMANDS - Protocol commands. Tends to flood logs.
 
-deftaps (zaptel)::
+deftaps (dahdi)::
   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
+  Asterisk's chan_dahdi tends to pass its own value anyway, with a
   different default size. So normally setting this doesn't change
   anything.
 
@@ -422,7 +276,15 @@ in README.Astribank .
 
 Reference Configuration
 -----------------------
-include::zaptel.conf.asciidoc[]
+Sample system.conf
+~~~~~~~~~~~~~~~~~~
+include::system.conf.asciidoc[]
+
+
+Sample init.conf
+~~~~~~~~~~~~~~~~~~
+include::init.conf.asciidoc[]
+
 
 Tonezones
 ~~~~~~~~~