diff options
Diffstat (limited to 'kernel/xpp/README.Astribank')
| -rw-r--r-- | kernel/xpp/README.Astribank | 189 |
1 files changed, 161 insertions, 28 deletions
diff --git a/kernel/xpp/README.Astribank b/kernel/xpp/README.Astribank index 6fd0deb..435d78a 100644 --- a/kernel/xpp/README.Astribank +++ b/kernel/xpp/README.Astribank @@ -57,6 +57,11 @@ user space utilities, apart from the standard 'make; make install': Patch for BRI ~~~~~~~~~~~~~ +(In latest SVN version of Zaptel this patch is no longer needed. Furthermore, it does +not apply. The same directory has a newer patch that applies. This +section is kept in the document for the time being for the benefit of +those with older versions) + In order for the BRI module (xpd_bri.ko) to build, you still need an external patch: @@ -77,7 +82,7 @@ Installation Scenarios ~~~~~~~~~~~~~~~~~~~~~~ Below are some commented sequences of commands that can be used at some common scenarios. Those scenarios begin only after you installed the -software (Zaptel, asterisk, etc.). +software (zaptel, asterisk, etc.). New Installation Scenario ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -210,6 +215,69 @@ modules: #fxs_skip_calib 1 ----------------------------------------------------------- +xpp_order: Explicitly order Astribanks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +(This feature is available in latest Zaptel SVN) + +On a system with multiple Astribank you would normally want to guarantee +that Astribanks are registered in the same order regardless of the order +in which they are connected or detected. Assuming that you register them +all at the same time. In order to do that, you should list the +Astribanks explicitly under /etc/xpp_order . + +Astribanks that are listed there are registered first (according to the +order of lines in the files). Astribanks not listed there are added +last, and sorted by the 'USB connector' string. + +You can identify an Astribank in two ways: + +Label:: + each Astribank (except some really old ones) has a label . This + identifies the actual Astribank box. + +Connector:: + Identify the path the Astribank is connected through. E.g.: to what + USB port you connected it. + +Identifying an Astribank by the label seems simpler and more +predictable. Though it may have some slightly surprising effects if +replace one Astribank with another. + +The sample configuration file: +----------------------------------------------------------- +# +# This is an optional configuration file for ordering +# Zaptel registration. +# +# It is read from /etc/xpp_order. This location +# may be overriden via the environment variable XPPORDER_CONF +# +# Lines may contain: +# - The Astribank label (verbatim) +# - The Astribank connector string (prefixed with @) +# Ordering number of each listed Astribank is determined +# by its position in this file. +# Astribanks not listed in this file, get an ordering +# number of 99 (last). +# +# Astribanks with same ordering number are sorted by their +# connectors (to preserve legacy behaviour). +# +# Examples: +#usb:1234 +#@usb-0000:06:02.2-2 +----------------------------------------------------------- + + +In order to generate one that includes all the Astribanks in the system +with the current order in which they are connected, use: + + zapconf xpporder + +For more technical details see the section <<_registering_in_zaptel>> +below. + + /etc/zaptel.conf ~~~~~~~~~~~~~~~~ @@ -237,7 +305,9 @@ Astribank 4 BRI span=3,2,1,ccs,ami span=4,0,1,ccs,ami bchan=1-2,4-5,7-8,10-11 - dchan=3,6,9,12 + ; if you applied the bri_dchan patch: + ;dchan=3,6,9,12 + hardhdlc=3,6,9,12 Astribank 4 PRI E1 ^^^^^^^^^^^^^^^^^^ @@ -865,7 +935,7 @@ There are some technical terms that are used in this document and in the driver / zaptel. span:: - Dahdi breaks the channels it knows about to logical units called + Zaptel breaks the channels it knows about to logical units called "spans". A port in a E1/T1/ISDN card is usually a span. An whole analog card is also a "span". You can see the list of spans as the list of files under /proc/zaptel directory or in output of the dahdi_tool @@ -876,7 +946,7 @@ XBUS:: XPD:: Basically this is a logical unit of the Astribank. It will be - registered in Dahdi as a single span. This can be either an analog + registered in Zaptel as a single span. This can be either an analog (FXS or FXO) module or a single port in case of a BRI module. @@ -897,30 +967,31 @@ during the Zaptel installation. The Astribank needs a firmware loaded into it. Without the firmware, the device will appear in lsusb with Vendor ID e4e4 and Product ID 11x0 -(1130, 1140 or 1150). The firmware loading process consists of two stages. -In the first stage the "USB" firmware is loaded by using program fxload. -When the first stage is completed the Vendor ID is e4e4 and the Product ID -is 11x1. (e.g. 1151 if it were 1150 previously). +(1130, 1140, 1150 or 1160). The firmware loading process consists of two +stages. In the first stage the "USB" firmware is loaded by using program +fxload. When the first stage is completed the Vendor ID is e4e4 and the +Product ID is 11x1. (e.g. 1151 if it were 1150 previously). You can use the following command in order to load the "USB" firmware manually: - fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_FW.hex + fxload -t fx2 -D /dev/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_FW.hex where, fxload:: A standard program that is typically part either of package 'fxload' or 'hotplug-utils' . -/proc/bus/usb:: - The mount point of the USB file-system (usbfs). +/dev/bus/usb:: + On some old systems it is missing . /proc/bus/usb (usbfs) could be + used instead. MMM:: the first number (bus number) NNN:: the second number (device number) you see for the device in lsusb If the loading process has been completed successfully, the device -disconnects and then connects again itself with USB Product ID 1131 +disconnects and then connects again itself with USB Product ID 11x1 (and a new device number). In the second stage, the "FPGA" firmware is loaded. @@ -931,7 +1002,20 @@ which is built in the directory xpp/utils and then copied to folder The command syntax is similar to the syntax of fxload. You can use the following command in order to load the FPGA firmware manually: - fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_1151.hex + # pick the right name according to the device ID. FPGA_1161.hex is for + # 116x Astribanks: + astribank_hexload -D /dev/bus/usb/MMM/NNN -F /usr/share/zaptel/FPGA_1161.hex + # Note the shell expantion in this line: + astribank_hexload -D /dev/bus/usb/MMM/NNN -p /usr/share/zaptel/PIC_TYPE_[1-4].hex + # reenumerate (disconnect and reconnect) + astribank_tool -D /dev/bus/usb/MMM/NNN -n + +With older USB firmwares before the one included in DAHDI 2.2 or latest +Zaptel SVN, you needed to use instead of all the above: + + # pick the right name according to the device ID. FPGA_1151.hex is for + # 115x Astribanks: + fpga_load -D /dev/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_1151.hex Please note, that NNN value differs from that that was used for the fxload command due to the fact that device has "reconnected" itself @@ -939,9 +1023,8 @@ with another Product ID number. So you need to run lsusb again and get the new NNN value. Usually, the new value is equal to the old value incremented by 1. -On newer systems usbfs (/prob/bus/usb) is replaced by basically the same -structure under /dev/bus/usb . Note, however, that zaptel_hardware still -relies on some data from usbfs that is not found in /dev/usb . +On newer systems (e.g. Centos 4) /dev/bus/usb may not be available. In +that case, use /proc/bus/usb . usbfs should be mounted there. Automatic Firmware Loading @@ -985,6 +1068,14 @@ usb 7-1: reset high speed USB device using ehci_hcd and address 46 INFO-xpp_usb: XUSB: Xorcom LTD -- Astribank -- FPGA ------------------------------------- +Another useful tool for tracing UDEV-related issue is the udev monitor: + + udevadm monitor + +Or with some older versions of udev: + + udevmonitor + Firmware Loading with Hotplug ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1007,7 +1098,7 @@ Loading The Modules Here is what should happen: In short: you should plug the Astribank device(s) or have them plugged in at the boot time. Then all the modules should be loaded automatically. -You will see xpp_usb , xpd_fxs and, possibly, xpd_fxo in the modules list +You will see xpp_usb, xpp, and some xpd_* modules in the modules list (the output of lsmod). After the module xpp is loaded, you'll also be able to see the directory @@ -1021,7 +1112,7 @@ Now to the ugly details: The driver of the Astribank is composed of several modules: xpp:: - The basic module, that communicates with Dahdi and provides some + The basic module, that communicates with Zaptel and provides some common services to other modules. xpd_fxs:: FXS modules (analog phones). Module type 1. @@ -1039,7 +1130,7 @@ However the xpd_* modules are installed on-demand: no need to load xpd_fxo if you have only Astribank FXS. Once an Astribank device connected and the firmware is loaded, the -Vendor-ID/Product-ID of the device will be e4e4/1132 . The handler for that +Vendor-ID/Product-ID of the device will be e4e4/11x2 . The handler for that combination is listed as the kernel module xpp_usb. Therefore, the system runs 'modprobe xpp_usb' if that module is not already loaded. @@ -1075,7 +1166,13 @@ NOTICE-xpp: xproto_get: Failed to load module for type=3. exit status=256. NOTICE-xpp: XBUS-00: CARD 0: missing protocol table for type 3. Ignored. -------------------------------------------------- In this case it was because I maliciously removed the module xpd_bri -(type 3) from the system. +(type 3) from the system. + +This can also happen if you accidentally blacklist the relevant xpd-* +module. 'blacklist some_module' in modprobe.conf or modprobe.d/*.conf +means that a direct insmod or modprobe of their name will work, but any +attempt to load a module through its aliases will fail. Recall that the +cpd-* modules are loaded on-demand using the alias 'xpd-type-N' . Device Initializations Scripts @@ -1111,11 +1208,8 @@ Connect / Disconnect Hook When the Astribank has finished initialization it also notifies userspace applications. This can be used to run a custom command when an Astribank is connected (after it has finished initialization) or when it -has disconnected. - -To use that you need to comment-out the last line in the udev rules file -xpp.rules. A sample hook script is included in -kernel/xpp/utils/astribank_hook.sample . +has disconnected. The hook script is installed by default to +/usr/share/zaptel/astribank_hook . Registering in Zaptel @@ -1136,7 +1230,7 @@ they are registered. To register: For a system with several spans you'll see a "fast train of lights". -"If you have multiple Astribank devices, zt_registration will +If you have multiple Astribank devices, zt_registration will register them by the ascending order of the USB connector ID. This means that as long as the same Astribank is connected to the same port, the order of plugging is not important. @@ -1161,11 +1255,13 @@ usb:004/007 xpp_usb+ e4e4:1152 Astribank-multi FPGA-firmware If you have multiple Astribank devices, dahdi_registration will register them by the order of the "connector" field. This means that as long as the same Astribank is connected to the same port, the order of plugging -is not important. +is not important. Alternatively you can set an explicit registration +order using /etc/dahdi/xpp_order . See above in section about +<<_xpp_order_explicitly_order_astribanks,xpp_order>>. The registration is performed through the sysfs interface. See below <<_sys_devices_xpp_xbus_nn_nn_m_p_span,the span attribute>>. Also note -that dahdi_registration also allows you to unregister spans, which will +that zt_registration also allows you to unregister spans, which will work for all spans that are not in use (That is: none of their channels is in use). @@ -1185,6 +1281,19 @@ parameter <<_zap_autoreg>> in the modprobe configuration file (A file under options xpp zap_autoreg=1 +Astribanks Synchronization Source +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If there is more than one Astribank on the system, all the Astribanks +keep their clock in sync. Optionally the Astribanks can synchronize +their clock to the master Zaptel device (in case it is a different Zaptel +device). Normally you just use the default init.d script or run +explicitly: + + xpp_sync auto + +(For now see the man page of xpp_sync for more information) + + Zaptel And Above ^^^^^^^^^^^^^^^^ From here you get a standard Zaptel span. The next step is to configure @@ -1325,6 +1434,10 @@ For the status of the D channel of the ports on all BRI spans, run: /proc/xpp/XBUS-nn/XPD-mm/pri_info ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +(In latest SVN this file is read-only. The writetable functionality +moved in part (E1/T1) to pri_protocol sysfs and in part (NT/TE) to +zaptel.conf settings) + In addition to the usual information about the LEDs, this file also provides useful information regarding ISDN Layer 1 and Layer 2 status. For example, you can run the following command in order to monitor @@ -1526,6 +1639,26 @@ easily see all the XPDs of the same type, as they are linked again from the driver's directory. +===== /sys/bus/astribanks/devices/xbus-NN/NN:M:P/pri_protocol +Can have either of those two: + +E1:: + Provides 31 channels, of which channel 16 is normally the D-channel. + Common in places outside of North America and Japan. This is the + default setup. + +T1:: + T1 provides 24 channels. The last one is normally the D-Channel. + Common in North America. + +This can also be set by writing the strings explicitly to the file. But +can only be done when an XPD is not a registered span. + +This writing is normally done by the device initialization script, based +on the 'pri_protocol' settings in +xref:_xpp_conf_astribank_initialization[/etc/xpp.conf] . + + Useful Module Parameters ~~~~~~~~~~~~~~~~~~~~~~~~ Compilation-time defaults for the all modules can be shown as part of the |