xpp r5151:

  * xpd_pri: Basically ready.
  * PCM synchronization changes:
    - Each Astribank unit ticks independently. Each with its own PLL.
    - HOST synchronization is gone. Loading of xpp will no longer cause
      useless 250 ticks per second if you have no Astribank.
    - Synchronization from the zaptel sync master requires setting
      ZAPTEL as sync source (xpp_sync ZAPTEL).
  * rx_tasklet is now a parameter of the module xpp, rather than of xpp_usb.
  * New FPGA firmware: 5128 (1151) / 5122 (1141, 1131):
    - Fixes synchronization issues.
    - PRI module: E1 should now work.
  * perl module and utilities:
    - Modules no longer magically scan system on initialization.
    - Scanning is by calling explicit methods.
    - "Serial" has been renamed "Label". It is basically unique, but 
      should be modifieble.
    - Some basic documentation of zaptel perl modules.
  * Default sort order of zt_registration is back to SORT_CONNCTOR.
  * zt_registration proc file now shows the number of span registered to 
    if registered. Try: grep . /proc/xpp/XBUS-*/XPD-*/zt_registration
  * genzaptelconf: Allow using a custom command instead of
    /etc/init.d/asterisk to start/stop asterisk.
  * Fixed the typo "Slagish".


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

1 files changed, 552 insertions, 431 deletions

diff --git a/xpp/README.Astribank b/xpp/README.Astribank
index af1c690..6e7cdb2 100644
--- a/xpp/README.Astribank
+++ b/xpp/README.Astribank
@@ -9,6 +9,8 @@ The drivers reside in a separate subdirectory, xpp/ .
 It is generally a more technical document than the 
 http://www.xorcom.com/documentation/manuals/[Astribank User Manual]
 
+An HTML version of the latest version of this document could be found at 
+http://rapid.tzafrir.org.il/docs/README.Astribank.html[]
 
 Building and Installation
 -------------------------
@@ -26,10 +28,6 @@ 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 CentOS/Trixbox).
 
-
-INSTALLATION
-------------
-
 Apart from the standard 'make install' in the zaptel directory, 
 run:
 
@@ -37,23 +35,432 @@ run:
 
 Though this should be done automatically on zaptel >= 1.4.1 .
 
-Alternatively, do the following manually:
 
-All firmware files and scripts should be copied to the new directory:
-  /usr/share/zaptel/
+Sample Configurations
+---------------------
+We generally recommend to generate the configuration by using utility
+genzaptelconf. The following reference configuration will work for a
+system where Astribank devices are used.
 
-xpp_fxloader.usermap should be copied to:
- /etc/hotplug/usb/
 
-Run:
+[[sect-default]]
+Zaptel Init Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
 
-  /usr/share/zaptel/xpp_fxloader load
+-----------------------------------------------------------
+# Lines beginning with '#' are considered comments and ignored.
 
-to load firmware.
+# A two-letter country code. genzaptelconf uses it to better guess 
+# the configuration it generates. E.g: the signalling of E1 spans, and 
+# a few other country-specific settings.
+lc_country=us
 
+# See genzaptelconf(8) and the script itself for a longer list of 
+# variables.
 
-LEDs Indication
+# Equivalent to the parameter opermode to the module wctdm: country-specific
+# settings to the FXO lines. For a complete list of possible values, see
+# /usr/share/zaptel/init_fxo_mode .
+#opermode=FCC
+#opermode=FRANCE
+
+# xpp_sync runs with the value of 'XPP_SYNC' as its parameter to set the
+# synchronization source. The default is 'auto' that selects the best
+# Astribank. 'ZAPTEL' gets synchronization from the Zaptel sync master
+# span. Or a specific xbus number.
+#XPP_SYNC=ZAPTEL
+
+# Disables hotplug firmware loading
+#XPP_HOTPLUG_DISABLED=yes
+#
+
+# Disables udev hook called when an astribank is added and ready
+# or removed.
+#ASTRIBANK_HOOK_DISABLED=yes
+
+# Setup for XPP PRI. This allows to have fixed settings:
+#   1. The variable XPP_PRI_SETUP contains a whitespace separated list of
+#      port specifications.
+#   2. Each port specification contains a match expression, a '=' and
+#      a setting string.
+#   2. Match expressions may be:
+#      - CONNECTOR/usb..../XPD-nn	To identify by physical connector
+#      - NUM/XBUS-mm/XPD-nn		To identify by bus number
+#   4. Match expressions may contain "wildcards" (which are translated
+#      internally to regular expressions):
+#        * matches zero or more characters.
+#        ? matches one charater
+#   5. The list of matches is scanned from beginning to end. First match wins.
+#   6. The list implicitly contains an 'NUM/*=TE,E1' catch all default, appended
+#      to its end.
+#   7. The setting string is composed of comma separated settings. Valid
+#      settings are:
+#      - NT or TE
+#      - E1 or T1 or J1
+#
+#XPP_PRI_SETUP='
+#	CONNECTOR/usb-0000:00:1d.7-1/XPD-01=NT,E1
+#	NUM/*/XPD-03=NT,E1
+#	'
+-----------------------------------------------------------
+
+/etc/zaptel.conf
+~~~~~~~~~~~~~~~~
+
+Astribank 8
+^^^^^^^^^^^
+    fxoks=1-14
+
+Astribank 6FXS/2FXO
+^^^^^^^^^^^^^^^^^^^
+    fxoks=1-12
+    fxsks=13-14
+
+Astribank 16: 8FXS/8FXO
+^^^^^^^^^^^^^^^^^^^^^^^
+    fxoks=1-14
+    fxsks=15-22
+
+Astribank 4 BRI
+^^^^^^^^^^^^^^^
+    # Assumed ports settings:
+    # Ports 1,3: TE
+    # Ports 2,4: NT
+    span=1,1,1,ccs,ami
+    span=2,0,1,ccs,ami
+    span=3,2,1,ccs,ami
+    span=4,0,1,ccs,ami
+    bchan=1-2
+    dchan=3
+    bchan=4-5
+    dchan=6
+    bchan=7-8
+    dchan=9
+    bchan=10-11
+    dchan=12
+  
+
+/etc/asterisk/zapata.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Astribank 8
+^^^^^^^^^^^   
+    [channels]
+    signalling=fxo_ks
+    ; The real analog ports:
+    context=from-internal
+    echocancel=yes
+    ; echocancelwhenbriged=yes
+    ; echotraining=no
+    channel => 1-8
+
+    ; output ports:
+    context=astbank-output
+    channel => 9-10
+    ; input ports:
+    immediate=yes
+    context=astbank-input
+    channel => 11-14
+    immediate=no
+
+Astribank 6FXS/2FXO
+^^^^^^^^^^^^^^^^^^^   
+    [channels]
+    signalling=fxo_ks
+    ; The real analog ports:
+    context=from-internal
+    echocancel=yes
+    ; echocancelwhenbriged=yes
+    ; echotraining=no
+    channel => 1-6
+
+    ; output ports:
+    context=astbank-output
+    channel => 7-8
+    ; input ports:
+    immediate=yes
+    context=astbank-input
+    channel => 9-12
+    immediate=no
+
+    ; FXO ports
+    signalling=fxs_ks
+    context=from-pstn
+    callerid=asreceived
+    channel => 13-14
+
+Astribank 16: 8FXS/8FXO
+^^^^^^^^^^^^^^^^^^^^^^^   
+    [channels]
+    signalling=fxo_ks
+    ; The real analog ports:
+    context=from-internal
+    echocancel=yes
+    ; echocancelwhenbriged=yes
+    ; echotraining=no
+    channel => 1-8
+
+    ; output ports:
+    context=astbank-output
+    channel => 9-10
+    ; input ports:
+    immediate=yes
+    context=astbank-input
+    channel => 11-14
+    immediate=no
+
+    ; FXO ports
+    signalling=fxs_ks
+    context=from-pstn
+    callerid=asreceived
+    channel => 15-22
+
+Astribank 4 BRI
+^^^^^^^^^^^^^^^    
+    ; Assumed ports settings:
+    ; Ports 1,3: TE
+    ; Ports 2,4: NT
+    [channels]
+    switchtype = euroisdn
+    callerid = asreceived
+    
+    ; TE ports:
+    signalling = bri_cpe_ptmp
+    ;signalling = bri_cpe
+    context = from-pstn
+    group = 1,11
+    channel => 1,2
+    
+    group = 1,13
+    channel => 7,8
+    
+    ; NT ports:
+    signalling = bri_net_ptmp
+    ;signalling = bri_net
+    context = from-internal
+    group = 2,12
+    channel => 4,5
+    
+    group = 2,14
+    channel => 10,11
+
+
+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:
+
+  root@rapid:~# cat /proc/zaptel/* 
+ Span 1: XBUS-00/XPD-00 "Xorcom XPD #00/00: 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)
+
+
+
+/etc/asterisk/extensions.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sample dialplan (extensions.conf) for all the above:
+
+-----------------------------------------------------------
+[phones-zap]
+; 6001 will dial to channel 1, 6020, to zaptel channel 20, etc.
+exten => _6XXX,1,Dial(ZAP/${EXTEN:1})
+; Useful for debugging trunks. Will potentially allow users to
+; bypass context limitations.
+;exten => _6XXX.,1,Dial(ZAP/${EXTEN:1:3}/${EXTEN:4})
+
+[trunk]
+; A number that begins with 9: dial it through a trunk
+; (we put FXO channels and TE channels in group 0).
+; The leading 9 is stripped.
+exten => _9.,1,Dial(Zap/g0/${EXTEN:1})
+; dialing a number that begins with 83 will dial it through
+; span 3, and so forth. The two leading digits are stripped.
+; (Each digital span is also added to group 10+span number).
+exten => _8X.,1,Dial(Zap/g1${EXTEN:1:1}/${EXTEN:2})
+
+[from-internal] 
+; The context of FXS ports: analog phones.
+; They are allowed to dial to all other phones 
+include => phones-zap 
+; They are also allowed to call through the trunk: 
+include => trunk
+; some simple tests:
+include => astbank-test
+
+[from-pstn] 
+; Calls from the PSTN enter here. Redirect calls to an IVR 
+; or a default extension in the s context here. In this case we  
+; redirect calls to Zaptel channel 1: 
+exten => s,1,Dial(Zap/1) 
+
+; Alternatively, the following will redirect you to the demo IVR 
+; from the sample extensions.conf of Asterisk:
+include => demo
+
+; An extra context with some simple tests
+[astbank-test]
+; 200: echo test
+exten => 200,1,Answer
+exten => 200,n,Wait(1)
+exten => 200,n,Echo()
+exten => 200,n,Hangup
+
+; 203: say extension number. Will only work if caller ID 
+; is properly set in zapata.conf / zapata-channels.conf
+exten => 203,1,Answer
+exten => 203,n,Wait(1)
+exten => 203,n,SayNumber(${CALLERID(num)})
+exten => 203,n,Hangup
+
+[astbank-input] 
+exten => s,1,Set(ZAP_CHAN=${CUT(CHANNEL,-,1)}) 
+exten => s,n,Set(ZAP_CHAN=${CUT(ZAP_CHAN,/,2)}) 
+; 11 is the number of the first input port. At least in the sample 
+; configuration below. 
+;exten => s,n,Set(INPUT_NUM=$[${ZAP_CHAN}-11)]) 
+; The sample below just logs the signal.  
+exten => s,n,NoOp(Got signal from Zaptel Channel ${ZAP_CHAN}) 
+; Alternatively: 
+;exten => s,n,System(run something) 
+
+; No. We did not forget the context astbank-outputs. Output 
+; ports only get calls from the PBX. Thus they don't need a context 
+; of their own. Sending them to a context of their on makes 
+; 'zap show channels' in the CLI provide useful display, though.
+-----------------------------------------------------------
+
+
+Troubleshhoting
 ---------------
+The following commands provide useful information for debugging:
+
+* 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.
+    Move on.
+    zaptel_hardware will also show you some more details if the driver
+    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 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
+    building Zaptel.
+  - It should list all of your Astribank devices. If it doesn't (for
+    more than period of time needed for the initial firmware
+    loading) - Check that the Astribank is connected indeed.
+
+* Check if the Astribank spans are registered in Zaptel
+
+  zt_registration
+
+  - This should give useful results after the drivers have identified
+    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).
+    For example:
+     Not configured Astribank FXS channel will be displayed as:
+
+       42 FXS
+
+     When a channel has been configured with *ztcfg* (that applies
+      /etc/zaptel.conf), you will see an extra column for the signalling
+      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:
+
+       42 FXS        FXOKS      (In use)
+
+* Check the Asterisk information:
+
+  asterisk -rx 'zap show channels'
+
+  - 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
+
+    (b) the chan_zap.so file exists but it is not loaded. Try to load it manually:
+
+         asterisk -rx 'load module chan_zap.so'
+
+  - 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 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`
+
+
+Reference
+---------
+LEDs Indication
+~~~~~~~~~~~~~~~
 The Astribank has 4 global indication leds and one or two per-port leds.
 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
@@ -89,13 +496,13 @@ 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
-~~~~~~~~~~~
+^^^^^^^^^^^
 There are some technical terms that are used in this document and in the
 driver / zaptel.
 
@@ -116,7 +523,7 @@ 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 Vendor ID and Product ID of the Astribank
@@ -175,7 +582,7 @@ incremented by 1.
 
 
 Firmware Loading with Hotplug
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 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 
@@ -203,7 +610,7 @@ firmware the device will re-enumerate itself and thus "unplug" and
 
 
 Firmware Loading with UDEV
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 The UDEV framework has replaced Hotplug in most recent systems. If you
 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.
@@ -224,7 +631,7 @@ second time for FPGA firmware loading.
 
 
 Firmware Resetting
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 Newer versions of the USB firmware can now be reset using 'fpga_load -r'.
 
 Also you can try the following:
@@ -238,7 +645,7 @@ Also you can try the following:
 
 
 Loading The Modules
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 Here is what should happen:
 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.
@@ -256,8 +663,10 @@ Now to the ugly details:
 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_fxs - the module for controlling FXS modules.
+* xpd_fxo - the module for controlling FXO modules. 
+* xpd_bri - the module for controlling BRI modules. 
+* xpd_pri - the module for controlling E1/T1 modules. 
 * xpd_usb - the module that holds the functionality needed to connect to the
             USB bus.
 
@@ -280,13 +689,11 @@ When command 'modprobe xpp_usb' returns, the span type specific modules
 
 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.
+the required xpd_* modules. 
 
 
 Device Initializations Scripts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 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
 hardwriting those values in the driver code is not a good idea.
@@ -310,7 +717,7 @@ 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,
@@ -348,7 +755,7 @@ parameter zap_autoreg in the modprobe configuration file (A file under
 
 
 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
@@ -372,359 +779,176 @@ 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:
-
-
-
-SAMPLE CONFIGURATIONS
----------------------
-We generally recommend to generate the configuration by using utility
-genzaptelconf. The following reference configuration will work for a
-system where Astribank devices are used.
+"Sample Configurations" section.
 
-/etc/zaptel.conf
-~~~~~~~~~~~~~~~~
 
-Astribank 8
-^^^^^^^^^^^
-    fxoks=1-14
-
-Astribank 6FXS/2FXO
-^^^^^^^^^^^^^^^^^^^
-    fxoks=1-12
-    fxsks=13-14
-
-Astribank 16: 8FXS/8FXO
-^^^^^^^^^^^^^^^^^^^^^^^
-    fxoks=1-14
-    fxsks=15-22
-
-Astribank 4 BRI
-^^^^^^^^^^^^^^^
-    # Assumed ports settings:
-    # Ports 1,3: TE
-    # Ports 2,4: NT
-    span=1,1,1,ccs,ami
-    span=2,0,1,ccs,ami
-    span=3,2,1,ccs,ami
-    span=4,0,1,ccs,ami
-    bchan=1-2
-    dchan=3
-    bchan=4-5
-    dchan=6
-    bchan=7-8
-    dchan=9
-    bchan=10-11
-    dchan=12
-  
-
-/etc/asterisk/zapata.conf
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Astribank 8
-^^^^^^^^^^^   
-    [channels]
-    signalling=fxo_ks
-    ; The real analog ports:
-    context=from-internal
-    echocancel=yes
-    ; echocancelwhenbriged=yes
-    ; echotraining=no
-    channel => 1-8
-
-    ; output ports:
-    context=astbank-output
-    channel => 9-10
-    ; input ports:
-    immediate=yes
-    context=astbank-input
-    channel => 11-14
-    immediate=no
-
-Astribank 6FXS/2FXO
-^^^^^^^^^^^^^^^^^^^   
-    [channels]
-    signalling=fxo_ks
-    ; The real analog ports:
-    context=from-internal
-    echocancel=yes
-    ; echocancelwhenbriged=yes
-    ; echotraining=no
-    channel => 1-6
-
-    ; output ports:
-    context=astbank-output
-    channel => 7-8
-    ; input ports:
-    immediate=yes
-    context=astbank-input
-    channel => 9-12
-    immediate=no
-
-    ; FXO ports
-    signalling=fxs_ks
-    context=from-pstn
-    callerid=asreceived
-    channel => 13-14
-
-Astribank 16: 8FXS/8FXO
-^^^^^^^^^^^^^^^^^^^^^^^   
-    [channels]
-    signalling=fxo_ks
-    ; The real analog ports:
-    context=from-internal
-    echocancel=yes
-    ; echocancelwhenbriged=yes
-    ; echotraining=no
-    channel => 1-8
+/proc Interface
+~~~~~~~~~~~~~~~
+The Astribank drivers provide their own /proc interface under /proc/xpp.
+(Note that the details of this interface are still potentially subject to 
+changes)
 
-    ; output ports:
-    context=astbank-output
-    channel => 9-10
-    ; input ports:
-    immediate=yes
-    context=astbank-input
-    channel => 11-14
-    immediate=no
+/proc/xpp/xbuses
+^^^^^^^^^^^^^^^^
+File /proc/xpp/xbuses lists the connected Astribank devices (one line 
+per device).
 
-    ; FXO ports
-    signalling=fxs_ks
-    context=from-pstn
-    callerid=asreceived
-    channel => 15-22
+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.
 
-Astribank 4 BRI
-^^^^^^^^^^^^^^^    
-    ; Assumed ports settings:
-    ; Ports 1,3: TE
-    ; Ports 2,4: NT
-    [channels]
-    switchtype = euroisdn
-    callerid = asreceived
-    
-    ; TE ports:
-    signalling = bri_cpe_ptmp
-    ;signalling = bri_cpe
-    context = from-pstn
-    group = 1,11
-    channel => 1,2
-    
-    group = 1,13
-    channel => 7,8
-    
-    ; NT ports:
-    signalling = bri_net_ptmp
-    ;signalling = bri_net
-    context = from-internal
-    group = 2,12
-    channel => 4,5
-    
-    group = 2,14
-    channel => 10,11
+/proc/xpp/sync
+^^^^^^^^^^^^^^
+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
 
+Possible values are:
 
-Please check, that the mailbox and callerid parameters generated by
-genzaptelconf are good for you and change them if necessary.
+<number>::
+  Make the Astribank XBUS-<number> the sync source for other Astribanks.
 
+ZAPTEL::
+  Make the astribanks synchronize with the Zaptel timing master span.
+  You probably ned this to get faxes from a non-Astribank adapter to an
+  Astribank.
 
-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:
+Though you'll normally use xpp_sync(8) for that.
 
-  root@rapid:~# cat /proc/zaptel/* 
- Span 1: XBUS-00/XPD-00 "Xorcom XPD #00/00: FXS"
+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.
 
-           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)
+/proc/xpp/XBUS-nn/XPD-mm/zt_registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+is a read/write file. Reading from it gives 0 if the span is
+unregistered, or the span number if it is registered.
 
+Writing to it allows manual registration / unregistration from Zaptel:
+writing 1 registers a span (if it wasn't already registered) and writing
+0 attempts to unregister it (if it is registered.  Span unregistration 
+will fail if some channels from the span are used  (e.g: by Asterisk).
 
-Sample dialplan (extensions.conf) for all the above:
+A more convient interface to this is the command zt_registration that
+registers or unregisters all the spans at once with a predefined order,
+and this is what you should normally use.
 
------------------------------------------------------------
-[phones-zap]
-; 6001 will dial to channel 1, 6020, to zaptel channel 20, etc.
-exten => _6XXX,1,Dial(ZAP/${EXTEN:1})
-; Useful for debugging trunks. Will potentially allow users to
-; bypass context limitations.
-;exten => _6XXX.,1,Dial(ZAP/${EXTEN:1:3}/${EXTEN:4})
+Alternatively you can use the parameter zap_autoreg to register spans
+automatically. But this is only recommended on a system with a single
+Astribank and no other Zaptel device.
 
-[trunk]
-; A number that begins with 9: dial it through a trunk
-; (we put FXO channels and TE channels in group 0).
-; The leading 9 is stripped.
-exten => _9.,1,Dial(Zap/g0/${EXTEN:1})
-; dialing a number that begins with 83 will dial it through
-; span 3, and so forth. The two leading digits are stripped.
-; (Each digital span is also added to group 10+span number).
-exten => _8X.,1,Dial(Zap/g1${EXTEN:1:1}/${EXTEN:2})
 
-[from-internal] 
-; The context of FXS ports: analog phones.
-; They are allowed to dial to all other phones 
-include => phones-zap 
-; They are also allowed to call through the trunk: 
-include => trunk
-; some simple tests:
-include => astbank-test
+/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:
 
-[from-pstn] 
-; Calls from the PSTN enter here. Redirect calls to an IVR 
-; or a default extension in the s context here. In this case we  
-; redirect calls to Zaptel channel 1: 
-exten => s,1,Dial(Zap/1) 
+  watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary
 
-; Alternatively, the following will redirect you to the demo IVR 
-; from the sample extensions.conf of Asterisk:
-include => demo
 
-; An extra context with some simple tests
-[astbank-test]
-; 200: echo test
-exten => 200,1,Answer
-exten => 200,n,Wait(1)
-exten => 200,n,Echo()
-exten => 200,n,Hangup
+/proc/xpp/XBUS-nn/XPD-mm/slics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Provides direct read/write interface to the registers of each chip. 
+Reading from the file shows the result of the last read request. To make
+either a read request or a write request you need to write to that file.
 
-; 203: say extension number. Will only work if caller ID 
-; is properly set in zapata.conf / zapata-channels.conf
-exten => 203,1,Answer
-exten => 203,n,Wait(1)
-exten => 203,n,SayNumber(${CALLERID(num)})
-exten => 203,n,Hangup
+It is mainly used by the initialization scripts (card_init_*).
 
-[astbank-input] 
-exten => s,1,Set(ZAP_CHAN=${CUT(CHANNEL,-,1)}) 
-exten => s,n,Set(ZAP_CHAN=${CUT(ZAP_CHAN,/,2)}) 
-; 11 is the number of the first input port. At least in the sample 
-; configuration below. 
-;exten => s,n,Set(INPUT_NUM=$[${ZAP_CHAN}-11)]) 
-; The sample below just logs the signal.  
-exten => s,n,NoOp(Got signal from Zaptel Channel ${ZAP_CHAN}) 
-; Alternatively: 
-;exten => s,n,System(run something) 
 
-; No. We did not forget the context astbank-outputs. Output 
-; ports only get calls from the PBX. Thus they don't need a context 
-; of their own. Sending them to a context of their on makes 
-; 'zap show channels' in the CLI provide useful display, though.
------------------------------------------------------------
+/proc/xpp/XBUS-nn/XPD-mm/fxo_info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Only for FXO modules. Apart from showing the status of the LEDs, it also
+shows for each FXO port if it is connected to a provider: look for the
+value of "battery" for that specific port.
 
 
-/proc Interface
----------------
-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/XBUS-nn/XPD-mm/bri_info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In addition to the usual information about the LEDs, this file also
+provides 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:
 
-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.
+  watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info'
 
-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.
+For the status of the D channel of the ports on all BRI spans, run:
 
-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.
+  watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info'
 
-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).
-You can register or unregister particular span manually by writing 1 or 0
-and unregistration is by writing 0 to the file.
 
-File /proc/xpp/XBUS-nn/XPD-mm/summary contains detailed information 
-about port statuses of the device module (off-hook, on-hook etc.)
+/proc/xpp/XBUS-nn/XPD-mm/pri_info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In addition to the usual information about the LEDs, this file also
+provides useful information regarding ISDN Layer 1 and Layer 2 status.
 For example, you can run the following command in order to monitor
-the port statuses in the real time:
+the Layer 1 port statuses for all E1/T1 devices in the real time:
 
-watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary
+  watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/pri_info'
 
-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 status of the D channel of the ports on all PRI spans, run:
 
-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'
+  watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/pri_info'
 
-For the status of the D channel of the ports on all BRI spans, run:
+Note: the layer 2 status is much more of a guesswork based on changes in
+the contents of the channel that is supposed to be the D channel.
 
-  watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info'
+Writing to this file can be used to change the type of the device. The
+device type can only be changed when the XPD is not registered as a
+Zaptel span. The value is a whitespace-separated list of values that can 
+be of:
 
-There are a bunch of other status files under /proc/xpp/.
+E1::
+  Provides 31 channels, of which channel 16 is normally the D-channel. 
+  Common in places outside of North America and Japan. This is the 
+  default setup.
 
+T1::
+  T1 provides 24 channels. The last one is normally the D-Channel.
+  Common in North America.
 
-Zaptel Init Configuration File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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:
+TE::
+  Use the bottom port (green LED) and don't invert any wiring. Hint to
+  higher layers that this will be the TE side of the connection. This is
+  the default setup.
 
------------------------------------------------------------
-# Lines beginning with '#' are considered comments and ignored.
+NT::
+  Use the top port (orange LED) and invert wiring (this is done to allow
+  connecting an NT port and a TE port using a standard straight 8 wires 
+  "ethernet" cable). Hint to higher layers that this will be the NT side 
+  of the connection.
 
-# A two-letter country code. genzaptelconf uses it to better guess 
-# the configuration it generates. E.g: the signalling of E1 spans, and 
-# a few other country-specific settings.
-lc_country=us
+Normally those are set by the PRI initialization script . See the
+definition of XPP_PRI_SETUP in xref:sect-default[the sample Zaptel init
+configuration file] .
 
-# See genzaptelconf(8) and the script itself for a longer list of 
-# variables.
+There are a bunch of other status files under /proc/xpp/.
 
-# Equivalent to the parameter opermode to the module wctdm: country-specific
-# settings to the FXO lines. For a complete list of possible values, see
-# /usr/share/zaptel/init_fxo_mode .
-#opermode=FCC
-#opermode=FRANCE
------------------------------------------------------------
 
 Useful Module Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~
 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):
-  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.
+zap_autoreg (xpp)::
+  Register spans automatically (1) or not (0). Default: 0. 
+  Setting it simplifies operations with a single Astribank and no other 
+  zaptel hardware. However if you have such systems, automatic
+  registration can cause the order of spans to be unpredictable.
+  The standard startup scripts use 'zt_registration on' instead of this.
 
-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):
+rx_tasklet (xpp)::
+  Enable (1) or disable (0) doing most of the packets processing in
+  separate tasklets. This should probably help on higher-end systes with
+  multiple Astribanks.
+
+print_dbg (all modules)::
   It will make the driver to print tons of debugging messages. You can 
   set/unset the parameter at run-time.
 
@@ -749,7 +973,7 @@ print_dbg (all modules):
   forces module xpp to print general debugging messages (1) and procfs
   debugging messages (32).
 
-vmwineon (xpd_fxs):
+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
@@ -781,109 +1005,6 @@ dtmf_detection (xpd_fxs)::
   Enable (1) or disable (0) support of hardware DTMF detection by the 
   Astribank.
 
-rx_tasklet (xpp_usb)::
-  Enable (1) or disable (0) doing most of the packets processing in
-  separate tasklets. This should probably help on higher-end systes with
-  multiple Astribanks.
-
-
-TROUBLESHOOTING
---------------
-The following commands provide useful information for debugging:
-
-* 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.
-    Move on.
-    zaptel_hardware will also show you some more details if the driver
-    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 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
-    building Zaptel.
-  - It should list all of your Astribank devices. If it doesn't (for
-    more than period of time needed for the initial firmware
-    loading) - Check that the Astribank is connected indeed.
-
-* Check if the Astribank spans are registered in Zaptel
-
-  zt_registration
-
-  - This should give useful results after the drivers have identified
-    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).
-    For example:
-     Not configured Astribank FXS channel will be displayed as:
-
-       42 FXS
-
-     When a channel has been configured with *ztcfg* (that applies
-      /etc/zaptel.conf), you will see an extra column for the signalling
-      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:
-
-       42 FXS        FXOKS      (In use)
-
-* Check the Asterisk information:
-
-  asterisk -rx 'zap show channels'
-
-  - 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
-
-    (b) the chan_zap.so file exists but it is not loaded. Try to load it manually:
-
-         asterisk -rx 'load module chan_zap.so'
-
-  - 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 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