* XppUtils.pm renamed Zaptel::Utils.pm .

* Some more documentation.


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

11 files changed, 57 insertions, 16 deletions

diff --git a/xpp/.version b/xpp/.version
index 61f8917..79b9063 100644
--- a/xpp/.version
+++ b/xpp/.version
@@ -1 +1 @@
-trunk-r5157
+trunk-r5178
diff --git a/xpp/Changelog_xpp b/xpp/Changelog_xpp
index 87e9b09..9112826 100644
--- a/xpp/Changelog_xpp
+++ b/xpp/Changelog_xpp
@@ -1,4 +1,4 @@
-Tue Dec 18 2007 Tzafrir Cohen <tzafrir.cohen@xorcom.com> - xpp.r5157
+Mon Dec 24 2007 Tzafrir Cohen <tzafrir.cohen@xorcom.com> - xpp.r5178
   * xpd_pri: Basically ready.
   * PCM synchronization changes:
     - Each Astribank unit ticks independently. Each with its own PLL.
diff --git a/xpp/README.Astribank b/xpp/README.Astribank
index 6e7cdb2..50c6544 100644
--- a/xpp/README.Astribank
+++ b/xpp/README.Astribank
@@ -10,7 +10,7 @@ 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[]
+http://zaptel.tzafrir.org.il/README.Astribank.html[]
 
 Building and Installation
 -------------------------
@@ -365,7 +365,7 @@ The following commands provide useful information for debugging:
 
 * Check USB level status. You can use one of the following utilities for it:
 
-  zaptel_hardware 
+  zaptel_hardware -v
        or
   lsusb | grep e4e4
 
@@ -376,7 +376,7 @@ The following commands provide useful information for debugging:
     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.
+    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
@@ -495,7 +495,7 @@ is up. A slower single blinking indicates that layer 2 is up as well
 (which means that Asterisk is driving the port).
 
 
-DEVICE STARTUP
+Device Startup
 ~~~~~~~~~~~~~~
 This section describes in great depth the initialization of the Xorcom
 Astribank. Normally it would not be really needed, as the standard
@@ -716,6 +716,20 @@ 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'. Currently this script will just adjust the
+Astribank sync settings (by running xpp_sync). 
+
+
 Registering in Zaptel
 ^^^^^^^^^^^^^^^^^^^^^
 The XPDs will not automatically register as zaptel spans. This is
@@ -788,6 +802,7 @@ 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/xbuses
 ^^^^^^^^^^^^^^^^
 File /proc/xpp/xbuses lists the connected Astribank devices (one line 
@@ -797,6 +812,7 @@ 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.
 
+
 /proc/xpp/sync
 ^^^^^^^^^^^^^^
 A read/write file. It contains information about current synchronization 
diff --git a/xpp/utils/xpp_sync b/xpp/utils/xpp_sync
index 80b61c7..1438f50 100755
--- a/xpp/utils/xpp_sync
+++ b/xpp/utils/xpp_sync
@@ -17,7 +17,20 @@ use Zaptel::Xpp::Xbus;
 my $sync;
 my $autoselect;
 
+sub usage() {
+	print 
+		"$0: show / set Astribank sync source\n".
+		"\n".
+		"Usage: $0                    Show sync source.\n".
+		"       $0 <auto|NN|zaptel>   Set sync source.\n".
+		"";
+}
+
 if(@ARGV == 1) {
+	if ($ARGV[0] =~ /^(-h|--help|help)$/) {
+		usage;
+		exit(0);
+	}
 	$sync = shift;
 	$autoselect = 1 if $sync =~ /^auto$/i;
 }
@@ -142,7 +155,7 @@ xpp_sync - Handle sync selection of Xorcom Astribanks.
 
 =head1 SYNOPSIS
 
-xpp_sync [auto|host|nn]
+xpp_sync [auto|zaptel|nn]
 
 =head1 DESCRIPTION
 
@@ -164,12 +177,18 @@ output of xpp_sync, it may be unregistered. Try running zt_registration .
 
 Automatically selects the best Astribank for syncing.
 
+=item zaptel
+
+Gets synchronization from the Zaptel sync master.
+
 =item nn
 
-Set XBUS number nn as sync source.
+Sets XBUS-I<nn> as sync source.
 
 =back
 
+(Parameter name is case-insensitive)
+
 =head2 Example output:
 
 	Setting SYNC
@@ -188,6 +207,12 @@ 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.
 
+xpp_sync is normally called from both the zaptel init.d script and the 
+the Astribank udev script. The parameter it is called with defaults to 
+I<auto>, but it is possible to override that parameter (e.g: set it to
+I<zaptel>) through the value of XPP_SYNC in either /etc/defualt/zaptel
+or /etc/sysconfig/zaptel .
+
 =head1 FILES
 
 =over
diff --git a/xpp/utils/zconf/Zaptel/Chans.pm b/xpp/utils/zconf/Zaptel/Chans.pm
index 236d6af..16ab1d5 100644
--- a/xpp/utils/zconf/Zaptel/Chans.pm
+++ b/xpp/utils/zconf/Zaptel/Chans.pm
@@ -8,7 +8,7 @@ package Zaptel::Chans;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 
 sub new($$$$$$) {
 	my $pack = shift or die "Wasn't called as a class method\n";
diff --git a/xpp/utils/zconf/Zaptel/Hardware/PCI.pm b/xpp/utils/zconf/Zaptel/Hardware/PCI.pm
index 7d4e2b3..b1a6b67 100644
--- a/xpp/utils/zconf/Zaptel/Hardware/PCI.pm
+++ b/xpp/utils/zconf/Zaptel/Hardware/PCI.pm
@@ -8,7 +8,7 @@ package Zaptel::Hardware::PCI;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 use Zaptel::Hardware;
 
 our @ISA = qw(Zaptel::Hardware);
diff --git a/xpp/utils/zconf/Zaptel/Hardware/USB.pm b/xpp/utils/zconf/Zaptel/Hardware/USB.pm
index a5501d1..a2dc08f 100644
--- a/xpp/utils/zconf/Zaptel/Hardware/USB.pm
+++ b/xpp/utils/zconf/Zaptel/Hardware/USB.pm
@@ -8,7 +8,7 @@ package Zaptel::Hardware::USB;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 use Zaptel::Hardware;
 use Zaptel::Xpp;
 use Zaptel::Xpp::Xbus;
diff --git a/xpp/utils/zconf/Zaptel/Span.pm b/xpp/utils/zconf/Zaptel/Span.pm
index 951f603..f8e5f01 100644
--- a/xpp/utils/zconf/Zaptel/Span.pm
+++ b/xpp/utils/zconf/Zaptel/Span.pm
@@ -8,7 +8,7 @@ package Zaptel::Span;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 use Zaptel::Chans;
 
 my $proc_base = "/proc/zaptel";
diff --git a/xpp/utils/zconf/XppUtils.pm b/xpp/utils/zconf/Zaptel/Utils.pm
index 1526537..8d13ad7 100644
--- a/xpp/utils/zconf/XppUtils.pm
+++ b/xpp/utils/zconf/Zaptel/Utils.pm
@@ -1,4 +1,4 @@
-package XppUtils;
+package Zaptel::Utils;
 
 # Accessors (miniperl does not have Class:Accessor)
 our $AUTOLOAD;
@@ -43,7 +43,7 @@ sub import {
 	#
 	# Export symbols, but not by accident of inheritance.
 	#
-	die "Sombody inherited XppUtils" if $pkg ne 'XppUtils';
+	die "Sombody inherited Zaptel::Utils" if $pkg ne 'Zaptel::Utils';
 	no strict 'refs';
 	*{ $callpkg . '::AUTOLOAD' } = \&AUTOLOAD;
 	*{ $callpkg . '::xpp_dump' } = \&xpp_dump;
diff --git a/xpp/utils/zconf/Zaptel/Xpp/Xbus.pm b/xpp/utils/zconf/Zaptel/Xpp/Xbus.pm
index 57c93f5..a5fcf1e 100644
--- a/xpp/utils/zconf/Zaptel/Xpp/Xbus.pm
+++ b/xpp/utils/zconf/Zaptel/Xpp/Xbus.pm
@@ -8,7 +8,7 @@ package Zaptel::Xpp::Xbus;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 use Zaptel::Xpp::Xpd;
 
 my $proc_base = "/proc/xpp";
diff --git a/xpp/utils/zconf/Zaptel/Xpp/Xpd.pm b/xpp/utils/zconf/Zaptel/Xpp/Xpd.pm
index ef479fb..c05cfdb 100644
--- a/xpp/utils/zconf/Zaptel/Xpp/Xpd.pm
+++ b/xpp/utils/zconf/Zaptel/Xpp/Xpd.pm
@@ -8,7 +8,7 @@ package Zaptel::Xpp::Xpd;
 # $Id$
 #
 use strict;
-use XppUtils;
+use Zaptel::Utils;
 
 my $proc_base = "/proc/xpp";