xpp.r5512:

* Build:
  - Zaptel >= 1.4.9 is migrating to storing kernel stuff in zaptel/kernel/*
  -  We conditionally use old/new directory scheme:
     In xpp/Kbuild and xpp/utils/Makefile use ZAP_KERNEL variable, so it's
     not confused with ZAPTEL_DIR (which appears in zaptel/Makefile as well).
  - Fix compile warnings on 64 bit systems.
  - Compile fixes for kernel-2.6.24
* UDEV:
  - /etc/udev/rules.d/xpp.rules now uses XPP_INIT_DIR to find astribank_hook.
  - astribank_hook: Modify to do nothing. Add some documentation.
* Autoconfiguration -- zapconf:
  - Don't fail zapconf et.al. if no config file was found.
  - Skip the 'IRQ Missing:' line in /proc/zaptel/nnn for wcte1xp(?).
  - Add some newer Digium cards to our hardware inventory.
  - Partially handle cases where the /proc/zaptel strings does not contain
    info about E1/T1/J1 or NT/TE.
* Better SYNC:
  - Finer tuning of PLL (New firmware).
  - Change calculation algorithm of sync offset. It now copes better
    with the variance in USB frame reception timing.
  - Statistics:
    . The view of results was moved from /proc/xpp/XBUS-*/summary to
      a new /sys/bus/astribanks/devices/xbus-*/timing and enhanced.
    . A new xpp_timing script shows all astribanks.
    . A new write only /sys/bus/astribanks/devices/xbus-*/cls is
      used to clear statistics. Eventually, clearing of XBUS related
      statistics should be done here. One that was migrated is the
      clearing of 'PCM [TR]X:' numbers currently appearing in
      /proc/xpp/XBUS-*/summary (they should be moved too later).
  - Shorten the strings representation sync_mode ("SYNC_MODE_AB" -> "AB")
    adapted their use in printk and /proc so the text is clear.
  - Added a command line parameter xpp.disable_pll_sync to stop all
    adjustments command to AB (calculations still continue as usual).
* PRI:
  - 4 port support
  - set clocking master span via ztcfg, like other zaptel devices.
* FXO:
  - Fix false hangups in some countries (voltage fluctuations).
  - Some countries send caller-id before first ring.
    Added code to handle caller-id PCM pass through according to
    a new command line parameter (xpd_fxo.caller_id_style).
  - No longer sends an event on zt_open. See #12160 .
* Misc:
  - Adapt to zaptel-1.4.8 and above ztscan: added fields returend by
    new ZT_SPANSTAT_V2 ioctl()
  - Document sysfs and waitfor_xpds.
  - Miscelaneous optimizations and bugfixes.
  - Remove deprecated pcm_tasklet parameter. The rx_tasklet parameter has
    replaced it a long time ago.
  - Add RX_CMD counter to /proc/xpp/XBUS-*/summary
  - Unclutter some of the usb disconnect messages.
  - xpp_usb: minor preformance improvements in receive.
    Expose the number of pending receive URB's in /proc/xpp/XBUS-*/xpp_usb

Merged revisions 3952 via svnmerge from 
http://svn.digium.com/svn/zaptel/branches/1.2


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

1 files changed, 216 insertions, 87 deletions

diff --git a/kernel/xpp/README.Astribank b/kernel/xpp/README.Astribank
index 342c6a9..183cd76 100644
--- a/kernel/xpp/README.Astribank
+++ b/kernel/xpp/README.Astribank
@@ -4,7 +4,7 @@ Xorcom Team <support@xorcom.com>
 $Revision$, $Date$
 
 This file documents the Zaptel drivers for the Xorcom Channel Bank.
-The drivers reside in a separate subdirectory, xpp/ .
+The drivers reside in a separate subdirectory, kernel/xpp/ .
 
 It is generally a more technical document than the 
 http://www.xorcom.com/documentation/manuals/[Astribank User Manual]
@@ -19,6 +19,10 @@ installing Zaptel with some additions.
 
 Building drivers
 ~~~~~~~~~~~~~~~~
+Apart from the standard Zaptel build requirements, you also need libusb
+development headers to build the fpga_load firmware loader. This is
+typically the package libusb-dev or libusb-devel .
+
 On zaptel 1.2 you will need to run the following extra step to build the
 Astribank drivers, apart from the standard 'make':
 
@@ -53,7 +57,7 @@ NT::
 
 The value XPP_PRI_SETUP in the init configuration file (see example
 below) can be used to change those defaults. This value is a
-whitelist-separated list of conditions. When a port is initialized it 
+whitespace-separated list of conditions. When a port is initialized it 
 checks those conditions and uses the firs one that matches.
 
 Match expressions may be:
@@ -61,6 +65,7 @@ Match expressions may be:
 - NUM/XBUS-mm/XPD-nn		To identify by bus number
 
 Match expressions may contain "wildcards":
+
 - * matches zero or more characters.
 - ? matches one charater
 - [xyz] - any of 'x', 'y', or 'z'.
@@ -458,98 +463,182 @@ Troubleshhoting
 ---------------
 The following commands provide useful information for debugging:
 
-* Check USB level status. You can use one of the following utilities for it:
+lsusb Test
+~~~~~~~~~~
+Check USB level status. You can use one of the following utilities for it:
 
   zaptel_hardware -v
        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. Also make sure that you have fxload installed.
-  - 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
+- 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. Also make sure that you have fxload installed.
+- 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. After you have installed it, you may need to re-run
+  ./configure .
+- 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.
+
+
+Zaptel Registration
+~~~~~~~~~~~~~~~~~~~
+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:
+- 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.
+
+
+Zaptel Level 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:
+- 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
 
-       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:
 
-     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
 
-       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)
 
-       42 FXS        FXOKS      (In use)
 
-* Check the Asterisk information:
 
+Asterisk Level 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:
+- 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:
+  * chan_zap.so is not even built. Check if the file exists:
+
+       ls -l /usr/lib/asterisk/modules/chan_zap.so
+
+  * 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`
+
+
+Known Issues
+~~~~~~~~~~~~
+Empty /proc dir
+^^^^^^^^^^^^^^^
+.Symptoms:
+- Error message:
+
+  "ERR-xpd_fxo: XBUS-00/XPD-00: Failed initializing registers (-22)"
+  
+- Likewise for all XPDs. 
+- The directory /proc/xpp exists but is empty (not even the files 
+  'xbuses' and 'sync').
+
+.Cause:
+The driver failed to recreate the procfs directory /proc/xpp and hence
+everything under it. This is because it has already existed. And it
+existed because a process still uses it. This is typically because you
+have a shell whose working directory is /proc/xpp or somewhere under
+it:
+
+  # lsof /proc/xpp
+  COMMAND  PID USER   FD   TYPE DEVICE SIZE       NODE NAME
+  bash    2741 root  cwd    DIR    0,3    0 4026532684 /proc/xpp
+
+.Fix:
+Move that process from that directory, or close the file it uses from
+under /proc/xpp and reload the zaptel / xpp drivers.
 
-         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:
+Bad Firmware Version
+^^^^^^^^^^^^^^^^^^^^
+.Symptoms:
+- An Astribank finishes initialization quickly, the /proc/XBUS-nn
+  directory has no XPD-mm subdirectories.
+- Error in the kernel logs about:
 
-         asterisk -rx 'load module chan_zap.so'
+  NOTICE-xpp: XBUS-00: XPD at 00: type=6.0 has bad firmware revision 2.6 
 
-  - 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`
+.Cause:
+This is normally caused by an Astribank with an older firmware connected
+to a 
+
+The protocol version supported by the firmware will typically be the same 
+one as in the device initialization scripts installed to 
+/usr/share/zaptel . Hence if this version installed 
+`/usr/share/zaptel/init_card_3_29` it will probably include firmware of 
+protocol version 29.
+
+.Fix:
+Reset the firmware:
+
+  /usr/share/zaptel/xpp_fxloader reset
+
+Or disconnect the Astribank and reocnnect. On some older versions of the
+USB firmware resetting the firmware (or any operation of fpga_load)
+would fail if the driver is loaded. Hence you would need to run 
+`rmmod xpp_usb` . In the end, reload the drivers.
+
+
+USB Errors at Shutdown
+^^^^^^^^^^^^^^^^^^^^^^
+.Symptoms:
+You see USB-related errors similar to the following whenever you shut
+down the drivers of the Astribank or disconnect its drivers:
+
+  ERR-xpp_usb: XBUS-00: Failed to submit a receive urb
+
+.Cause:
+This is a normal part of the shutdown of the USB connection. 
+
+.Fix:
+Ignore them. Unless the USB should not have disconnected at that time.
 
 
 Reference
@@ -756,6 +845,7 @@ m may be another number: 0, 1 ,etc).
 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 modules.
@@ -782,9 +872,10 @@ the module.
 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 about type of telephony modules
-it has. According to the answers it receives, the xpp driver will "modprobe"
-the required xpd_* modules. 
+At this point the xpp driver "asks" the box about its software
+(firmware) version) and the type of telephony modules it has. According 
+to the answers it receives, the xpp driver will "modprobe" the required 
+xpd_* modules. 
 
 
 Device Initializations Scripts
@@ -799,6 +890,9 @@ 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
 
+Those scripts must be executable. Funny things happen if such a script
+exists but is not executable.
+
 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
@@ -811,20 +905,6 @@ faster "blinking" when the XPDs register as Zaptel spans. The initializaton
 of an FXS XPD may take a few seconds.
 
 
-Astribank in Sysfs
-^^^^^^^^^^^^^^^^^^
-When an Astribank device loads it generates a device node in the bus 
-'astribanks' in sysfs. You can see a directory for each device under 
-/sys/bus/astribanks/devices/ and under it there are several attributes
-for each Astribank (such as its connector string).
-
-On each time an Astribank is initialized or destroyed a udev event is
-generated. The rules from our sample udev rules file (xpp/utils/xpp.rules) 
-make that event run the script /usr/share/zaptel/astribank_hook with the
-parameter 'add' or 'remove', if such script exists. An example script
-that just adjusts the Astribank sync settings is included in xpp/utils. 
-
-
 Registering in Zaptel
 ^^^^^^^^^^^^^^^^^^^^^
 The XPDs will not automatically register as zaptel spans. This is
@@ -894,8 +974,13 @@ Alternatively, write you own configuration, based on the sample from the
 /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)
+Here we review the more useful details of the procfs interface. There
+are many other debugging details that are exposed through the debugfs
+interface. 
+
+Also note that those details are subject to changes. Generally the
+recommended stable interface are the zaptel-perl utilities from the
+xpp/utils directory.
 
 
 /proc/xpp/xbuses
@@ -931,6 +1016,17 @@ 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/waitfor_xpds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Reading from this file only returns when the Astribank has finished
+initialization of the XPDs or in case of a timeout. It prints the number
+of XPDs to initialize, and the number initialize. Unless something went
+wrong, those two numbers are the same. Once the span was initialized,
+reading from this file returns immediately:
+
+  XPDS_READY: XBUS-00: 3/3
+
+
 /proc/xpp/XBUS-nn/XPD-mm/zt_registration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 is a read/write file. Reading from it gives 0 if the span is
@@ -1044,6 +1140,39 @@ configuration file] .
 There are a bunch of other status files under /proc/xpp/.
 
 
+/sys Interface
+~~~~~~~~~~~~~~~
+When an Astribank device loads it generates a device node in the bus 
+'astribanks' in sysfs. You can see a directory for each device under 
+/sys/bus/astribanks/devices/ and under it there are several attributes
+for each Astribank (such as its connector string).
+
+On each time an Astribank is initialized or destroyed a udev event is
+generated. The rules from our sample udev rules file (xpp/utils/xpp.rules) 
+make that event run the script /usr/share/zaptel/astribank_hook with the
+parameter 'add' or 'remove', if such script exists. An example script
+that just adjusts the Astribank sync settings is included in xpp/utils. 
+
+cls::
+  CLear Statistics: writing to this file clear the procfs statistics for
+  this bus.
+
+connector::
+  Connector string for the device. The place to which the Astribank is
+  connected. e.g: usb-0000:00:03.3-2
+
+label::
+  The label string of the Astribank unit. E.g: usb-0000:00:03.3-2
+
+status::
+  'connected' (normal operation) or 'disconnected' (has been disconnected,
+  some channels are still open).
+
+timing::
+  Provides some statistics in case the astribank is not the sync source.
+  The format of this file is subject to future changes.
+
+
 Useful Module Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Compilation-time defaults for the all modules can be shown as part of the