* Earleier initialization of PRI module's register.

* Fix zaptel-perl reporting of battery after procfs changes.
* Documentation updates.
* Block hdlcstress/test fixes that followed: already merged.

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


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

1 files changed, 160 insertions, 130 deletions

diff --git a/kernel/xpp/README.Astribank b/kernel/xpp/README.Astribank
index 183cd76..e3c6070 100644
--- a/kernel/xpp/README.Astribank
+++ b/kernel/xpp/README.Astribank
@@ -21,70 +21,25 @@ 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 .
+typically the package libusb-dev on Debian (and derivatives like Ubuntu)
+or libusb-devel on RedHat (and derivatives like CentOS/Trixbox).
 
-On zaptel 1.2 you will need to run the following extra step to build the
-Astribank drivers, apart from the standard 'make':
+On Zaptel 1.2 you will need to run the following extra step to build the
+user space utilities, apart from the standard 'make; make install':
 
   make -C xpp/utils install
 
-In order to build the user space utilities, you will need the libusb-dev
-package on Debian (and derivatives like Ubuntu) or libusb-devel on RedHat
-(and derivatives like CentOS/Trixbox).
-
-Apart from the standard 'make install' in the zaptel directory, 
-run:
-
-  make -C xpp/utils install
-
-Though this should be done automatically on zaptel >= 1.4.1 .
-
-PRI Port Setup
-~~~~~~~~~~~~~~
-A port in the PRI module can be either E1 (default) or T1. It can also be 
-either "TE" or "NT".
-
-TE::
-  Use the bottom port (green LED) and don't invert any wiring. Hint to
-  higher layers that this will be the TE (CPE) side of the connection. 
-  This is the default setup.
-
-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 (Net) 
-  side of the connection.
-
-The value XPP_PRI_SETUP in the init configuration file (see example
-below) can be used to change those defaults. This value is a
-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:
-- CONNECTOR/usb..../XPD-nn	To identify by physical connector
-- 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'.
-
-For each line you should define both if it is E1 or T1 and if it is NT
-or TE.
-
-The list implicitly contains an 'NUM/*=TE,E1' catch all default, appended
-to its end.
+Though this should be done automatically on Zaptel >= 1.4.1 .
 
 
 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.
+genzaptelconf or zapconf which are included with Zaptel. Nevertheless,
+the following can serve as reference configurations 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 
@@ -111,14 +66,14 @@ that may be defined there:
 # 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.
+# span. Or a specific XBUS number.
 #XPP_SYNC=ZAPTEL
 
-# Disables hotplug firmware loading
+# Disables hot-plug firmware loading
 #XPP_HOTPLUG_DISABLED=yes
 #
 
-# Disables udev hook called when an astribank is added and ready
+# Disables udev hook called when an Astribank is added and ready
 # or removed.
 #ASTRIBANK_HOOK_DISABLED=yes
 
@@ -308,8 +263,8 @@ Astribank 4 PRI E1
     channel => 61-75,77-90
     
     ; NT ports:
-    signalling = bri_net_ptmp
-    ;signalling = bri_net
+    signalling = pri_net
+    ;signalling = pri_net
     context = from-internal
     group = 2,12
     channel => 31-45,47-60
@@ -336,8 +291,8 @@ Astribank 4 PRI T1
     channel => 49-71
     
     ; NT ports:
-    signalling = bri_net_ptmp
-    ;signalling = bri_net
+    signalling = pri_cpe
+    ;signalling = pri_net
     context = from-internal
     group = 2,12
     channel => 25-47
@@ -346,50 +301,13 @@ Astribank 4 PRI T1
     channel => 73-95
 
 
-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.
+; 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.
@@ -459,7 +377,7 @@ exten => s,n,NoOp(Got signal from Zaptel Channel ${ZAP_CHAN})
 
 
 
-Troubleshhoting
+Troubleshooting
 ---------------
 The following commands provide useful information for debugging:
 
@@ -620,10 +538,10 @@ 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.
+Or disconnect the Astribank from the power 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
@@ -648,8 +566,8 @@ 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.
+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 
@@ -679,6 +597,110 @@ is up. A slower single blinking indicates that layer 2 is up as well
 (which means that Asterisk is driving the port).
 
 
+PRI Ports Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+Astribank PRI module has two RJ-45 sockets for each PRI port. The lower
+socket provides typical PRI CPE side wiring: Rx- pins 1,2; Tx - pins 
+4,5. The upper socket provides typical PRI Network side  wiring: Rx- pins
+4,5; Tx - pins 1,2. The both sockets are permanently active and you can 
+use any of them regardless of any configuration parameters (Both
+connectors are live. And connecting both of them with a flat 8-wire
+ethernet cable is a simple way to do a loop test for the port).
+
+
+For each port there are two optional parameters that define its
+behavior:
+
+Each port in the PRI module can be configured either as E1 or T1. The
+port type defaults to E1 and can be changed to T1 in the Zaptel Init 
+Configuration File.
+
+The Astribank xpp driver uses that information for correct hardware
+initialization that is performed before the Zaptel span registration
+process takes place. Because of that, xpp driver can't use the 
+information from file zaptel.conf.
+
+Another parameter that also can be defined in the Zaptel Init
+Configuration File is the function group TE (CPE) or NT (Network). This
+parameter is used for (a) building correct Zaptel & Asterisk
+configuration by genzaptelconf and (b) control RJ-45 sockets LEDs for 
+better visual port control:
+
+A port in the PRI module can be either E1 (default) or T1. It can also be 
+either "TE" (default) or "NT".
+
+TE::
+  Green LED of the lower socket will light. Hint that this is a TE
+  (CPE) port. This is the default.
+
+NT::
+    Orange LED of the upper socket will light. Hint that this is an
+    NT (network) port.
+
+To set them to a non-default value, you should use the variable
+XPP_PRI_SETUP in the 
+xref:_zaptel_init_configuration_file[Zaptel Init Configuration File]
+(/etc/sysconfig/zaptel on Redhats, /etc/default/zaptel on Debians).
+This value is a whitespace-separated list of conditions. When a port is 
+initialized it checks those conditions and uses the first one that 
+matches.
+
+Match expressions may be:
+- CONNECTOR/usb..../XPD-nn	To identify by physical connector
+- 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'.
+
+For each line you should define both if it is E1 or T1 and if it is NT
+or TE.
+
+The list implicitly contains an 'NUM/*=TE,E1' catch all default, appended
+to its end.
+
+A number of useful examples. Note that you should use just one of them.
+---------------------------------------------
+# All ports are E1 and CPE
+#XPP_PRI_SETUP=  #no need to set it
+
+# All ports are T1 and CPE:
+XPP_PRI_SETUP='NUM/*=T1,TE'
+
+# Now you want to test a loop between ports 1 and 2 and between 
+# port 3 and 4. So let's make ports 2 and 4 network:
+XPP_PRI_SETUP='NUM/*/XPD-0[24]=E1,NT'
+
+# The same with T1. In this case we also need to set the default of all 
+# the others to T1. Note that we can use more than one item and the
+# first one that matches counts:
+XPP_PRI_SETUP='
+  NUM/*/XPD-0[24]=T1,NT
+  NUM/*=T1,TE
+'
+
+# Actually, there is an implicit 'NUM/*=E1,TE' added to the end of the
+# value and set as the value if there is none. This is how the default
+# is set.
+
+# If you have more than one Astribank and you wish to configure
+# different Astribanks differently, you can use the CONNECTOR option:
+# e.g: set one specific Astribank as E1 network. The others default to
+# E1 CPE:
+XPP_PRI_SETUP='CONNECTOR/usb-0000:00:10.4-4/*=E1,NT'
+
+# Theoretically you could use: XPP_PRI_SETUP='NUM/XBUS-01/*=E1,NT'
+# but the XBUS number depends on the specific load order and is thus
+# might differ in a manual load and a system boot.
+---------------------------------------------
+
+This is currently implemented by writing a value to the 
+xref:_proc_xpp_xbus_nn_xpd_mm_pri_info[pri_info file in procfs], but
+that may change in future versions.
+
+
 Device Startup
 ~~~~~~~~~~~~~~
 This section describes in great depth the initialization of the Xorcom
@@ -767,7 +789,7 @@ incremented by 1.
 
 Firmware Loading with Hotplug
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Hotplug framework was popular for hotplugging different devices and 
+The Hotplug framework was popular for hot-plugging 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 
@@ -882,7 +904,7 @@ 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.
+hardwiring 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,
@@ -901,13 +923,13 @@ 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 
+faster "blinking" when the XPDs register as Zaptel spans. The initialization 
 of an FXS XPD may take a few seconds.
 
 
 Registering in Zaptel
 ^^^^^^^^^^^^^^^^^^^^^
-The XPDs will not automatically register as zaptel spans. This is
+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.
@@ -930,13 +952,15 @@ 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
+from that file returns 0 if the span is unregisters 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
+(register) or 0 (unregister) to that file. Registration 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 
+You may choose to register the XPDs in Zaptel automatically. This may
+make the startup sequence a bit simpler, but is generally not
+recommended on a system with more than one Astribank or an Astribank and
+a different Zaptel device. 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):
 
@@ -947,14 +971,14 @@ 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
+other Zaptel device. In order for you to get a dial-tone 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,
+configure those levels. e.g, the README file in the top-level directory,
 and
 
   http://voip-info.org/wiki/view/Asterisk+config+zapata.conf[]
@@ -975,11 +999,11 @@ Alternatively, write you own configuration, based on the sample from the
 ~~~~~~~~~~~~~~~
 The Astribank drivers provide their own /proc interface under /proc/xpp.
 Here we review the more useful details of the procfs interface. There
-are many other debugging details that are exposed through the debugfs
+are many other debugging details that are exposed through the procfs
 interface. 
 
 Also note that those details are subject to changes. Generally the
-recommended stable interface are the zaptel-perl utilities from the
+recommended stable interface are the Zaptel-perl utilities from the
 xpp/utils directory.
 
 
@@ -1006,14 +1030,14 @@ Possible values are:
   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
+  Make the Astribanks synchronize with the Zaptel timing master span.
+  You probably need this to get faxes from a non-Astribank adapter to an
   Astribank.
 
 Though you'll normally use xpp_sync(8) for that.
 
 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.
+module (span in the terms of Zaptel) there is folder /proc/XBUS-nn/XPD-mm.
 
 
 /proc/xpp/XBUS-nn/waitfor_xpds
@@ -1037,7 +1061,7 @@ 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).
 
-A more convient interface to this is the command zt_registration that
+A more convenient 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.
 
@@ -1063,12 +1087,16 @@ either a read request or a write request you need to write to that file.
 
 It is mainly used by the initialization scripts (card_init_*).
 
+Incorrect usage of this file is one possible way of damaging the
+Astribank.
+
 
 /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.
+value of "battery" for that specific port, and a bunch of other
+characteristics of the port.
 
 
 /proc/xpp/XBUS-nn/XPD-mm/bri_info
@@ -1128,15 +1156,17 @@ NT::
 
 LOCALOOP::
   Set the device into local loop mode: loops the transmitted channels
-  directly into the recieved channels.
+  directly into the received channels.
 
 NOLOCALLOOP::
   Ends local loop mode.
 
 Normally those are set by the PRI initialization script . See the
-definition of XPP_PRI_SETUP in xref:sect-default[the sample Zaptel init
+definition of XPP_PRI_SETUP in 
+xref:_zaptel_init_configuration_file[the sample Zaptel init 
 configuration file] .
 
+
 There are a bunch of other status files under /proc/xpp/.
 
 
@@ -1162,14 +1192,14 @@ connector::
   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
+  The label string of the Astribank unit. E.g: usb:00000135
 
 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.
+  Provides some statistics in case the Astribank is not the sync source.
   The format of this file is subject to future changes.
 
 
@@ -1181,7 +1211,7 @@ description line for the parameter in the "modinfo" command output.
 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
+  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.
 
@@ -1192,7 +1222,7 @@ initdir (xpp)::
 
 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
+  separate tasklets. This should probably help on higher-end systems with
   multiple Astribanks.
 
 print_dbg (all modules)::
@@ -1205,7 +1235,7 @@ print_dbg (all modules)::
   * 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
+  * 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.
@@ -1222,7 +1252,7 @@ print_dbg (all modules)::
 
 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 
+  signal to phones equipped with the Message Waiting 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.