xpp driver release 1.1.0 (first part of commit)

* FPGA firmware now loaded from PC (for newer models)
* Driver for the FXO module
* Moved most userspace files to the subdirectory utils (see also next commit)
* Explicit license for firmware files
* Optionally avoid auto-registration
* Initializations parameters to chips given from userspace
* And did I mention bugfixes?


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

1 files changed, 62 insertions, 11 deletions

diff --git a/xpp/README.Astribank b/xpp/README.Astribank
index aa24371..5e49176 100644
--- a/xpp/README.Astribank
+++ b/xpp/README.Astribank
@@ -5,15 +5,48 @@ The drivers reside in a separate subdirectory, xpp/ .
 Building and Installation:
 """""""""""""""""""""""""
 Building and installation is basically like the normal procedure of 
-installing Zaptel. Follow the rest of the documentation here.
+installing Zaptel with some additions.
 
-In addition, the file xpp/xpp_modprobe contains modprobe settings. It
-should be copied verbatim into /etc/modprobe.conf or (better) copied to
-/etc/modprobe.d/ . If you fail to do so, xpp_usb.ko will fail to load
-xpd_fxs.ko and as a result will not detect your Astribank.
-
-Loading Firmware
+Building drivers:
 """"""""""""""""
+From the toplevel zaptel directory run a command similar to (I used line
+continuation to prevent line wrapping):
+
+ $ make \
+        KSRC=/usr/src/kernel-headers-2.6.12-1-386       \
+        KVERS=2.6.12-1-386                              \
+        XPPMOD=xpp/                                     \
+        EC_TYPE=CAN_KB1
+
+ - The KSRC= points to a configured kernel source tree.
+ - The KVERS= should match the relevant tree version.
+ - The XPPMOD= instructs the Zaptel Makefile to descend into the xpp/
+   subdirectory. The slash (/) in the end is mandatory.
+ - The EC_TYPE= select the echo canceler.
+
+Building firmware utilities:
+"""""""""""""""""""""""""""
+Then you should compile the firmware loading utilities. Simply go
+to the zaptel/xpp/utils and run make.
+
+Those who don't use prepackaged drivers should make sure they also
+install the (externally available) fxload utility.
+
+Installation:
+""""""""""""
+
+All firmware files should be copied to a new directory:
+  /usr/share/zaptel/
+
+The xpp_fxloader and xpp_fxloader.usbmap should be copied to:
+ /etc/hotplug/usb/
+
+In addition, the file xpp/xpp_modprobe contains optional modprobe settings.
+It may be copied verbatim into /etc/modprobe.conf or (better) copied to
+/etc/modprobe.d/ .
+
+Loading Firmware Details:
+""""""""""""""""""""""""
 The Astribank needs a firmware loaded into it. Without the firmware, 
 the device will appear in lsusb with vendor ID 04b4 and product ID 8613
 The firmware is provided in the Intel hex format. It can be loaded using 
@@ -21,12 +54,11 @@ the program fxload, which is typically part of the package 'fxload' or
 'hotplug-utils' . 
 
 To load the firmware automatically using the standard hotplug script, 
-place xpp/xpp_fxloader and xpp/xpp_fxloader.usermap in /etc/hotplug/usb
-and place xpp/FPGA_XPD.hex in /etc/xortel (or edit xpp_fxloader
-accordingly). 
+place xpp/utils/xpp_fxloader and xpp/utils/xpp_fxloader.usermap in 
+/etc/hotplug/usb and place xpp/utils/*.hex in /usr/share/zaptel .
 
 Alternatively, xpp_fxloader when given the parameter 'xppdetect' will load 
-the firmware from /etc/xortel/FPGA_XPD.hex . You can use it to load the 
+the firmwares from /usr/share/zaptel/ . You can use it to load the 
 firmware manually.
 
 You should then get in lsusb the vendor ID e4e4 and device ID 2121
@@ -128,6 +160,25 @@ file.
 (There are a bunch of other status files under /proc/xpp/ )
 
 
+Useful Module Parameters:
+""""""""""""""""""""""""
+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.
+
+initialize_registers (xpd_fxs)
+The script that is run to initilize registers of the device. The default is 
+/usr/share/zaptel/initialize_registers . 
+Setting this value could be useful if that location is inconvient for you.
+
+print_dbg: (all modules)
+It will make the driver print tons of debugging messages. Can be sometime 
+even handy, but overly-verbose in the case of xpp_usb. Can be safely 
+set/unset at run-time using /sys/modules .
+
+
 
 BTW: XPP here does not stand for X Printing Panel, XML Pull Parser, 
 X-Windows Phase Plane or XML Professional Publisher. It is simply the