From 4953605453a7f7f1da8c70c4c12a4b557cfc2c24 Mon Sep 17 00:00:00 2001 From: tzafrir Date: Mon, 6 Nov 2006 21:18:42 +0000 Subject: r1557@boole: tzafrir | 2006-11-06 20:12:16 +0200 Merging xpp driver release 1.2 (rev. 2569), originally team/tzafrir/xpp_1.2 * Should build well. Almost final. * genzaptelconf: Also work when zap_autoreg=0 * README.Astribank updated for rev. 1.2. * xpp/utils/Makefile: Use $< with cc -c * Get xpp/utils configuration from autoconf (without changesin top dir) git-svn-id: http://svn.digium.com/svn/zaptel/trunk@1563 5390a7c7-147a-4af0-8ec9-7488f05a26cb --- xpp/README.Astribank | 326 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 240 insertions(+), 86 deletions(-) (limited to 'xpp/README.Astribank') diff --git a/xpp/README.Astribank b/xpp/README.Astribank index f6f995c..e45bde9 100644 --- a/xpp/README.Astribank +++ b/xpp/README.Astribank @@ -9,30 +9,20 @@ installing Zaptel with some additions. 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: +Unlike earlier versions, the Astribank driver (xpp) will now build +automatically. To build the drivers follow the usual Zaptel +documentation. E.g: run: + + make + +in the top-level directory. + +Next you will need to build the user-space tools needed for loading the +firmware and initialization files for the Astribank: + + make -C xpp/utils + +INSTALLATION: """""""""""" apart from the standard 'make install' in the zaptel directory, @@ -45,7 +35,7 @@ Alternatively, do the following manually: All firmware files should be copied to a new directory: /usr/share/zaptel/ -The xpp_fxloader and xpp_fxloader.usbmap should be copied to: +The xpp_fxloader and xpp_fxloader.usermap should be copied to: /etc/hotplug/usb/ In addition, the file xpp/xpp_modprobe contains optional modprobe settings. @@ -55,48 +45,242 @@ It may be copied verbatim into /etc/modprobe.conf or (better) copied to Note that loading through udev is not yet provided. Run - /etc/hotplug/usb/xpp_fxloader xppdetect + /etc/hotplug/usb/xpp_fxloader load to load firmware. +The FXS calibration script requires the perl module Time::HiRes. This +modules is already packaged for most distributions including Debian, Fedora, +RedHat and CentOS. To test for the existance of this module run: + perl -MTime::HiRes -e '' -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 -the program fxload, which is typically part of the package 'fxload' or -'hotplug-utils' . +This should run cleanly (without output) if the module exists and issue +a long error message otherwise. At least in RedHat, CentOS and Fedora-2 +until Fedora-5 it is in a package named perl-Time-HiRes. In Debian and +Fedora-6 it is bundled with perl. -To load the firmware automatically using the standard hotplug script, -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 firmwares from /usr/share/zaptel/ . You can use it to load the -firmware manually. +DEVICE STARTUP: +"""""""""""""" -You should then get in lsusb the vendor ID e4e4 and device ID 2121 -(those IDs are temporary and likely to change in upcoming versions). -Once there is such a device, the xpp_usb driver should load -automatically on hot-plugging. In fact, you may find it simpler to -disconnect and reconnect the device than running 'modprobe xpp_usb'. +Terminology: +""""""""""" +Some technical terms that are used throughout the document and in the +driver / zaptel . Only used in the technical parts. +span: +Zaptel breaks the channels it knows bout to logical units called +"spans". A port in a E1/T1/ISDN card is usually a span. So is a complete +analog card. You can see the list of spans as the list of files under +/proc/zaptel or the list in zttool. -The driver has been separated into several modules: xpp.ko, xpd_fxs.ko and -xpp_usb.ko . Generally you only need to modprobe xpp_usb, and it should also -be loaded by hotplug when you connect the Astribank. However in order for it -to load xpd_fks.ko correctly +XBUS: +A funny way to call an Astribank device. -Refer to the instructions for Zaptel. After our small patches were applies, -you get xpp.ko which is basically yet another zaptel driver, like wcfxo -and wctdm. +XPD: +This is basically a logical unit of the Astribank. It will be registered to +Zaptel as a single span. This will basically be 8 analog channels. + + +Loading Firmware: +"""""""""""""""" +Normally this is done using the script xpp_fxloader.If it works fine, +you don't need to bother reading this section. +Once the firmware is loaded the USB ID of the Astribank changes to e4e4 +1132, and the driver can pick it up. You'll also see the top led lit. + +First and foremost: the simplest and most useful tool to debug problems +here is lsusb. The output of lsusb should show exactly if the device is +connected and if its firmware is loaded. + +The firmware files are named *.hex. The are in the Intel hex format +(read: plain text, but not readable) that is copied at install time from +xpp/utils to /usr/share/zaptel . + +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 is loaded in two stages. In the first stage we load the +"USB" firmware using the program fxload. After the first stage the USB +ID is e4e4 1131. In the second stage we load the "FPGA" firmware. + +The first is done using the the program fxload. To load it manually, use +the command: + + fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_1130.hex + +fxload is standard program that is typically part of the package 'fxload' +or 'hotplug-utils' . /proc/bus/usb is the mount point of the USB +file-system (usbfs). MMM is the first number (bus number) and NNN is the +second number (device number) you see for the device in lsusb, with full +3 digits. If the load is successful, the device disconnects and +reconnects with USB product ID 1131 (and a new device number). + +The second-stage loader is done using the program fpga_load, which is +built in the directory xpp/utils and installed to /usr/sbin/fpga_load . +Its syntax is based on fxload. To load with it manually, use: + + fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_FXS.hex + +Note that as the device has reconnected, it now has a new device +number. So you need to re-check the value of NNN with lsusb. Typically +this will be the old value + 1. + + +Firmware Loading with UDEV: +"""""""""""""""""""""""""" +Firmware loading with udev should work but is not installed +automatically, yet. See the comments in the beginning of the script +/etc/hotplug/usb/xpp_fxloader . + +Loading The Modules: +""""""""""""""""""" +Here is what should happen: +In short: you should plug it or have it plugged at boot time, and all +the modules should load. 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 discovered there you will see a directory +/prc/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 is the +basic one, that contains the functionality to connect to Zaptel and other +common functions. xpd_fxs is the module for controlling FXS spans. +xpd_fxo is the module for controlling FXO spans. xpd_usb is 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 only installed on-demand: no need to +install xpd_fxo if you only have FXS Astribank. + +You either plug in the Astribank , or start the hotplug/udev system +while an Astribank is connected, after the firmware is loaded. The +Vendor-ID/Product-ID of the device is e4e4/1132 . The handler for that +combination is listed as the kernel module xpp_usb . Thus the system +runs 'modprobe xpp_usb' if that module is not already loaded. + +The module xpp_usb depends on the modules zaptel and xpp . Both of which +are loaded before xpp_usb is loaded. As usual, parameters and rules form +/etc/modprobe.conf and/or /etc/modprobe.d/* will apply to the module, as +modprobe is used. + +The modules to handle the specific span types (xpd_fxs, xpd_fxo) may or +may not have been loaded yet at this stage (when the command 'modprobe +xpp_usb' returns). + +At this point the xpp driver asks the box what logical units it has. +According to the answers it gets, it will figure what xpd_* modules it will +need, and modprobe for them. At some earlier version of the driver this has +required some special modprobe.conf setup, but this is no longer +the case. + + +Device Initializations Scripts: +"""""""""""""""""""""""""""""" +The chips in the device need to be initialized. This involves sending a +bunch of values to certain registers in those chips. We decided that +hardwiring those values in the driver itself would not be a good idea. + +before registering a XPD as a span in Zaptel, we run an initialization +script: /usr/share/zaptel/initialize_registers . If this fails (e.g: +because the script is not there, or is not executable), you will get an +error message in the logs [FIXME: quote error message] that the +invocation has failed. The XPD will then be removed (you won't see that +a directory for that XPD under the relevant /proc/xpp/XBUS-* directory) +and not be registered with Zaptel. + +Registering With Zaptel: +""""""""""""""""""""""" +Now we finally got to the "lights party" part: the lights in a unit +(XPD) get lit before it registers with Zaptel and are turned off after +that. + +You may choose not to register the XPDs to Zaptel automatically, to +allow finer control of the process. This is done using the module +parameter zap_autoreg. Set in the modprobe configuration file (e.g: +/etc/modprobe.conf ) the line: + + options xpp zap_autoreg=0 + +to disable automatic registration at startup. You will then need to +register the spans manually. + + +SAMPLE CONFIGURATIONS: +"""""""""""""""""""""" + +/etc/zaptel.conf: + + Astribank 8: + + fxoks=1-14 + + Astribank 16: 8FXS/8FXO + + fxoks=1-14 + fksks=15-22 + +/etc/asterisk/zapata.conf + + Astribank 8: + + [channels] + signalling=fxo_ks + ; The real analog ports: + context=from-internal + ; echocancel=yes + ; echocancelwhenbriged=yes + ; echotraining=9 + channel => 1-8 + + ; output ports: + context=astribank-outputs + channel => 9-10 + ; input ports: + immediate=yes + context=astribank-inputs + channel => 11-14 + immediate=no + + Astribank 16: 8FXS/8FXO + + [channels] + signalling=fxo_ks + ; The real analog ports: + context=from-internal + ; echocancel=yes + ; echocancelwhenbriged=yes + ; echotraining=9 + channel => 1-8 + + ; output ports: + context=astribank-outputs + channel => 9-10 + ; input ports: + immediate=yes + context=astribank-inputs + channel => 11-14 + immediate=no + + ; FXO ports + signalling=fxs_ks + context=from-pstn + callerid=asreceived + channel => 15-22 + +See also the output of genzaptelconf for examples of mailbox and +callerid, and for channel numbers that will match your specific settings. +For that reason I only give the above two sample configurations. When loaded, you should get one span, of 8 extensions, 2 output ports and 4 input ports: root@rapid:~# cat /proc/zaptel/2 - Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS" NOTOPEN + Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS" 1 XPP_FXS/0-0 FXOKS (In use) 2 XPP_FXS/0-1 FXOKS (In use) @@ -113,36 +297,6 @@ When loaded, you should get one span, of 8 extensions, 2 output ports and 13 XPP_IN/0-12 FXOKS (In use) 14 XPP_IN/0-13 FXOKS (In use) -For such a simple case you could use: - -/etc/zaptel.conf: - -fxoks=1-14 -loadzone=us -tonezone=us - -/etc/asterisk/zapata.conf: - -[channels] -group=1 -signalling=fxo_ks -immediate=no - -context=from-internal -channels => 1-8 - -; actually they will never generate calls, so the context -; here is irrelevant -;context=outputs -channels => 9-10 - -; input ports should get an answer: -immediate=yes -context=inputs -channels => 11-14 - -;;;;;; end of zapata.conf - /proc Interface """"""""""""""" @@ -183,10 +337,10 @@ 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. +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 print tons of debugging messages. Can be sometime -- cgit v1.2.3