r1557@boole: tzafrir | 2006-11-06 20:12:16 +0200

 Merging xpp driver release 1.2 (rev. 2569), originally team/tzafrir/xpp_1.2
  * Should build well. Almost final.
  * genzaptelconf: Also work when zap_autoreg=0
  * README.Astribank updated for rev. 1.2.
  * xpp/utils/Makefile: Use $< with cc -c
  * Get xpp/utils configuration from autoconf (without changesin top dir)


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

1 files changed, 240 insertions, 86 deletions

diff --git a/xpp/README.Astribank b/xpp/README.Astribank
index f6f995c..e45bde9 100644
--- a/xpp/README.Astribank
+++ b/xpp/README.Astribank
@@ -9,30 +9,20 @@ installing Zaptel with some additions.
 
 Building drivers:
 """"""""""""""""
-From the toplevel zaptel directory run a command similar to (I used line
-continuation to prevent line wrapping):
-
- $ make \
-        KSRC=/usr/src/kernel-headers-2.6.12-1-386       \
-        KVERS=2.6.12-1-386                              \
-        XPPMOD=xpp/                                     \
-        EC_TYPE=CAN_KB1
-
- - The KSRC= points to a configured kernel source tree.
- - The KVERS= should match the relevant tree version.
- - The XPPMOD= instructs the Zaptel Makefile to descend into the xpp/
-   subdirectory. The slash (/) in the end is mandatory.
- - The EC_TYPE= select the echo canceler.
-
-Building firmware utilities:
-"""""""""""""""""""""""""""
-Then you should compile the firmware loading utilities. Simply go
-to the zaptel/xpp/utils and run make.
-
-Those who don't use prepackaged drivers should make sure they also
-install the (externally available) fxload utility.
-
-Installation:
+Unlike earlier versions, the Astribank driver (xpp) will now build 
+automatically. To build the drivers follow the usual Zaptel
+documentation. E.g: run:
+
+  make
+
+in the top-level directory.
+
+Next you will need to build the user-space tools needed for loading the
+firmware and initialization files for the Astribank:
+
+  make -C xpp/utils
+
+INSTALLATION:
 """"""""""""
 
 apart from the standard 'make install' in the zaptel directory, 
@@ -45,7 +35,7 @@ Alternatively, do the following manually:
 All firmware files should be copied to a new directory:
   /usr/share/zaptel/
 
-The xpp_fxloader and xpp_fxloader.usbmap should be copied to:
+The xpp_fxloader and xpp_fxloader.usermap should be copied to:
  /etc/hotplug/usb/
 
 In addition, the file xpp/xpp_modprobe contains optional modprobe settings.
@@ -55,48 +45,242 @@ It may be copied verbatim into /etc/modprobe.conf or (better) copied to
 
 Note that loading through udev is not yet provided. Run 
 
-  /etc/hotplug/usb/xpp_fxloader xppdetect
+  /etc/hotplug/usb/xpp_fxloader load
 
 to load firmware.
 
+The FXS calibration script requires the perl module Time::HiRes. This
+modules is already packaged for most distributions including Debian, Fedora,
+RedHat and CentOS. To test for the existance of this module run:
+  perl -MTime::HiRes -e ''
 
-Loading Firmware Details:
-""""""""""""""""""""""""
-The Astribank needs a firmware loaded into it. Without the firmware, 
-the device will appear in lsusb with vendor ID 04b4 and product ID 8613
-The firmware is provided in the Intel hex format. It can be loaded using 
-the program fxload, which is typically part of the package 'fxload' or 
-'hotplug-utils' . 
+This should run cleanly (without output) if the module exists and issue
+a long error message otherwise. At least in RedHat, CentOS and Fedora-2
+until Fedora-5 it is in a package named perl-Time-HiRes. In Debian and
+Fedora-6 it is bundled with perl.
 
-To load the firmware automatically using the standard hotplug script, 
-place xpp/utils/xpp_fxloader and xpp/utils/xpp_fxloader.usermap in 
-/etc/hotplug/usb and place xpp/utils/*.hex in /usr/share/zaptel .
 
-Alternatively, xpp_fxloader when given the parameter 'xppdetect' will load 
-the firmwares from /usr/share/zaptel/ . You can use it to load the 
-firmware manually.
+DEVICE STARTUP:
+""""""""""""""
 
-You should then get in lsusb the vendor ID e4e4 and device ID 2121
-(those IDs are temporary and likely to change in upcoming versions). 
-Once there is such a device, the xpp_usb driver should load
-automatically on hot-plugging. In fact, you may find it simpler to
-disconnect and reconnect the device than running 'modprobe xpp_usb'.
+Terminology:
+"""""""""""
+Some technical terms that are used throughout the document and in the
+driver / zaptel . Only used in the technical parts.
 
+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.
 
-The driver has been separated into several modules: xpp.ko, xpd_fxs.ko and 
-xpp_usb.ko . Generally you only need to modprobe xpp_usb, and it should also
-be loaded by hotplug when you connect the Astribank. However in order for it
-to load xpd_fks.ko correctly
+XBUS:
+A funny way to call an Astribank device.
 
-Refer to the instructions for Zaptel. After our small patches were applies, 
-you get xpp.ko which is basically yet another zaptel driver, like wcfxo
-and wctdm.
+XPD:
+This is basically a logical unit of the Astribank. It will be registered to
+Zaptel as a single span. This will basically be 8 analog channels.
+
+
+Loading Firmware:
+""""""""""""""""
+Normally this is done using the script 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
+1132, and the driver can pick it up. You'll also see the top led lit.
+
+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. 
+
+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 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 first is done using the the program fxload. To load it manually, use
+the command:
+
+  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).
+
+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.
+
+
+Firmware Loading with UDEV:
+""""""""""""""""""""""""""
+Firmware loading with udev should work but is not installed 
+automatically, yet. See the comments in the beginning of the script
+/etc/hotplug/usb/xpp_fxloader .
+
+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).
+
+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
+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.
+
+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.
+
+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
+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 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).
+
+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.
+
+
+Device Initializations Scripts:
+""""""""""""""""""""""""""""""
+The chips in the device need to be initialized. This involves 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.
+
+before registering a XPD as a span in Zaptel, we run an initialization
+script: /usr/share/zaptel/initialize_registers . If this fails (e.g:
+because the script is not there, or is not executable), you will get an
+error message in the logs [FIXME: quote error message] 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.
+
+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.
+
+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:
+
+  options xpp zap_autoreg=0
+
+to disable automatic registration at startup. You will then need to
+register the spans manually. 
+
+
+SAMPLE CONFIGURATIONS:
+""""""""""""""""""""""
+
+/etc/zaptel.conf:
+
+  Astribank 8:
+
+    fxoks=1-14
+
+  Astribank 16: 8FXS/8FXO
+
+    fxoks=1-14
+    fksks=15-22
+
+/etc/asterisk/zapata.conf
+
+  Astribank 8:
+   
+    [channels]
+    signalling=fxo_ks
+    ; The real analog ports:
+    context=from-internal
+    ; echocancel=yes
+    ; echocancelwhenbriged=yes
+    ; echotraining=9
+    channel => 1-8
+
+    ; output ports:
+    context=astribank-outputs
+    channel => 9-10
+    ; input ports:
+    immediate=yes
+    context=astribank-inputs
+    channel => 11-14
+    immediate=no
+  
+  Astribank 16: 8FXS/8FXO
+   
+    [channels]
+    signalling=fxo_ks
+    ; The real analog ports:
+    context=from-internal
+    ; echocancel=yes
+    ; echocancelwhenbriged=yes
+    ; echotraining=9
+    channel => 1-8
+
+    ; output ports:
+    context=astribank-outputs
+    channel => 9-10
+    ; input ports:
+    immediate=yes
+    context=astribank-inputs
+    channel => 11-14
+    immediate=no
+
+    ; FXO ports
+    signalling=fxs_ks
+    context=from-pstn
+    callerid=asreceived
+    channel => 15-22
+
+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.
 
 When loaded, you should get one span, of 8 extensions, 2 output ports and 
 4 input ports:
 
   root@rapid:~# cat /proc/zaptel/2 
-  Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS" NOTOPEN 
+  Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS"
 
            1 XPP_FXS/0-0 FXOKS (In use) 
            2 XPP_FXS/0-1 FXOKS (In use) 
@@ -113,36 +297,6 @@ When loaded, you should get one span, of 8 extensions, 2 output ports and
           13 XPP_IN/0-12 FXOKS (In use) 
           14 XPP_IN/0-13 FXOKS (In use) 
 
-For such a simple case you could use:
-
-/etc/zaptel.conf:
-
-fxoks=1-14
-loadzone=us
-tonezone=us
-
-/etc/asterisk/zapata.conf:
-
-[channels]
-group=1
-signalling=fxo_ks
-immediate=no
-
-context=from-internal
-channels => 1-8
-
-; actually they will never generate calls, so the context 
-; here is irrelevant
-;context=outputs
-channels => 9-10
-
-; input ports should get an answer:
-immediate=yes
-context=inputs
-channels => 11-14
-
-;;;;;; end of zapata.conf
-
 
 /proc Interface
 """""""""""""""
@@ -183,10 +337,10 @@ 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.
 
-initialize_registers (xpd_fxs)
-The script that is run to initilize registers of the device. The default is 
-/usr/share/zaptel/initialize_registers . 
-Setting this value could be useful if that location is inconvient for you.
+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