xpp.r4584:

* New firmware to fix FXS leds irregularities.
* Less noise at build time - don't echo version, test compile only once.
* zapconf can generate users.conf snippets.
* xpd_pri: initial version.


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

1 files changed, 392 insertions, 308 deletions

diff --git a/xpp/README.Astribank b/xpp/README.Astribank
index 3c476ee..d9a8015 100644
--- a/xpp/README.Astribank
+++ b/xpp/README.Astribank
@@ -23,33 +23,26 @@ Astribank drivers, apart from the standard 'make':
   make -C xpp/utils install
 
 In order to build the user space utilities, you will need the libusb-dev
-package on Debian (and derivatives like ubuntu) or libusb-devel on RedHat
-(and derivatives like Centox/Trixbox).
+package on Debian (and derivatives like Ubuntu) or libusb-devel on RedHat
+(and derivatives like CentOS/Trixbox).
 
-And the following extra step to install:
-
-  make -C xpp/utils install
 
 INSTALLATION
 ------------
 
-apart from the standard 'make install' in the zaptel directory, 
+Apart from the standard 'make install' in the zaptel directory, 
 run:
 
   make -C xpp/utils install
 
 Though this should be done automatically on zaptel >= 1.4.1 .
 
-Also consider editing xpp/utils/Makefile and removing the commant before
-the line that begins with PERLLIBDIR. This will install some perl modules 
-and utilities that will help you with the usage of the Astribank.
-
 Alternatively, do the following manually:
 
-All firmware files should be copied to a new directory:
+All firmware files and scripts should be copied to the new directory:
   /usr/share/zaptel/
 
-The xpp_fxloader and xpp_fxloader.usermap should be copied to:
+xpp_fxloader.usermap should be copied to:
  /etc/hotplug/usb/
 
 Run:
@@ -62,31 +55,30 @@ to load firmware.
 LEDs Indication
 ---------------
 The Astribank has 4 global indication leds and one or two per-port leds.
-In the Astribank 16 and in the Astribank BRI (USB product IDs 113x and 
-114x, respectively) the indication leds will normally be in the side.
-
-In the 1U models (USB product IDs 115x) the indication leds will normally
-be the first (leftmost) red leds of the device. Don't mistake them for 
-per-port leds.
-
-The first led is the "Power" led. It is lit if the unit gets power.
-The second led is the "Active" led, which is lit when there is there at 
-least one "active" (in a call / off-hook, though the meaning of this is 
+On some of the models the LEDs are located on the left side on the front
+panel. If there are no separate LEDs there, then the red LEDs of the
+upper left-most ports of the device are used as the indication leds. Don't 
+confuse them with green port status leds.
+
+The first led is the "Power" led. It is on if the unit gets power.
+The second led is the "Active" led, which is on when there is at 
+least one "active" port (in a call / off-hook, though the meaning of this is 
 different in BRI).
-The last led is called "Hardware OK", but is actually only lit if the 
-hardware is not OK.
+The last led is called "Hardware OK", but is actually only is on in case of  
+the hardware failure.
 
-The third led is the "Sync" led. If it blinks, the device is in sync 
-with the driver on the computer. If the device is the synchronization 
-source for all the Astribank devices it will blink a quick single blink.
+The third led is the "Sync" led. If it blinks, the device is synchronized 
+with the driver on the computer. If the device is selected to be the  
+synchronization source for all of the Astribank devices then it will blink
+a quick single blink.
 If the device gets synchronization from the driver, it will blink in a 
-more steady blink.
+more steady frequency.
 
 "Double blink" indicates that the unit has an FXO module, and still is
-getting synchronization from the computer, and does not provide 
-synchronization.
+getting synchronization from the computer, and is not the synchronization
+source.
 
-The per-port green led on analog (both FXS and FXO) indicate that the
+The per-port green led on analog (both FXS and FXO) indicates that the
 port is off-hook.
 
 On the BRI, the green led indicates a TE port whereas an orange led
@@ -98,223 +90,299 @@ is up. A slower single blinking indicates that layer 2 is up as well
 
 DEVICE STARTUP
 --------------
+This section describes in great depth the initialization of the Xorcom
+Astribank. Normally it would not be really needed, as the standard
+installation of Zaptel should put everything in place.
 
 Terminology
 ~~~~~~~~~~~
-Some technical terms that are used throughout the document and in the
-driver / zaptel . Only used in the technical parts.
+There are some technical terms that are used in this document and in the
+driver / zaptel.
 
 span:
-Zaptel breaks the channels it knows bout to logical units called
-"spans". A port in a E1/T1/ISDN card is usually a span. So is a complete
-analog card. You can see the list of spans as the list of files under
-/proc/zaptel or the list in zttool.
+Zaptel breaks the channels it knows about to logical units called
+"spans". A port in a E1/T1/ISDN card is usually a span. An whole
+analog card is also a "span". You can see the list of spans as the list
+of files under /proc/zaptel directory or in output of the zttool
+utility.
 
 XBUS:
 A funny way to call an Astribank device.
 
 XPD:
-This is basically a logical unit of the Astribank. It will be registered to
+Basically this is a logical unit of the Astribank. It will be registered in
 Zaptel as a single span. This can be either an analog (FXS or FXO)
-module or a single port in a BRI module.
+module or a single port in case of a BRI module.
 
 
 Loading Firmware
 ~~~~~~~~~~~~~~~~
-Normally this is done using the script /usr/share/zaptel/xpp_fxloader .
-If it works fine, you don't need to bother reading this section. 
-Once the firmware is loaded the USB ID of the Astribank changes to e4e4
-11x2, and the driver can pick it up. You'll also see the top led lit.
+Normally this is done using the script /usr/share/zaptel/xpp_fxloader.
+If it works fine, you don't need to bother reading this section.
+Once the firmware is loaded the USB Vendor ID and Product ID of the Astribank
+became to be e4e4 11x2, and now the driver can pick it up.
 
 First and foremost: the simplest and most useful tool to debug problems
-here is lsusb. The output of lsusb should show exactly if the device is
-connected and if its firmware is loaded. 
+is lsusb. The output of lsusb should show you if the device is connected
+if its firmware is loaded. 
 
-The firmware files are named *.hex. The are in the Intel hex format 
-(read: plain text, but not readable) that is copied at install time from 
-xpp/utils to /usr/share/zaptel .
+The firmware files are named *.hex. They are presented in the text
+hexadecimal format The files are copied from xpp/utils to /usr/share/zaptel
+folder during the Zaptel installation.
 
 The Astribank needs a firmware loaded into it. Without the firmware, 
-the device will appear in lsusb with vendor ID e4e4 and product ID 1130.
-The firmware is loaded in two stages. In the first stage we load the
-"USB" firmware using the program fxload. After the first stage the USB
-ID is e4e4 1131. In the second stage we load the "FPGA" firmware.
+the device will appear in lsusb with Vendor ID e4e4 and Product ID 1130.
+The firmware loading process consists of two stages. In the first stage the
+"USB" firmware is loaded by using program fxload. When the first stage is
+completed the Vendor ID is e4e4 and the Product ID is 1131.
 
-The first is done using the the program fxload. To load it manually, use
-the command:
+You can use the following command in order to load the "USB" firmware
+manually:
 
   fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_1130.hex
 
-fxload is standard program that is typically part of the package 'fxload' 
-or 'hotplug-utils' . /proc/bus/usb is the mount point of the USB
-file-system (usbfs). MMM is the first number (bus number) and NNN is the
-second number (device number) you see for the device in lsusb, with full
-3 digits. If the load is successful, the device disconnects and
-reconnects with USB product ID 1131 (and a new device number).
+where,
+
+fxload::
+  A standard program that is typically part either of package 'fxload' 
+  or 'hotplug-utils' . 
+/proc/bus/usb::
+  The mount point of the USB file-system (usbfs).
+MMM::
+  the first number (bus number)
+NNN::
+  the second number (device number) you see for the device in lsusb
+
+If the loading process has been completed successfully, the device 
+disconnects and then connects again itself with USB Product ID 1131 
+(and a new device number).
+
+In the second stage, the "FPGA" firmware is loaded.
+The second-stage firmware loading is performed by using program fpga_load, 
+which is built in the directory xpp/utils and then copied to folder 
+/usr/sbin during Zaptel installation.
+
+The command syntax is similar to the syntax of fxload. You can use the 
+following command in order to load the "USB" firmware manually:
 
-The second-stage loader is done using the program fpga_load, which is
-built in the directory xpp/utils and installed to /usr/sbin/fpga_load .
-Its syntax is based on fxload. To load with it manually, use:
-  
   fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_FXS.hex
 
-Note that as the device has reconnected, it now has a new device
-number. So you need to re-check the value of NNN with lsusb. Typically
-this will be the old value + 1.
+Please note, that  NNN value differs from that that was used for the 
+fxload command due to the fact that device has "reconnected" itself 
+with another Product ID number. So you need to run lsusb again and get 
+the new NNN value. Usually, the new value is equal to the old value 
+incremented by 1.
 
 
 Firmware Loading with Hotplug
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The Hotplug framework was popular for hotplugging and usually also 
-autoloading drivers. If it is used on your system, you'll see 
-/etc/hotplug with many files under it. Hotplug will automatically load
-most relevant USB and PCI kernel modules by the relevant USB and PCI
-IDs. Again: if the framework is in place and the proper configuration
-files are in place, the firmware should be loaded automatically.
-
-In order to get hotplug to autoload the firmware into the Astribank, 
-the configuration file xpp_fxloader.usermap and the script xpp_fxloader 
-should be copied into /etc/hotplug/usb/ . This is done by 'make -C
-xpp/utils install' .
-
-xpp_fxloader.usermap includes a map of USB IDs and the command to run 
-when they are encountered. It instructs hotplug to run the script 
-xpp_fxloader from that directory. This is done by 'make -C
+The Hotplug framework was popular for hotplugging different devices and 
+usually also for automatic device drivers loading. If Hotplug is used in 
+your system, you'll see many files in folder /etc/hotplug. Hotplug will 
+automatically load the most relevant USB and PCI kernel modules according 
+to the USB and PCI IDs provided by devices. Please note, that if the 
+Hotplug framework is in place and the correct configuration files are 
+located in the right place, then the firmware should be loaded automatically.
+
+In order to get the Hotplug framework to load the firmware into the 
+Astribank automatically, the configuration file xpp_fxloader.usermap and
+the script xpp_fxloader should be copied into /etc/hotplug/usb/ . This is 
+done by 'make -C xpp/utils install'.
+
+File xpp_fxloader.usermap includes a map of USB IDs and the command to run 
+when such devices are encountered. It instructs the Hotplug to run the script 
+xpp_fxloader from that directory. This is also done by 'make -C
 xpp/utils install' .
 
 When xpp_fxloader is run without any parameters it assumes that it was
-run by the hotplug scripts. It will then check if the even is an "add"
-event (and not a "remove" event), and if so, install the required
-firmware file. It will be called twice, as after the load of the USB
-firmware the device will reenumerate itself and thus "unplug" and
-"replug" to load the FPGA firmware.
+run by the hotplug scripts. Then it will check if the "add" event was 
+accepted and if so, xpp_fxloader will install the required firmware file. 
+The xpp_fxloader will be called twice, as after the load of the USB 
+firmware the device will re-enumerate itself and thus "unplug" and 
+"replug" in order to load the FPGA firmware.
 
 
 Firmware Loading with UDEV
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 The UDEV framework has replaced Hotplug in most recent systems. If you
-have a recent 2.6 system with no Hotplug and files under /etc/udev,
-chances are you ude udev. udev does quite a few nice things.
-Again: if the framework is in place and the proper configuration
-files are in place, the firmware should be loaded automatically.
+have a recent 2.6 system without Hotplug and with many files in folder
+/etc/udev, then there are good chances that are you using udev.
+As in case of Hotplug, if your udev framework is configured properly
+then the firmware should be loaded automatically.
 
-In order to get hotplug to autoload the firmware into the Astribank, 
-the configuration file xpp.rules should be copied into /etc/udev/rules.d 
-and the script xpp_fxloader should be copied into /etc/hotplug/usb/ . 
-This is done by 'make -C xpp/utils install' .
+In order to get udev to automatically load the firmware into the Astribank, 
+the configuration file xpp.rules should be copied into folder /etc/udev/rules.d 
+and the script xpp_fxloader should be copied into folder /etc/hotplug/usb/ . 
+This is done by 'make -C xpp/utils install' during Zaptel installation.
 
-xpp.rules instructs udevd to run xpp_fxloader with the option udev and
-the USB ID when an Astribank is plugged and needs loading firmware.
-When xpp_fxloader is run with the option udev it assumes that it was
-run by udevd scripts. It will then install the required firmware file. 
-It will be called twice, as after the load of the USB firmware the
-device will reenumerate itself and thus "unplug" and "replug" to load 
-the FPGA firmware.
+File xpp.rules instructs the udevd daemon to run xpp_fxloader script with
+the option "udev" and with the Astribank USB ID obtained from the 
+device when it is plugged in.
+Please note, that exactly like in case of Hotplug, the xpp_fxloader will be
+called twice by the udevd. First time for the USB firmware loading and the 
+second time for FPGA firmware loading.
 
 
 Firmware Resetting
 ~~~~~~~~~~~~~~~~~~
 Newer versions of the USB firmware can now be reset using 'fpga_load -r'.
 This will only work when the device is not used by the driver, so you may 
-need to 'rmmod xpp_usb' in order to reset the firmware.
+need to run 'rmmod xpp_usb' before.
 
-Also try:  
+Also you can try the following:
 
   rmmod xpp_usb; /usr/share/zaptel/xpp_fxloader reset
   # if asterisk was running: you may need to stop/restart it now. 
   # if there are some "disconnected" spans in /proc/xpp/xbuses
   # wait a while, until you see the 1152 IDs again, and then:
   /etc/init.d/zaptel start
-  # and start/restrart asterisk.
+  # and start/restart asterisk.
 
 
 Loading The Modules
 ~~~~~~~~~~~~~~~~~~~
 Here is what should happen:
-In short: you should plug it or have it plugged at boot time, and all
-the modules should load. You will see xpp_usb , xpd_fxs and possibly
-xpd_fxo in the modules list (the output of lsmod).
+In short: you should plug the Astribank device(s) or have them plugged in at
+the boot time. Then all the modules should be loaded automatically.
+You will see xpp_usb , xpd_fxs and, possibly, xpd_fxo in the modules list
+(the output of lsmod).
 
 After the module xpp is loaded, you'll also be able to see the directory
-/proc/xpp . For any Astribank discovered there you will see a directory
-/prc/xpp/XBUS-n (where n is a number: typically 0). Once a unit have
+/proc/xpp. For any Astribank device discovered, you will see there a 
+directory /proc/xpp/XBUS-n (where n is a number: typically 0). Once a unit have
 been discovered you'll see subdirectories: /proc/xpp/XBUS-n/XPD-m (where
 m may be another number: 0, 1 ,etc).
 
 Now to the ugly details:
 
-The driver of the Astribank is composed of several modules: xpp is the
-basic one, that contains the functionality to connect to Zaptel and other
-common functions. xpd_fxs is the module for controlling FXS spans.
-xpd_fxo is the module for controlling FXO spans. xpd_usb is the module
-that holds the functionality needed to connect to the USB bus.
+The driver of the Astribank is composed of several modules: 
+* xpp     - the basic module, that communicates with Zaptel and provides
+            some common services to other modules.
+* xpd_fxs - the module for controlling FXS spans.
+* xpd_fxo - the module for controlling FXO spans. 
+* xpd_usb - the module that holds the functionality needed to connect to the
+            USB bus.
 
 All modules depend on xpp, and modprobing them will install xpp as well.
-However the xpd_* modules are only installed on-demand: no need to
-install xpd_fxo if you only have FXS Astribank.
+However the xpd_* modules are installed on-demand: no need to install
+the xpd_fxo if you have only Astribank FXS.
 
-You either plug in the Astribank , or start the hotplug/udev system 
-while an Astribank is connected, after the firmware is loaded. The 
-Vendor-ID/Product-ID of the device is e4e4/1132 . The handler for that
-combination is listed as the kernel module xpp_usb . Thus the system
+Once an Astribank device connected and the firmware is loaded, the
+Vendor-ID/Product-ID of the device will be  e4e4/1132 . The handler for that
+combination is listed as the kernel module xpp_usb. Therefore, the system
 runs 'modprobe xpp_usb' if that module is not already loaded.
 
-The module xpp_usb depends on the modules zaptel and xpp . Both of which 
-are loaded before xpp_usb is loaded. As usual, parameters and rules form
-/etc/modprobe.conf and/or /etc/modprobe.d/* will apply to the module, as
-modprobe is used.
+The module xpp_usb depends on the zaptel and xpp modules. Both of them 
+are loaded before xpp_usb. As usual, parameters and rules form
+/etc/modprobe.conf and/or from /etc/modprobe.d/* will be applied to 
+the module.
 
-The modules to handle the specific span types (xpd_fxs, xpd_fxo) may or
-may not have been loaded yet at this stage (when the command 'modprobe
-xpp_usb' returns).
+When command 'modprobe xpp_usb' returns, the span type specific modules
+(e.g., xpd_fxs, xpd_fxo) may or may not have been loaded yet.
 
-At this point the xpp driver asks the box what logical units it has.
-According to the answers it gets, it will figure what xpd_* modules it will
-need, and modprobe for them. At some earlier version of the driver this has
-required some special modprobe.conf setup, but this is no longer
-the case.
+At this point the xpp driver "asks" the box about type of telephony modules
+it has. According to the answers it receives, the xpp driver will "modprobe"
+the required xpd_* modules. In some earlier versions of the driver this
+operation required some special modprobe.conf configuration, but this is no
+longer the case.
 
 
 Device Initializations Scripts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The chips in the device need to be initialized. This involves sending a
+The chips in the device need to be initialized. This requires sending a
 bunch of values to certain registers in those chips. We decided that
-hardwiring those values in the driver itself would not be a good idea.
+hardwriting those values in the driver code is not a good idea.
+Before registering a XPD as a span in Zaptel, we run an initialization
+script: /usr/share/zaptel/init_card_N_MM (
+where,
+
+* N  - is 3 for an FXS span and 4 for an FXO span, and 6 or 7 for BRI.
+* MM - is a version number. Currently it equals 26
+
+If because of some reasons this fails (the script is not in the place, or the
+file doesn't have the executable permissions), then you will get an error 
+message in the logs and the XPD will then be removed (you won't see directory
+for that XPD under the corresponding /proc/xpp/XBUS-* directory) and will not
+be registered in Zaptel.
+
+As the XPD is initialized, you'll see the green LEDs of the ports steadily 
+turn on and later off ("a train of lights"). This is a bit slower than the 
+faster "blinking" when the XPDs register as Zaptel spans. The initializaton 
+of an FXS XPD may take a few seconds.
+
+
+Registering in Zaptel
+~~~~~~~~~~~~~~~~~~~~~
+The XPDs will not automatically register as zaptel spans. This is
+intended to allow you to set the registration order (and hence the order
+of Zaptel spans and channels) among multiple Astribank devices,
+or between an Astribank and a different Zaptel device.
+
+When the XPD registers to Zaptel, all the green LEDs will be lit for a
+short while. 
+
+Spans are normally registered with the utility zt_registration. Simply
+running 'zt_registration' shows the available XPDs and whether or not
+they are registered. To register: 
 
-before registering a XPD as a span in Zaptel, we run an initialization
-script: /usr/share/zaptel/init_card_N_MM (N is 3 for an FXS span and 4 
-for an FXO span, MM is a version number, and currently stands at 24). 
-If this fails (e.g: because the script is not there, or is not 
-executable), you will get an error message in the logs that the
-invocation has failed. The XPD will then be removed (you won't see that
-a directory for that XPD under the relevant /proc/xpp/XBUS-* directory)
-and not be registered with Zaptel.
+  zt_registration on
 
+For a system with several spans you'll see a "fast train of lights".
 
-Registering With Zaptel
-~~~~~~~~~~~~~~~~~~~~~~~
-Now we finally got to the "lights party" part: the lights in a unit
-(XPD) get lit before it registers with Zaptel and are turned off after
-that.
+If you have multiple Astribank devices, zt_registration will register
+them by the order of the "connector" field. This means that as long as
+the same Astribank is connected to the same port, the order of plugging
+is not important..
 
-You may choose not to register the XPDs to Zaptel automatically, to
-allow finer control of the process. This is done using the module
-parameter zap_autoreg. Set in the modprobe configuration file (e.g:
-/etc/modprobe.conf ) the line:
+zt_registration checks if a span is registered or tries to register a
+span using the file /proc/xpp/XBUS-nn/XPD-mm/zt_registration . Reading
+from that file returns 0 if the span is unregisteres or 1 if it is
+registered. You can register a span or ask to unregister it by writing 1
+(register) or 0 (unregister) to that file. Registeration should
+generally always succeed. Unregistration may fail if a span is in use.
 
-  options xpp zap_autoreg=0
+You may choose to register the XPDs in Zaptel automatically, in order to
+allow finer control of the process. This behavior may be defined by setting 
+parameter zap_autoreg in the modprobe configuration file (A file under 
+/etc/modprobe.d or /etc/modprobe.conf):
 
-to disable automatic registration at startup. You will then need to
-register the spans manually. 
+  options xpp zap_autoreg=1
+
+
+Zaptel And Above
+~~~~~~~~~~~~~~~~
+From here you get a standard Zaptel span. It still needs to be
+configured by ztcfg and used by a program such as Asterisk like any
+other Zaptel device. In order for you to get a dialtone in a phone
+connected to the FXS port or a fully synchronized BRI port (layer 2
+activated, as signalled by a more steady blink) you will actually need
+both the span configured by Zaptel and the channels configured in
+Asterisk.
+
+You should generally refer to the general Zaptel documentation on how to
+configure those levels. e.g, the README file in the toplevel directory,
+and
+
+  http://voip-info.org/wiki/view/Asterisk+config+zapata.conf[]
+
+
+Zaptel now includes a utility called genzaptelconf (written as a big
+ugly shell script) to configure Zaptel automatically as good as
+possible. For analog channels it works quite well (because, IMHO, the
+"configuration" level on Zaptel should be optional there - there are
+already sane defaults). For digital spans - BRI and PRI , it may take
+some tuning.
+
+Alternatively, write you own configuration, based on the sample from the
+following section:
 
-For your convenience the command zt_registration 
 
 
 SAMPLE CONFIGURATIONS
 ---------------------
-We generally recommend generating the configuration with the utility
+We generally recommend to generate the configuration by using utility
 genzaptelconf. The following reference configuration will work for a
-system whose sole Zaptel hardware device is the said Astribank.
+system where Astribank devices are used.
 
 /etc/zaptel.conf
 ~~~~~~~~~~~~~~~~
@@ -456,30 +524,41 @@ Astribank 4 BRI
     channel => 10,11
 
 
-See also the output of genzaptelconf for examples of mailbox and 
-callerid, and for channel numbers that will match your specific settings.
-For that reason I only give the above two sample configurations.
+Please check, that the mailbox and callerid parameters generated by
+genzaptelconf are good for you and change them if necessary.
+
+
+If you have Astribank device with 8 FXS and 8FXO ports connected and set up, then 
+the Zaptel channels will be allocated as the following:
 
-When loaded, you should get one span, of 8 extensions, 2 output ports and 
-4 input ports:
+  root@rapid:~# cat /proc/zaptel/* 
+ Span 1: XBUS-00/XPD-00 "Xorcom XPD #00/00: FXS"
 
-  root@rapid:~# cat /proc/zaptel/2 
-  Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS"
+           1 XPP_FXS/00/00/0 FXOLS (In use)
+           2 XPP_FXS/00/00/1 FXOLS (In use)
+           3 XPP_FXS/00/00/2 FXOLS (In use)
+           4 XPP_FXS/00/00/3 FXOLS (In use)
+           5 XPP_FXS/00/00/4 FXOLS (In use)
+           6 XPP_FXS/00/00/5 FXOLS (In use)
+           7 XPP_FXS/00/00/6 FXOLS (In use)
+           8 XPP_FXS/00/00/7 FXOLS (In use)
+           9 XPP_OUT/00/00/8 FXOLS (In use) (no pcm)
+          10 XPP_OUT/00/00/9 FXOLS (In use) (no pcm)
+          11 XPP_IN/00/00/10 FXOLS (In use) (no pcm)
+          12 XPP_IN/00/00/11 FXOLS (In use) (no pcm)
+          13 XPP_IN/00/00/12 FXOLS (In use) (no pcm)
+          14 XPP_IN/00/00/13 FXOLS (In use) (no pcm)
+ Span 2: XBUS-00/XPD-01 "Xorcom XPD #00/01: FXO" (MASTER)
+
+          15 XPP_FXO/00/01/0 FXSKS (In use)
+          16 XPP_FXO/00/01/1 FXSKS (In use) (no pcm)
+          17 XPP_FXO/00/01/2 FXSKS (In use) (no pcm)
+          18 XPP_FXO/00/01/3 FXSKS (In use) (no pcm)
+          19 XPP_FXO/00/01/4 FXSKS (In use) (no pcm)
+          20 XPP_FXO/00/01/5 FXSKS (In use) (no pcm)
+          21 XPP_FXO/00/01/6 FXSKS (In use) (no pcm)
+          22 XPP_FXO/00/01/7 FXSKS (In use) (no pcm)
 
-           1 XPP_FXS/0-0 FXOKS (In use) 
-           2 XPP_FXS/0-1 FXOKS (In use) 
-           3 XPP_FXS/0-2 FXOKS (In use) 
-           4 XPP_FXS/0-3 FXOKS (In use) 
-           5 XPP_FXS/0-4 FXOKS (In use) 
-           6 XPP_FXS/0-5 FXOKS (In use) 
-           7 XPP_FXS/0-6 FXOKS (In use) 
-           8 XPP_FXS/0-7 FXOKS (In use) 
-           9 XPP_OUT/0-8 FXOKS (In use) 
-          10 XPP_OUT/0-9 FXOKS (In use) 
-          11 XPP_IN/0-10 FXOKS (In use) 
-          12 XPP_IN/0-11 FXOKS (In use) 
-          13 XPP_IN/0-12 FXOKS (In use) 
-          14 XPP_IN/0-13 FXOKS (In use) 
 
 Sample dialplan (extensions.conf) for all the above:
 
@@ -517,7 +596,7 @@ include => astbank-test
 exten => s,1,Dial(Zap/1) 
 
 ; Alternatively, the following will redirect you to the demo IVR 
-; from the sample extenbtions.conf of Asterisk:
+; from the sample extensions.conf of Asterisk:
 include => demo
 
 ; An extra context with some simple tests
@@ -555,65 +634,63 @@ exten => s,n,NoOp(Got signal from Zaptel Channel ${ZAP_CHAN})
 
 /proc Interface
 ---------------
-The Astribank drivers provide their own /proc interface under /proc/xpp .
+The Astribank drivers provide their own /proc interface under /proc/xpp.
 (Note that the details of this interface are still potentially subject to 
 changes)
 
-/proc/xpp/xbuses lists the connected devices (an xbus is such a device), 
-one per line. A device is normally "connected". "missing" means that it
-was disconnected, but Asterisk still holds channels from it open. You can
-also see in the xbuses file to which physical connection the Astribank
-is connected.
-
-/proc/xpp/sync is a read/write file . It prints the current
-synchronization source. printing to it can change the synchronization
-source. Host-synchronization is currently the default but for better
-sound quality you should synchronize from the Astribank.
+File /proc/xpp/xbuses lists the connected Astribank devices (one xbus per device.)
+A device is normally has status "connected". The status "missing" means that
+the device has been disconnected, but Asterisk still holds channels from it
+open.
 
-Reading it may provide you some information regarding the timing
-behaviour of Asterisk.
+File /proc/xpp/sync is a read/write file. It contains information about current
+synchronization source. You can change the synchronization source by writing 
+special command to the file. For example, command
+   echo SYNC=01 > /proc/xpp/sync
+will force the system to use the Astribank device connected to span 1 as the 
+synchronization source.
 
-/proc/xpp/XBUS-nn gives information about device number nn (starting from
-00). under it, /proc/XBUS-nn/XPD-mm gives information regarding span number
-m in that device.
+For each Astribank device there is folder /proc/xpp/XBUS-nn and for each device
+module (span in the therms of Zaptel) there is folder /proc/XBUS-nn/XPD-mm.
 
-/proc/xpp/XBUS-nn/XPD-mm/zt_registration is a read-write file for
-manually registering/unregistering the span with Zaptel. A span will 
+File /proc/xpp/XBUS-nn/XPD-mm/zt_registration is a read/write file that may be
+used for registering/unregistering the span in Zaptel manually. A span will be
 register automatically when generated, though. Span unregistration may
 fail if some channels from the span are used (e.g: by Asterisk).
-Registration is by writing 1 and unregistration is by writing 0 to the
-file.
-
-  watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary
+You can register or unregister particular span manually by writing 1 or 0
+and unregistration is by writing 0 to the file.
 
-This shows which ports are off-hook, which are ringing, etc. It also 
-shows the current audio sample in both direction, which is useful to 
-see if there is something going at all.
+File /proc/xpp/XBUS-nn/XPD-mm/summary contains detailed information 
+about port statuses of the device module (off-hook, on-hook etc.)
+For example, you can run the following command in order to monitor
+the port statuses in the real time:
 
+watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary
 
-For FXO modules, /proc/xpp/XBUS-nn/XPD-mm/fxo_info also provides a
-"battery" line to show if the 
+In case of FXO modules, you can also see if there is a line connected to 
+a FXO port. See value of parameter "line" in file 
+/proc/xpp/XBUS-nn/XPD-mm/fxo_info provides.
 
-
-For the BRI module, /proc/xpp/XBUS-nn/XPD-mm/bri_info provides very
-useful information regarding layer 1 and layer 2 status. For the
-lower-layer status:
+In case of BRI modules, /proc/xpp/XBUS-nn/XPD-mm/bri_info provides very
+useful information regarding ISDN Layer 1 and Layer 2 status.
+For example, you can run the following command in order to monitor
+the Layer 1 port statuses for all BRI devices in the real time:
 
   watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info'
 
-For the status of the D channel of the span, see:
+For the status of the D channel of the ports on all BRI spans, run:
 
   watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info'
 
-
-There are a bunch of other status files under /proc/xpp/ .
+There are a bunch of other status files under /proc/xpp/.
 
 
 Zaptel Init Configuration File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The zaptel init.d script, genzaptelconf and the XPD init scripts source 
-the file /etc/init.d/zaptel (on Debian) or /etc/sysconfig/zaptel (on 
-RedHats). A number of useful values for there:
+The zaptel init.d script, genzaptelconf and the XPD init scripts uses the 
+parameters located in file /etc/default/zaptel (on Debian) or 
+/etc/sysconfig/zaptel (on RedHats). There is a number of useful parameters 
+that may be defined there:
 
 -----------------------------------------------------------
 # Lines beginning with '#' are considered comments and ignored.
@@ -635,49 +712,51 @@ lc_country=us
 
 Useful Module Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~
-Compile-time defaults of all modules can be shown as part of the
-description line for the parameter in the output of modinfo.
+Compilation-time defaults for the all modules can be shown as part of the
+description line for the parameter in the "modinfo" command output.
 
-zap_autoreg (xpp)::
+zap_autoreg (xpp):
   Register spans automatically (1) or not (0). Default: 1. 
   Unsetting this could be useful if you have several Astribanks and you 
   want to set their registration order manually using zt_registration in 
   the /proc interface.
 
-initdir (xpp)::
+initdir (xpp):
   This is the directory containing the initialization scripts.
   The default is /usr/share/zaptel .
   Setting this value could be useful if that location is inconvenient for you.
 
-print_dbg (all modules)::
-It will make the driver print tons of debugging messages. Can be sometime 
-even handy, but overly-verbose in the case of xpp_usb. Can be safely 
-set/unset at run-time using /sys/modules .
+print_dbg (all modules):
+  It will make the driver to print tons of debugging messages. You can 
+  set/unset the parameter at run-time.
 
-The value is a bitmask of several values. The value of 0 thus means "no
-debug". The different bits are (as defined in xpp/zap_debug.h) - 
+  The parameter value is a bitmask of several values. The different bits 
+  meaning as it defined in xpp/zap_debug.h: 
 
-  * 1: GENERAL - General debug comments.
-  * 2: PCM - PCM-related messages. Tend to flood logs.
-  * 4: LEDS - Anything related to blinking leds. When they appear, there
-    are many of them.
-  * 8: SYNC - Synchronization messages. Annoy as they happen regularily.
-  * 16: SIGNAL - Zaptel signalling and such.
-  * 32: PROC - procfs interface.
-  * 64: REGS - Reading and writing to regiaters. Tends to flood logs.
+  * 0  - Disable debug messages
+  * 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 - procfs interface related messages.
+  * 64 - REGS - Reading and writing to chip registers. The driver produces
+         a lot of messages when the option is enabled.
 
-Thus: 
+  For example,
 
-  echo 33 >/sys/modules/xpp/parameters/print_dbg 
+    echo 33 >/sys/modules/xpp/parameters/print_dbg 
 
-sets the module xpp to print general debugging messages (1) and procfs
-debuggingmessages (32).
+  forces module xpp to print general debugging messages (1) and procfs
+  debugging messages (32).
 
-vmwineon (xpd_fxs)::
-  Enable (1) or disable (0) sending voicemail message waiting indication
-  to phones with a neon lamp. Disabled by default as it requires extra
-  work of the driver even without such a phone and may potentially have
-  some strange sideeffects with some phones.
+vmwineon (xpd_fxs):
+  Enable (1) or disable (0) sending the voicemail message waiting indication
+  signal to phones equipped with the Message Wainting neon lamp. It is 
+  disabled by default because the feature requires extra work of the driver
+  even when such a phone is not used and also may cause some unusual
+  side effects with some phone models.
 
 usb1 (xpp_usb)::
   Enable (1) or disable (0) support of USB1 devices. Disabled by default.
@@ -685,122 +764,127 @@ usb1 (xpp_usb)::
   +
   USB1 devices are not well-tested. It seems that they don't work at all
   for Astribank BRI. Generally they should work with the current code, but
-  we expect quality issues. Hence we would like to make it very clear that
+  we expect the voice quality issues. Hence we would like to make it very clear that
   you if you have a USB1 port (rather than a USB2 one, as recommended) you
   will have to take an action to enable the device.
 
 poll intervals (various)::
   There are various values which the driver occasionally polls the device
-  for. For instance ,the parameter poll_battery_interval for xpd_fxo
-  to poll the battery (if the telco is actually connected).
+  for. For instance, the parameter poll_battery_interval for xpd_fxo
+  to poll the battery (in order to know if the telco line is actually
+  connected.)
   +
   +
   The value of those parameters is typically a number in milliseconds or 0
   to disable. Under normal operation there should be no reason to play
-  with such parameters.
+  with those parameters.
 
 dtmf_detection (xpd_fxs)::
-  enable (1) or disable (0) support of DTMF detection by the Astribank.
-  Disabled by defualt and curently buggy. On some earlier versions (4372 -
+  enable (1) or disable (0) support of hardware DTMF detection by the Astribank.
+  Disabled by default and currently buggy. On some earlier versions (4372 -
   4415) it was enabled by default, and disabling it there may help.
 
 
-TROUBLSHOOTING
+TROUBLESHOOTING
 --------------
-The following commands provide useful input for debugging:
+The following commands provide useful information for debugging:
 
-* USB level listing: one of the following:
+* Check USB level status. You can use one of the following utilities for it:
 
   zaptel_hardware 
-
+       or
   lsusb | grep e4e4
 
-  - Look for the USB product ID (the second number after e4e4).
-  - If you see *11x2* (e.g: 1152)- the FPGA firmware has been loaded. 
+  - Look for the USB Product ID (the second number after e4e4).
+  - If you see *11x2* (e.g: 1152)- the FPGA firmware has been loaded.
     Move on.
     zaptel_hardware will also show you some more details if the driver
-    is loaded. lsusb will just list the device.
+    is loaded while the lsusb will just list the device.
   - If it shows something as product ID *11x0* - the USB firmware is not
-    loaded. Maybe you need fxload. Or maybe just unplug and replug the
-    device.
-  - If it shows a product ID of *11x1* - only the USB firmware is loaded 
+    loaded. Maybe you need to run fxload. Or maybe just unplug and plug again
+    the device.
+  - If lsusb shows the Product ID as *11x1* - only the USB firmware is loaded 
     and not the FPGA firmware is loaded. If this is still the case after 
     a while - either the firmware loading has failed or you don't have
-    fpga_load - make sure you have libusb-dev(el) installed when
+    fpga_load. Make sure you have libusb-dev(el) installed when
     building Zaptel.
   - It should list all of your Astribank devices. If it doesn't (for
-    more than a temporary while it takes for the initial firmware
-    loading) - Check that the Astribank is indeed connected. 
+    more than period of time needed for the initial firmware
+    loading) - Check that the Astribank is connected indeed.
 
-* Are Astribank spans registered?
+* Check if the Astribank spans are registered in Zaptel
 
   zt_registration
-  
+
   - This should give useful results after the drivers have identified
-    and initialized your devices.
-  - It should list all Astribank XPDs. for each of them it should write
-    "on" or "off". If it is "off", the span has not been registered with
-    Zaptel and thus cannot yet be used.
-  - Registration is normally done as part of `/etc/init.d/zaptel start` .
-    To run it manually use the command:  `zt_registration on` .
-  - Recall that we do not register Astribank spans automaitcally to give
-    you full control on the order of Zaptel spans. See the module
-    parameter **zap_autoreg** above to change that.
-
-* Zaptel-level listing:
-
-  lszaptel
-
-  cat /proc/zaptel/*
-
-  - Those two are almost the same. lszaptel sorts more correctly if you
-    have more than 10 spans, and formats the output slightly nicer.
-  - Here you can see if your Zaptel spans and channels were loaded, if
-    they were configired by ztcfg and if they are in use (typically by
+    and your devices are initialized.
+  - It should list all Astribank XPDs. For each of them it should write
+    "on" or "off". If the registration status is "off", then it means that
+    the span has not been registered in Zaptel and therefore can not be used
+    yet.
+  - Registration is normally done as part of `/etc/init.d/zaptel start`.
+    If you want to register the spans manually, then run command:
+    `zt_registration on` .
+  - Disabling of the automatic Astribank spans registration give you full
+    control on the order of Zaptel spans. See the module parameter
+    **zap_autoreg** for the further details.
+
+* Check the Zaptel information:
+  You can get some information regarding Zaptel channels by running one of the
+  following commands:
+
+    lszaptel
+       or
+    cat /proc/zaptel/*
+
+  - Those two are almost the same. The lszaptel produced more correctly sorted
+    output if you have more than 10 spans, and also make the output listing
+    looks a little bit nicer.
+  - You can see if your Zaptel spans and channels were loaded, if
+    they were configured by ztcfg and if they are in use (typically by
     Asterisk).
-    - The fact that a file for a span is show whos that it has been
-      registered with Zaptel. A n example non-configured channel
-      (Astribank FXS):
+    For example:
+     Not configured Astribank FXS channel will be displayed as:
 
        42 FXS
 
-    - When a channel has been configured with *ztcfg* (that applies
+     When a channel has been configured with *ztcfg* (that applies
       /etc/zaptel.conf), you will see an extra column for the signalling
-      of the channel. The same channel after it has been configured:
+      type of the channel. The same channel after it has been configured:
 
        42 FXS        FXOKS
 
-    - If a program (which is typically asterisk uses it, you'll see:
+     If a program (which is typically Asterisk) uses it, you'll see:
 
        42 FXS        FXOKS      (In use)
 
-* Information from Asterisk
+* Check the Asterisk information:
 
   asterisk -rx 'zap show channels'
 
-  - If you get the error connecting to asterisk.ctl: Asterisk is not
-    running. Maybe it has failed to load. This may be due to
-    misconfigured zapata.conf or whatever reason. Check
-    /var/log/asterisk/messages or /var/log/asterisk/full .
-  - If you get the error that "there is no such command": chan_zap.so is
-    not loaded. This can be one of two cases:
-    - chan_zap.so is not even built. To see that it is available run:
+  - If you get error "Unable to connect to remote asterisk" then it
+    means that the Asterisk is not running. It is possible that Asterisk
+    has failed to start due to misconfigured zapata.conf or whatever reason.
+    Check /var/log/asterisk/messages or /var/log/asterisk/full .
+  - If you get the error that "there is no such command" then it means that
+    chan_zap.so is not loaded. There are two reasons for such problem:
+    (a) chan_zap.so is not even built. Check if the file exists:
+
+         ls -l /usr/lib/asterisk/modules/chan_zap.so
 
-      ls -l /usr/lib/asterisk/modules/chan_zap.so
+    (b) the chan_zap.so file exists but it is not loaded. Try to load it manually:
 
-    - Your Asterisk has chan_zap.so but it is not loaded. Try loading
-      it:
-      
-      asterisk -rx 'load module chan_zap.so'
+         asterisk -rx 'load module chan_zap.so'
 
-  - You see only "pseudo": in this case you have not configured any
+  - You see "pseudo" channel only. It means that you have not configured any
     channels. If you have configured channels in zapata.conf, you may
-    need to restart asterisk (or: `unload chan_zap.so` and 
-    `load chan_zap.so`) to apply those changes.
+    need either to restart the Asterisk or unload/load chan_zap.so manually.
+    You can use the following Asterisk CLI commands for it: `unload chan_zap.so` and 
+    `load chan_zap.so`
 
 
 NOTE: XPP here does not stand for X Printing Panel, XML Pull Parser, 
 X-Windows Phase Plane or XML Professional Publisher. It is simply the 
 Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom 
-Peripheral Device). An XBus (originally XPP Bus) is actually a single
+Peripheral Device). An XBUS (originally XPP Bus) is actually a single
 Astribank device and the XPDs have become the single modules in it.