* Update documentation on perl utilities.

* But we do need to ignore their man pages.


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

8 files changed, 134 insertions, 32 deletions

diff --git a/xpp/.version b/xpp/.version
index d18c751..9d20fe3 100644
--- a/xpp/.version
+++ b/xpp/.version
@@ -1 +1 @@
-trunk-r4371
+trunk-r4372
diff --git a/xpp/ChangeLog b/xpp/ChangeLog
index bf962ca..b054a01 100644
--- a/xpp/ChangeLog
+++ b/xpp/ChangeLog
@@ -1,4 +1,4 @@
-Thu Jul 12 2007 Oron Peled <oron@actcom.co.il> - xpp.r4370
+Thu Jul 12 2007 Oron Peled <oron@actcom.co.il> - xpp.r4372
   * Update to zaptel-1.2.18 and zaptel-1.4.3 (r4308 onward)
   * Fix a critical race with zaptel synchronization (r4362)
   * Added a /proc/xpp/cmds for statistics about command timing (r4360)
diff --git a/xpp/utils/Makefile b/xpp/utils/Makefile
index f446216..72ba74d 100644
--- a/xpp/utils/Makefile
+++ b/xpp/utils/Makefile
@@ -31,7 +31,7 @@ PERL_MODS	:= $(shell cd zconf; echo $(PERL_MODS_PAT))
 XPD_FIRMWARE	= $(wildcard ../firmwares/*.hex)
 XPD_INIT_DATA	= $(XPD_FIRMWARE) init_fxo_modes
 XPD_INIT	= $(wildcard ../init_card_?_*) ../calibrate_slics xpp_fxloader
-XPD_INIT_PERL	= ../init_card_6_26 ../init_card_7_26 ../init_card_9_26
+XPD_INIT_PERL	= ../init_card_6_26 ../init_card_7_26
 
 # Variables that should be defined above, but need sane defaults:
 # FIXME: Are those values really sane?
diff --git a/xpp/utils/lszaptel b/xpp/utils/lszaptel
index 7a8f422..3126c8a 100755
--- a/xpp/utils/lszaptel
+++ b/xpp/utils/lszaptel
@@ -40,18 +40,53 @@ lszaptel
 
 Example output:
 
-	### Span  1: XBUS-03/XPD-00 "Xorcom XPD #3/0: FXS"
-	  1 FXS
-	  2 FXS
-	  3 FXS
-	  4 FXS
-	  5 FXS
-	  6 FXS
-	  7 FXS
-	  8 FXS
-	  9 Output
-	 10 Output
-	 11 Input
-	 12 Input
-	 13 Input
-	 14 Input
+	### Span  1: WCTDM/0 "Wildcard TDM400P REV E/F Board 1"
+	  1 FXO        FXOLS      (In use)
+	  2 FXS        FXSKS
+	  3 FXS        FXSKS
+	  4 FXS        FXSKS
+	### Span  2: XBUS-00/XPD-00 "Xorcom XPD #00/00: FXO"
+	  5 FXO        FXSKS      (In use)
+	  6 FXO        FXSKS      (In use) (no pcm)
+	  7 FXO        FXSKS      (In use) (no pcm)
+	  8 FXO        FXSKS      (In use) (no pcm)
+	  9 FXO        FXSKS      (In use) (no pcm)
+	 10 FXO        FXSKS      (In use) (no pcm)
+	 11 FXO        FXSKS      (In use) (no pcm)
+	 12 FXO        FXSKS      (In use) (no pcm)
+	### Span  3: XBUS-00/XPD-10 "Xorcom XPD #00/10: FXO"
+	 13 FXO        FXSKS      (In use) (no pcm)
+	 14 FXO        FXSKS      (In use) (no pcm)
+	 15 FXO        FXSKS      (In use) (no pcm)
+	 16 FXO        FXSKS      (In use) (no pcm)
+	 17 FXO        FXSKS      (In use) (no pcm)
+	 18 FXO        FXSKS      (In use) (no pcm)
+	 19 FXO        FXSKS      (In use) (no pcm)
+	 20 FXO        FXSKS      (In use) (no pcm)
+
+	...
+
+	### Span  6: XBUS-01/XPD-00 "Xorcom XPD #01/00: FXS"
+	 37 FXS        FXOLS      (In use)
+	 38 FXS        FXOLS      (In use) (no pcm)
+	 39 FXS        FXOLS      (In use) (no pcm)
+	 40 FXS        FXOLS      (In use) (no pcm)
+	 41 FXS        FXOLS      (In use) (no pcm)
+	 42 FXS        FXOLS      (In use) (no pcm)
+	 43 FXS        FXOLS      (In use) (no pcm)
+	 44 FXS        FXOLS      (In use) (no pcm)
+	 45 Output     FXOLS      (In use) (no pcm)
+	 46 Output     FXOLS      (In use) (no pcm)
+	 47 Input      FXOLS      (In use) (no pcm)
+	 48 Input      FXOLS      (In use) (no pcm)
+	 49 Input      FXOLS      (In use) (no pcm)
+	 50 Input      FXOLS      (In use) (no pcm)
+
+The first column is the type of the channel (port, for an analog device) 
+and the second one is the signalling (if set).
+
+=head1 FILES
+
+lszaptel is a somewhat glorified 'cat /proc/zaptel/*' . Unlike that
+command, it sorts the spans with the proper order. It also formats the
+output slightly differently.
diff --git a/xpp/utils/xpp_blink b/xpp/utils/xpp_blink
index ea6e353..65be247 100755
--- a/xpp/utils/xpp_blink
+++ b/xpp/utils/xpp_blink
@@ -101,15 +101,18 @@ Blink all the leds of an XPD.
 =over 16
 
 =item span	Select by span number. This only work for XPD registered to zaptel.
+		will also print the zaptel channels of the span and the
+		xbus/xpd this span represents.
 
 =item xpd	Select by xbus + xpd numbers. If only xbus number is given, all the
-		XPDs of the selected xbus are blinked.
+		XPDs of the selected xbus (Astribank) are blinked.
 
 =back
 
 =head1 EXAMPLES
 
   $ xpp_blink bzzt span 2
+  Using XBUS-04/XPD-10 (connected via usb-0000:00:1d.7-1): channels 15 16 17 18 19 20 21 22
 
   $ xpp_blink xpd 0 1
 
diff --git a/xpp/utils/xpp_sync b/xpp/utils/xpp_sync
index 4bd1e86..67825f8 100755
--- a/xpp/utils/xpp_sync
+++ b/xpp/utils/xpp_sync
@@ -46,10 +46,8 @@ sub get_sorted_xpds() {
 
 	# Sync Priority
 	return
-		@pri_nt_xpds,
 		@bri_nt_xpds,
 		@fxo_xpds,
-		@pri_te_xpds,
 		@bri_te_xpds,
 		@fxs_xpds;
 }
@@ -162,7 +160,7 @@ __END__
 
 =head1 NAME
 
-xpp_sync - Handle sync selection of Xorcom XPD's.
+xpp_sync - Handle sync selection of Xorcom Astribanks.
 
 =head1 SYNOPSIS
 
@@ -170,8 +168,15 @@ xpp_sync [auto|host|nn]
 
 =head1 DESCRIPTION
 
-Without parameters, the current syncer. Either HOST or the XBUS number.
-Then a list of the 3 best XPD's for syncing.
+On a normal operation one Astribank device provides timing for all the
+other Astribank devices.
+
+When run without parameters, xpp_sync will display a list of Astribanks
+(xbuses) that are connected and registered as Zaptel spans. The current
+xpp sync master will be marked (if it is not HOST).
+
+If you this an Astribank is connected and yet it does not appear on the 
+output of xpp_sync, it may be unregistered. Try running zt_registration .
 
 =head2 Parameters
 
@@ -179,7 +184,7 @@ Then a list of the 3 best XPD's for syncing.
 
 =item auto
 
-Automatically selects the best XPD for syncing (with HOST fallback).
+Automatically selects the best Astribank for syncing (with HOST fallback).
 
 =item host
 
@@ -193,9 +198,27 @@ Set XBUS number nn as sync source.
 
 =head2 Example output:
 
-	Current sync: 03
+	Current sync: 02
 	Best Available Syncers:
-		  XBUS-00: FXS FXO              (USB-0000:00:10.4-4)
-		+ XBUS-03: FXS FXS FXS FXS      (USB-0000:00:10.4-1)
-		  XBUS-02: FXS FXS FXS FXS      (USB-0000:00:10.4-2)
-		  XBUS-01: FXS FXS FXS FXS      (USB-0000:00:10.4-3)
+	 + XBUS-02 [ FXS*3 FXO ]        (usb-0000:00:1d.7-3)
+	   XBUS-04 [ FXS*4 ]            (usb-0000:00:1d.7-1)
+	   XBUS-03 [ FXS*4 ]            (usb-0000:00:1d.7-2)
+	   XBUS-01 [ FXS*4 ]            (usb-0000:00:1d.7-4)
+	   XBUS-00 [ FXS*4 ]            (usb-0000:00:1d.7-5)
+	   XBUS-05 [ FXS*4 ]            (usb-0000:00:1d.7-6)
+
+In this example we see that the recommended xpp sync master is XBUS-02 - 
+it is the first on the list. It is also the actual syncer, as we can see
+from the '+' beside it.
+
+=head1 FILES
+
+=over
+
+=item /proc/xpp/sync
+
+xpp_sync is essentially a nicer interface to /proc/xpp/sync . That file
+shows the current xpp sync master (and in what format you need to write
+to it to set the master).
+
+=back
diff --git a/xpp/utils/zaptel_hardware b/xpp/utils/zaptel_hardware
index 049c1e8..afd3a06 100755
--- a/xpp/utils/zaptel_hardware
+++ b/xpp/utils/zaptel_hardware
@@ -5,7 +5,7 @@
 # This program is free software; you can redistribute and/or
 # modify it under the same terms as Perl itself.
 #
-# $Id:$
+# $Id$
 #
 use strict;
 use File::Basename;
@@ -92,3 +92,8 @@ zaptel_hardware
 
 Show all zaptel hardware devices, both used and unused.
 
+=head1 BUGS
+
+Assumes a bit too much about the output of lspci and sysfs. Currently
+the PCI scanning will not work on e.g. CentOS 4. This should be fixed in
+Zaptel::Hardware::PCI.pm
diff --git a/xpp/utils/zt_registration b/xpp/utils/zt_registration
index aa92cc4..9a8323f 100755
--- a/xpp/utils/zt_registration
+++ b/xpp/utils/zt_registration
@@ -74,7 +74,7 @@ zt_registration [on|off]
 
 =head1 DESCRIPTION
 
-Without parameters, show all connected XPD's sorted by physical connector order.
+Without parameters, show all connected XPDs sorted by physical connector order.
 Each one is show to be unregistered (off), or registered to a specific zaptel span
 (the span number is shown).
 
@@ -85,3 +85,39 @@ All registerations/deregisterations are sorted by physical connector string.
 off -- deregisters all XPD's from zaptel.
 
 on -- registers all XPD's to zaptel.
+
+=head2 Sample Output
+
+	$ zt_registration
+	XBUS-02                 usb-0000:00:1d.7-3
+	        XBUS-02/XPD-00: on Span 9
+	        XBUS-02/XPD-10: on Span 10
+	        XBUS-02/XPD-20: on Span 11
+	        XBUS-02/XPD-30: on Span 12
+	XBUS-01                 usb-0000:00:1d.7-4
+	        XBUS-01/XPD-00: on Span 13
+	        XBUS-01/XPD-10: on Span 14
+	        XBUS-01/XPD-20: on Span 15
+	        XBUS-01/XPD-30: on Span 16
+	XBUS-00                 usb-0000:00:1d.7-5
+	        XBUS-00/XPD-00: on Span 17
+	        XBUS-00/XPD-10: on Span 18
+	        XBUS-00/XPD-20: on Span 19
+	        XBUS-00/XPD-30: on Span 20
+
+=head1 FILES
+
+=over
+
+=item /proc/xpp/XBUS-nn/XPD-mm/zt_registration
+
+Reading from this file shows if if the if the specific XPD is
+registered. Writing to it 0 or 1 registers / unregisters the device.
+
+This should allow you to register / unregister a specific XPD rather
+than all of them. 
+
+Unregistering an XPD will fail if the span is in use (has some channels
+that are in use by e.g. Asterisk).
+
+=back