[zaptel-commits] tzafrir: branch 1.4 r3508 - in /branches/1.4: ./ xpp/ xpp/firmwares/ xpp/util...

SVN commits to the Zaptel project zaptel-commits at lists.digium.com
Tue Dec 18 09:36:20 CST 2007


Author: tzafrir
Date: Tue Dec 18 09:36:20 2007
New Revision: 3508

URL: http://svn.digium.com/view/zaptel?view=rev&rev=3508
Log:
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".

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

Added:
    branches/1.4/xpp/utils/zconf/XppUtils.pm
      - copied unchanged from r3506, branches/1.2/xpp/utils/zconf/XppUtils.pm
    branches/1.4/xpp/xbus-pcm.c
      - copied unchanged from r3506, branches/1.2/xpp/xbus-pcm.c
    branches/1.4/xpp/xbus-pcm.h
      - copied unchanged from r3506, branches/1.2/xpp/xbus-pcm.h
    branches/1.4/xpp/xframe_queue.c
      - copied unchanged from r3506, branches/1.2/xpp/xframe_queue.c
    branches/1.4/xpp/xframe_queue.h
      - copied unchanged from r3506, branches/1.2/xpp/xframe_queue.h
Removed:
    branches/1.4/xpp/README.metering
Modified:
    branches/1.4/   (props changed)
    branches/1.4/xpp/.version
    branches/1.4/xpp/Changelog_xpp
    branches/1.4/xpp/Kbuild
    branches/1.4/xpp/README.Astribank
    branches/1.4/xpp/card_bri.c
    branches/1.4/xpp/card_fxo.c
    branches/1.4/xpp/card_fxo.h
    branches/1.4/xpp/card_fxs.c
    branches/1.4/xpp/card_global.c
    branches/1.4/xpp/card_global.h
    branches/1.4/xpp/card_pri.c
    branches/1.4/xpp/firmwares/FPGA_1141.hex
    branches/1.4/xpp/firmwares/FPGA_1151.hex
    branches/1.4/xpp/firmwares/FPGA_FXS.hex
    branches/1.4/xpp/init_card_9_29
    branches/1.4/xpp/utils/example_default_zaptel
    branches/1.4/xpp/utils/fpga_load.c
    branches/1.4/xpp/utils/genzaptelconf
    branches/1.4/xpp/utils/hexfile.c
    branches/1.4/xpp/utils/test_parse.c
    branches/1.4/xpp/utils/xpp_blink
    branches/1.4/xpp/utils/xpp_fxloader
    branches/1.4/xpp/utils/xpp_fxloader.usermap
    branches/1.4/xpp/utils/xpp_sync
    branches/1.4/xpp/utils/zapconf
    branches/1.4/xpp/utils/zaptel_drivers
    branches/1.4/xpp/utils/zaptel_hardware
    branches/1.4/xpp/utils/zconf/Zaptel.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Chans.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Hardware.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Hardware/PCI.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Hardware/USB.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Span.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Xpp.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Xpp/Xbus.pm
    branches/1.4/xpp/utils/zconf/Zaptel/Xpp/Xpd.pm
    branches/1.4/xpp/utils/zt_registration
    branches/1.4/xpp/xbus-core.c
    branches/1.4/xpp/xbus-core.h
    branches/1.4/xpp/xbus-sysfs.c
    branches/1.4/xpp/xdefs.h
    branches/1.4/xpp/xpd.h
    branches/1.4/xpp/xpp_usb.c
    branches/1.4/xpp/xpp_zap.c
    branches/1.4/xpp/xpp_zap.h
    branches/1.4/xpp/xproto.c
    branches/1.4/xpp/xproto.h
    branches/1.4/xpp/zap_debug.h

Propchange: branches/1.4/
------------------------------------------------------------------------------
Binary property 'branch-1.2-merged' - no diff available.

Modified: branches/1.4/xpp/.version
URL: http://svn.digium.com/view/zaptel/branches/1.4/xpp/.version?view=diff&rev=3508&r1=3507&r2=3508
==============================================================================
--- branches/1.4/xpp/.version (original)
+++ branches/1.4/xpp/.version Tue Dec 18 09:36:20 2007
@@ -1,1 +1,1 @@
-branch-rel-4816-r5010
+trunk-r5151

Modified: branches/1.4/xpp/Changelog_xpp
URL: http://svn.digium.com/view/zaptel/branches/1.4/xpp/Changelog_xpp?view=diff&rev=3508&r1=3507&r2=3508
==============================================================================
--- branches/1.4/xpp/Changelog_xpp (original)
+++ branches/1.4/xpp/Changelog_xpp Tue Dec 18 09:36:20 2007
@@ -1,3 +1,28 @@
+Tue Dec 18 2007 Tzafrir Cohen <tzafrir.cohen at xorcom.com> - 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".
+
 Wed Nov 14 2007 Tzafrir Cohen <tzafrir.cohen at xorcom.com> - xpp.r5010
   * Fix a deadlock spotted on some SMP installations.
   * increase FXS ring detect debounce interval.

Modified: branches/1.4/xpp/Kbuild
URL: http://svn.digium.com/view/zaptel/branches/1.4/xpp/Kbuild?view=diff&rev=3508&r1=3507&r2=3508
==============================================================================
--- branches/1.4/xpp/Kbuild (original)
+++ branches/1.4/xpp/Kbuild Tue Dec 18 09:36:20 2007
@@ -30,7 +30,7 @@
 obj-m		+= xpd_bri.o
 endif
 
-xpp-y		+= xbus-core.o xbus-sysfs.o xpp_zap.o xproto.o card_global.o
+xpp-y		+= xbus-core.o xbus-sysfs.o xbus-pcm.o xframe_queue.o xpp_zap.o xproto.o card_global.o
 xpd_fxs-y	+= card_fxs.o
 xpd_fxo-y	+= card_fxo.o
 xpd_bri-y	+= card_bri.o

Modified: branches/1.4/xpp/README.Astribank
URL: http://svn.digium.com/view/zaptel/branches/1.4/xpp/README.Astribank?view=diff&rev=3508&r1=3507&r2=3508
==============================================================================
--- branches/1.4/xpp/README.Astribank (original)
+++ branches/1.4/xpp/README.Astribank Tue Dec 18 09:36:20 2007
@@ -9,6 +9,8 @@
 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 @@
 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,350 +35,78 @@
 
 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/
-
-xpp_fxloader.usermap should be copied to:
- /etc/hotplug/usb/
-
-Run:
-
-  /usr/share/zaptel/xpp_fxloader load
-
-to load firmware.
-
-
-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
-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 is on in case of  
-the hardware failure.
-
-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 frequency.
-
-"Double blink" indicates that the unit has an FXO module, and still is
-getting synchronization from the computer, and is not the synchronization
-source.
-
-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
-indicates an NT port. If the led is solid, the port is down (not even
-layer-1 connection is up). If it is blinking a double blink, layer 1
-is up. A slower single blinking indicates that layer 2 is up as well
-(which means that Asterisk is driving the port).
-
-
-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.
-
-span:
-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:
-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 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
-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
-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. 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 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.
-
-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_FW.hex
-
-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 FPGA firmware manually:
-
-  fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_1151.hex
-
-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 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. 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 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 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.
-
-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'.
-
-Also you can try the following:
-
-  /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/restart asterisk.
-
-
-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.
-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 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     - 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 installed on-demand: no need to install
-the xpd_fxo if you have only Astribank FXS.
-
-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 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.
-
-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. 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 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.
-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: 
-
-  zt_registration on
-
-For a system with several spans you'll see a "fast train of lights".
-
-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..
-
-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.
-
-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):
-
-  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:
-
-
-
-SAMPLE CONFIGURATIONS
+
+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.
+
+
+[[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:
+
+-----------------------------------------------------------
+# Lines beginning with '#' are considered comments and ignored.
+
+# 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.
+
+# 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
 ~~~~~~~~~~~~~~~~
@@ -558,6 +284,9 @@
           22 XPP_FXO/00/01/7 FXSKS (In use) (no pcm)
 
 
+
+/etc/asterisk/extensions.conf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sample dialplan (extensions.conf) for all the above:
 
 -----------------------------------------------------------
@@ -630,165 +359,8 @@
 -----------------------------------------------------------
 
 
-/proc Interface
+Troubleshhoting
 ---------------
-The Astribank drivers provide their own /proc interface under /proc/xpp.
-(Note that the details of this interface are still potentially subject to 
-changes)
-
-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.
-
-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 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.
-
-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.)
-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
-
-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.
-
-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 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/.
-
-
-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:
-
------------------------------------------------------------
-# Lines beginning with '#' are considered comments and ignored.
-
-# 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.
-
-# 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.
-
-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 to print tons of debugging messages. You can 
-  set/unset the parameter at run-time.
-
-  The parameter value is a bitmask of several values. The different bits 
-  meaning as it defined in xpp/zap_debug.h: 
-
-  * 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.
-
-  For example,
-
-    echo 33 >/sys/modules/xpp/parameters/print_dbg 
-
-  forces module xpp to print general debugging messages (1) and procfs
-  debugging messages (32).
-
-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.
-  +
-  +
-  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 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 (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 those parameters.
-
-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:
@@ -885,6 +457,555 @@
     `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
+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 is on in case of  
+the hardware failure.
+
+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 frequency.
+
+"Double blink" indicates that the unit has an FXO module, and still is
+getting synchronization from the computer, and is not the synchronization
+source.
+
+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
+indicates an NT port. If the led is solid, the port is down (not even
+layer-1 connection is up). If it is blinking a double blink, layer 1
+is up. A slower single blinking indicates that layer 2 is up as well
+(which means that Asterisk is driving the port).
+
+
+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.
+
+span:
+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:
+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 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
+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
+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. 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 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.
+
+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_FW.hex
+
+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 FPGA firmware manually:
+
+  fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_1151.hex
+
+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 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. 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 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 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.
+
+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

[... 13316 lines stripped ...]



More information about the zaptel-commits mailing list