From 7b47ea30547963a48f5baf470d03acc0bb1b28a7 Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Thu, 27 Nov 2008 09:54:59 +0000 Subject: Moving README.Astribank to dahdi-tools . git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@5402 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- xpp/README.Astribank | 1362 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1362 insertions(+) create mode 100644 xpp/README.Astribank diff --git a/xpp/README.Astribank b/xpp/README.Astribank new file mode 100644 index 0000000..1918268 --- /dev/null +++ b/xpp/README.Astribank @@ -0,0 +1,1362 @@ +Xorcom Astribank Documentation +============================== +Xorcom Team +$Revision$, $Date$ + +This file documents the Dahdi drivers for the Xorcom Channel Bank. +The drivers reside in a separate subdirectory, kernel/xpp/ . + +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://docs.tzafrir.org.il/dahdi-linux/README.Astribank.html[] + +Building and Installation +------------------------- +Building and installation is basically like the normal procedure of +installing Dahdi with some additions. + +Building drivers +~~~~~~~~~~~~~~~~ +Apart from the standard Dahdi build requirements, you also need libusb +development headers to build the fpga_load firmware loader. This is +typically the package libusb-dev on Debian (and derivatives like Ubuntu) +or libusb-devel on RedHat (and derivatives like CentOS/Trixbox). + +Sample Configurations +--------------------- +We generally recommend to generate the configuration by using utility +genzaptelconf or zapconf which are included with Dahdi. Nevertheless, +the following can serve as reference configurations for a system where +Astribank devices are used. + + +xpp.conf: Astribank Initialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +/etc/dahdi/xpp.conf is read by the initialization modules of dahdi +scripts. +----------------------------------------------------------- +# /etc/dahdi/xpp.conf +# +# This file is used to configure the operation +# of init_card_* initialization scripts. +# + +# Adds many more tracing messages that are sent to syslog: +#debug 1 + +# xpd_pri: E1 or T1. The default is E1 for all the ports. +# Setting T1 instead: +#pri_protocol T1 +# +# Or if you actually want to mix E1 and T1: +#pri_protocol/xbus-00/xpd-02 T1 +#pri_protocol/connector:usb-0000:00:1d.7-7/xpd-03 T1 +#pri_protocol/label:usb:0000183/xpd-03 T1 +# If several definitions can refer to a port, the last wins. +# If none applies, the default of E1 holds. + +# Don't run power calibration on the FXS units. This can save time +# but can also get you unit randomly disconnect, if badly used: +#fxs_skip_calib 1 + +# FXO: country to adjust settings to: +#opermode ISRAEL +----------------------------------------------------------- + +///////////////////////////////////////////// +TODO: genconf_parameters, init.conf: need documentation? +///////////////////////////////////////////// + +/etc/dahdi/system.conf +~~~~~~~~~~~~~~~~~~~~~~ + +Astribank 8 +^^^^^^^^^^^ + fxoks=1-14 + +Astribank 6FXS/2FXO +^^^^^^^^^^^^^^^^^^^ + fxoks=1-12 + fxsks=13-14 + +Astribank 16: 8FXS/8FXO +^^^^^^^^^^^^^^^^^^^^^^^ + fxoks=1-14 + fxsks=15-22 + +Astribank 4 BRI +^^^^^^^^^^^^^^^ + # Assumed ports settings: + # Ports 1,3: TE + # Ports 2,4: NT + span=1,1,1,ccs,ami + span=2,0,1,ccs,ami + 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 + +Astribank 4 PRI E1 +^^^^^^^^^^^^^^^^^^ + # Assumed ports settings: + # Ports 1,3: TE (CPE) + # Ports 2,4: NT (Net) + span=1,1,1,ccs,hdb3,crc4 + span=2,0,1,ccs,hdb3,crc4 + span=3,2,1,ccs,hdb3,crc4 + span=4,0,1,ccs,hdb3,crc4 + bchan=1-15,17-30,31-45,47-60,61-75,77-90,91-105,107-120 + dchan=16,46,76,106 + +Astribank 4 PRI T1 +^^^^^^^^^^^^^^^^^^ + # Assumed ports settings: + # Ports 1,3: TE (CPE) + # Ports 2,4: NT (Net) + span=1,1,1,esf,b8zs + span=2,0,1,esf,b8zs + span=3,2,1,esf,b8zs + span=4,0,1,esf,b8zs + bchan=1-23,25-47,49-71,73-95 + dchan=24,48,72,96 + + +/etc/asterisk/chan_dahdi.conf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Astribank 8 +^^^^^^^^^^^ + [channels] + signalling=fxo_ks + ; The real analog ports: + context=from-internal + echocancel=yes + ; echocancelwhenbriged=yes + ; echotraining=no + channel => 1-8 + + ; output ports: + context=astbank-output + channel => 9-10 + ; input ports: + immediate=yes + context=astbank-input + channel => 11-14 + immediate=no + +Astribank 6FXS/2FXO +^^^^^^^^^^^^^^^^^^^ + [channels] + signalling=fxo_ks + ; The real analog ports: + context=from-internal + echocancel=yes + ; echocancelwhenbriged=yes + ; echotraining=no + channel => 1-6 + + ; output ports: + context=astbank-output + channel => 7-8 + ; input ports: + immediate=yes + context=astbank-input + channel => 9-12 + immediate=no + + ; FXO ports + signalling=fxs_ks + context=from-pstn + callerid=asreceived + channel => 13-14 + +Astribank 16: 8FXS/8FXO +^^^^^^^^^^^^^^^^^^^^^^^ + [channels] + signalling=fxo_ks + ; The real analog ports: + context=from-internal + echocancel=yes + ; echocancelwhenbriged=yes + ; echotraining=no + channel => 1-8 + + ; output ports: + context=astbank-output + channel => 9-10 + ; input ports: + immediate=yes + context=astbank-input + channel => 11-14 + immediate=no + + ; FXO ports + signalling=fxs_ks + context=from-pstn + callerid=asreceived + channel => 15-22 + +Astribank 4 BRI +^^^^^^^^^^^^^^^ + ; Assumed ports settings: + ; Ports 1,3: TE + ; Ports 2,4: NT + [channels] + switchtype = euroisdn + callerid = asreceived + + ; TE ports: + signalling = bri_cpe_ptmp + ;signalling = bri_cpe + context = from-pstn + group = 1,11 + channel => 1,2 + + group = 1,13 + channel => 7,8 + + ; NT ports: + signalling = bri_net_ptmp + ;signalling = bri_net + context = from-internal + group = 2,12 + channel => 4,5 + + group = 2,14 + channel => 10,11 + +Astribank 4 PRI E1 +^^^^^^^^^^^^^^^^^^ + ; Assumed ports settings: + ; Ports 1,3: TE + ; Ports 2,4: NT + [channels] + switchtype = euroisdn + callerid = asreceived + + ; TE ports: + signalling = pri_cpe + context = from-pstn + group = 1,11 + channel => 1-15,17-30 + + group = 1,13 + channel => 61-75,77-90 + + ; NT ports: + signalling = pri_net + ;signalling = pri_net + context = from-internal + group = 2,12 + channel => 31-45,47-60 + + group = 2,14 + channel => 91-105,107-120 + +Astribank 4 PRI T1 +^^^^^^^^^^^^^^^^^^ + ; Assumed ports settings: + ; Ports 1,3: TE + ; Ports 2,4: NT + [channels] + switchtype = national + callerid = asreceived + + ; TE ports: + signalling = pri_cpe + context = from-pstn + group = 1,11 + channel => 1-23 + + group = 1,13 + channel => 49-71 + + ; NT ports: + signalling = pri_cpe + ;signalling = pri_net + context = from-internal + group = 2,12 + channel => 25-47 + + group = 2,14 + channel => 73-95 + + +/etc/asterisk/extensions.conf +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sample dialplan (extensions.conf) for all the above: + +----------------------------------------------------------- +[phones-dahdi] +; With Asterisk 1.4 you will may need to use here 'Zap' instead of +; DAHDI. See Zaptel-to-DAHDI.txt . +; +; 6001 will dial to channel 1, 6020, to Dahdi channel 20, etc. +exten => _6XXX,1,Dial(DAHDI/${EXTEN:1}) +; Useful for debugging trunks. Will potentially allow users to +; bypass context limitations. +;exten => _6XXX.,1,Dial(DAHDI/${EXTEN:1:3}/${EXTEN:4}) + +[trunk] +; A number that begins with 9: dial it through a trunk +; (we put FXO channels and TE channels in group 0). +; The leading 9 is stripped. +exten => _9.,1,Dial(DAHDI/g0/${EXTEN:1}) +; dialing a number that begins with 83 will dial it through +; span 3, and so forth. The two leading digits are stripped. +; (Each digital span is also added to group 10+span number). +exten => _8X.,1,Dial(DAHDI/g1${EXTEN:1:1}/${EXTEN:2}) + +[from-internal] +; The context of FXS ports: analog phones. +; They are allowed to dial to all other phones +include => phones-zap +; They are also allowed to call through the trunk: +include => trunk +; some simple tests: +include => astbank-test + +[from-pstn] +; Calls from the PSTN enter here. Redirect calls to an IVR +; or a default extension in the s context here. In this case we +; redirect calls to Dahdi channel 1: +exten => s,1,Dial(DAHDI/1) + +; Alternatively, the following will redirect you to the demo IVR +; from the sample extensions.conf of Asterisk: +include => demo + +; An extra context with some simple tests +[astbank-test] +; 200: echo test +exten => 200,1,Answer +exten => 200,n,Wait(1) +exten => 200,n,Echo() +exten => 200,n,Hangup + +; 203: say extension number. Will only work if caller ID +; is properly set in zapata.conf / zapata-channels.conf +exten => 203,1,Answer +exten => 203,n,Wait(1) +exten => 203,n,SayNumber(${CALLERID(num)}) +exten => 203,n,Hangup + +[astbank-input] +exten => s,1,Set(DAHDI_CHAN=${CUT(CHANNEL,-,1)}) +exten => s,n,Set(DAHDI_CHAN=${CUT(DAHDI_CHAN,/,2)}) +; 11 is the number of the first input port. At least in the sample +; configuration below. +;exten => s,n,Set(INPUT_NUM=$[${DAHDI_CHAN}-11)]) +; The sample below just logs the signal. +exten => s,n,NoOp(Got signal from Dahdi Channel ${DAHDI_CHAN}) +; Alternatively: +;exten => s,n,System(run something) + +; No. We did not forget the context astbank-outputs. Output +; ports only get calls from the PBX. Thus they don't need a context +; of their own. Sending them to a context of their on makes +; 'zap show channels' in the CLI provide useful display, though. +----------------------------------------------------------- + + + + +Troubleshooting +--------------- +The following commands provide useful information for debugging: + +lsusb Test +~~~~~~~~~~ +Check USB level status. You can use one of the following utilities for it: + + dahdi_hardware -v + or + lsusb | grep e4e4 + +- Look for the USB Product ID (the second number after e4e4). +- If you see *11x2* (e.g: 1152)- the FPGA firmware has been loaded. + Move on. + dahdi_hardware will also show you some more details if the driver + 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. 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 + fpga_load. Make sure you have libusb-dev(el) installed when + building Dahdi. After you have installed it, you may need to re-run + ./configure . +- It should list all of your Astribank devices. If it doesn't (for + more than period of time needed for the initial firmware + loading) - Check that the Astribank is connected indeed. + + +DAHDI Registration +~~~~~~~~~~~~~~~~~~ +Check if the Astribank spans are registered in DAHDI: + + dahdi_registration + +- This should give useful results after the drivers have identified + and your devices are initialized. +- It should list all Astribank XPDs. For each of them it should write + "on" or "off". If the registration status is "off", then it means that + the span has not been registered in Dahdi and therefore can not be used + yet. +- Registration is normally done as part of `/etc/init.d/dahdi start`. + If you want to register the spans manually, then run command: + `dahdi_registration on` . +- Disabling of the automatic Astribank spans registration give you full + control on the order of Dahdi spans. See the module parameter + **zap_autoreg** for the further details. + + +DAHDI Level Information +~~~~~~~~~~~~~~~~~~~~~~~ +You can get some information regarding Dahdi channels by running one of the +following commands: + + lsdahdi + or + cat /proc/dahdi/* + +- Those two are almost the same. The lsdahdi produced more correctly sorted + output if you have more than 10 spans, and also make the output listing + looks a little bit nicer. +- You can see if your Dahdi spans and channels were loaded, if + they were configured by dahdi_cfg and if they are in use (typically by + Asterisk). + For example: + Not configured Astribank FXS channel will be displayed as: + + 42 FXS + +- When a channel has been configured with *dahdi_cfg* (that applies + /etc/dahdi/system.conf), you will see an extra column for the signalling + type of the channel. The same channel after it has been configured: + + 42 FXS FXOKS + +- If a program (which is typically Asterisk) uses it, you'll see: + + 42 FXS FXOKS (In use) + + + +Asterisk Level Information +~~~~~~~~~~~~~~~~~~~~~~~~~~ + asterisk -rx 'dahdi show channels' + +- If you get error "Unable to connect to remote asterisk" then it + means that the Asterisk is not running. It is possible that Asterisk + has failed to start due to misconfigured zapata.conf or whatever reason. + Check /var/log/asterisk/messages or /var/log/asterisk/full . +- If you get the error that "there is no such command" then it means that + chan_zap.so is not loaded. There are two reasons for such problem: + * chan_zap.so is not even built. Check if the file exists: + + ls -l /usr/lib/asterisk/modules/chan_dahdi.so + + * the chan_zap.so file exists but it is not loaded. Try to load it manually: + + asterisk -rx 'load module chan_dahdi.so' + +- You see "pseudo" channel only. It means that you have not configured any + channels. If you have configured channels in zapata.conf, you may + need either to restart the Asterisk or unload/load chan_zap.so manually. + You can use the following Asterisk CLI commands for it: `unload chan_zap.so` + and `load chan_zap.so` + + +Known Issues +~~~~~~~~~~~~ +Empty /proc dir +^^^^^^^^^^^^^^^ +.Symptoms: +- Error message: + + "ERR-xpd_fxo: XBUS-00/XPD-00: Failed initializing registers (-22)" + +- Likewise for all XPDs. +- The directory /proc/xpp exists but is empty (not even the files + 'xbuses' and 'sync'). + +.Cause: +The driver failed to recreate the procfs directory /proc/xpp and hence +everything under it. This is because it has already existed. And it +existed because a process still uses it. This is typically because you +have a shell whose working directory is /proc/xpp or somewhere under +it: + + # lsof /proc/xpp + COMMAND PID USER FD TYPE DEVICE SIZE NODE NAME + bash 2741 root cwd DIR 0,3 0 4026532684 /proc/xpp + +.Fix: +Move that process from that directory, or close the file it uses from +under /proc/xpp and reload the dahdi / xpp drivers. + + +Bad Firmware Version +^^^^^^^^^^^^^^^^^^^^ +.Symptoms: +- An Astribank finishes initialization quickly, the /proc/XBUS-nn + directory has no XPD-mm subdirectories. +- Error in the kernel logs about: + + NOTICE-xpp: XBUS-00: XPD at 00: type=6.0 has bad firmware revision 2.6 + +.Cause: +This is normally caused by an Astribank with an older firmware connected +to a + +The protocol version supported by the firmware will typically be the same +one as in the device initialization scripts installed to +/usr/share/dahdi . Hence if this version installed +`/usr/share/dahdi/init_card_3_29` it will probably include firmware of +protocol version 29. + +.Fix: +Reset the firmware: + + /usr/share/dahdi/xpp_fxloader reset + +Or disconnect the Astribank from the power and reocnnect. On some older +versions of the USB firmware resetting the firmware (or any operation of +fpga_load) would fail if the driver is loaded. Hence you would need to +run `rmmod xpp_usb` . In the end, reload the drivers. + + +USB Errors at Shutdown +^^^^^^^^^^^^^^^^^^^^^^ +.Symptoms: +You see USB-related errors similar to the following whenever you shut +down the drivers of the Astribank or disconnect its drivers: + + ERR-xpp_usb: XBUS-00: Failed to submit a receive urb + +.Cause: +This is a normal part of the shutdown of the USB connection. + +.Fix: +Ignore them. Unless the USB should not have disconnected at that time. + + +BRI Layer 1 Down +^^^^^^^^^^^^^^^^ +.Symptoms: +With the BRI module only, and not in the middle of an active call, you +notice that suddenly the line goes down. The LED of the port stops +blinking, layer1 not listed as "active" in the bri_info file in +/proc/xpp, and the span is in RED alarm in Dahdi. + +You may also see an error message such as: + + NOTICE-xpd_bri: XBUS-00/XPD-02: D-Chan RX Bad checksum: [2A:01=FC] (252) + +from the exact time of the disconnecting. + +.Cause: +This is expected with most european BRI PtMP providers. If they support +PtMP, they are normally also expected to support ISDN phones, that get +the power from the provider. And thus they shut down the line whenever +there's no active call. + +Sometimes the line is shut down in the middle of a layer 2 message. In +the BRI driver the HDLC decoding/encoding is done in the card. In that +case we may get the above error. + +.Fix: +Normaly this is not a problem. The driver will re-establish a connection +once a new call needs to be made. + + +Both default and sysconfig Exist +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.Symptoms: +The firmware fails to load. Manually running xpp_fxloader gives: + + Both '/etc/default/zaptel' and '/etc/sysconfig/zaptel' exist + +Alternatively: an initialization script fails and gives the error + + An '/etc/default/zaptel' collides with 'etc/sysconfig/zaptel' + +.Cause: +/etc/default/ is the place used in Debian-based +systems for initialization scripts. /etc/sysconfig/ is +used in Redhat and similar for the same purpose. For historical reasons +many of our programs read configuration from there: either from +/etc/default/zaptel or from /etc/sysconfig/zaptel . + +The problem is what to do if both of those exist. Selecting an arbitrary +one can lead to unexpected results. Likewise sourcing both of them. +Therefore we prefer to fail in a noisy and expected way. In the future +we will probably me to reading configuration from a file under /etc/dahdi . + +.Fix: +Remove one of those two. There should be no reason to have both on the +same system. + + +Astribank not initialized: Premature packet end +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.Symptoms: +After upgrading to Zaptel 1.4.12 / 1.2.25 the initialization of the +Astribank times out. In the logs you see: + + kernel: NOTICE-xpp: XBUS-00(00): FIRMWARE: ERROR_CODE CODE = 0x3 (Premature packet end) + +.Cause: +When an Astribank is detected, the driver asks it what is its version +and what components it has. Normally if the version of the firmware and +of the driver does not match the driver gives an ugly message and fails +the initialization. + +However in the change of the protocol between versions 2.9 (29) and 3.0 +(30), the response that the new driver recieves from a device with the +old version is now considered to be an illegal packet and gets +discarded. As a result, the Astribank waits till time-out for the +initilization to end. + +.Fix: +Reset the firmware of the Astribank by either: + + /usr/share/dahdi/xpp_fxloader reset + +or disconnecting it from the power and reconnecting it. + + +Reference +--------- +LEDs Indication +~~~~~~~~~~~~~~~ +The Astribank has 4 global indication leds and one or two per-port leds. +On some of the models the LEDs are located on the left side on the front +panel. If there are no separate LEDs there, then the red LEDs of the +upper left-most ports of the device are used as the indication LEDs. Don't +confuse them with green port status LEDs. + +The first led is the "Power" led. It is on if the unit gets power. +The second led is the "Active" led, which is on when there is at +least one "active" port (in a call / off-hook, though the meaning of this is +different in BRI). +The last led is called "Hardware OK", but is actually only is on in case of +the hardware failure. + +The third led is the "Sync" led. If it blinks, the device is synchronized +with the driver on the computer. If the device is selected to be the +synchronization source for all of the Astribank devices then it will blink +a quick single blink. +If the device gets synchronization from the driver, it will blink in a +more steady frequency. + +"Double blink" indicates that the unit has an FXO module, and still is +getting synchronization from the computer, and is not the synchronization +source. + +The per-port green led on analog (both FXS and FXO) indicates that the +port is off-hook. + +On the BRI, the green led indicates a TE port whereas an orange led +indicates an NT port. If the led is solid, the port is down (not even +layer-1 connection is up). If it is blinking a double blink, layer 1 +is up. A slower single blinking indicates that layer 2 is up as well +(which means that Asterisk is driving the port). + + +PRI Ports Configuration +~~~~~~~~~~~~~~~~~~~~~~~ +Astribank PRI module has two RJ-45 sockets for each PRI port. The lower +socket provides typical PRI CPE side wiring: Rx- pins 1,2; Tx - pins +4,5. The upper socket provides typical PRI Network side wiring: Rx- pins +4,5; Tx - pins 1,2. The both sockets are permanently active and you can +use any of them regardless of any configuration parameters (Both +connectors are live. And connecting both of them with a flat 8-wire +ethernet cable is a simple way to do a loop test for the port). + + +For each port there are two optional parameters that define its +behavior: + +Each port in the PRI module can be configured either as E1 or T1. The +port type defaults to E1 and can be changed to T1 in the Dahdi Init +Configuration File. + +The Astribank xpp driver uses that information for correct hardware +initialization that is performed before the Dahdi span registration +process takes place. Because of that, xpp driver can't use the +information from file /etc/dahdi/system.conf. + +Another parameter that also can be defined in the Dahdi Init +Configuration File is the function group TE (CPE) or NT (Network). This +parameter is used for (a) building correct Dahdi & Asterisk +configuration by genzaptelconf and (b) control RJ-45 sockets LEDs for +better visual port control: + +A port in the PRI module can be either E1 (default) or T1. It can also be +either "TE" (default) or "NT". + +TE:: + Green LED of the lower socket will light. Hint that this is a TE + (CPE) port. This is the default. + +NT:: + Orange LED of the upper socket will light. Hint that this is an + NT (network) port. + +////////////////////////////////////////////////// +FIXME: Update for DAHDI +////////////////////////////////////////////////// +To set them to a non-default value, you should use the variable +XPP_PRI_SETUP in the +xref:dahdi_init_configuration_file[Dahdi Init Configuration File] +(/etc/sysconfig/zaptel on Redhats, /etc/default/zaptel on Debians). +This value is a whitespace-separated list of conditions. When a port is +initialized it checks those conditions and uses the first one that +matches. + +Match expressions may be: +- CONNECTOR/usb..../XPD-nn To identify by physical connector +- NUM/XBUS-mm/XPD-nn To identify by bus number + +Match expressions may contain "wildcards": + +- * matches zero or more characters. +- ? matches one charater +- [xyz] - any of 'x', 'y', or 'z'. + +For each line you should define both if it is E1 or T1 and if it is NT +or TE. + +The list implicitly contains an 'NUM/*=TE,E1' catch all default, appended +to its end. + +A number of useful examples. Note that you should use just one of them. +--------------------------------------------- +# All ports are E1 and CPE +#XPP_PRI_SETUP= #no need to set it + +# All ports are T1 and CPE: +XPP_PRI_SETUP='NUM/*=T1,TE' + +# Now you want to test a loop between ports 1 and 2 and between +# port 3 and 4. So let's make ports 2 and 4 network: +XPP_PRI_SETUP='NUM/*/XPD-0[24]=E1,NT' + +# The same with T1. In this case we also need to set the default of all +# the others to T1. Note that we can use more than one item and the +# first one that matches counts: +XPP_PRI_SETUP=' + NUM/*/XPD-0[24]=T1,NT + NUM/*=T1,TE +' + +# Actually, there is an implicit 'NUM/*=E1,TE' added to the end of the +# value and set as the value if there is none. This is how the default +# is set. + +# If you have more than one Astribank and you wish to configure +# different Astribanks differently, you can use the CONNECTOR option: +# e.g: set one specific Astribank as E1 network. The others default to +# E1 CPE: +XPP_PRI_SETUP='CONNECTOR/usb-0000:00:10.4-4/*=E1,NT' + +# Theoretically you could use: XPP_PRI_SETUP='NUM/XBUS-01/*=E1,NT' +# but the XBUS number depends on the specific load order and is thus +# might differ in a manual load and a system boot. +--------------------------------------------- + +This is currently implemented by writing a value to the +xref:_proc_xpp_xbus_nn_xpd_mm_pri_info[pri_info file in procfs], but +that may change in future versions. + + +Device Startup +~~~~~~~~~~~~~~ +This section describes in great depth the initialization of the Xorcom +Astribank. Normally it would not be really needed, as the standard +installation of Dahdi should put everything in place. + +Terminology +^^^^^^^^^^^ +There are some technical terms that are used in this document and in the +driver / dahdi. + +span: +Dahdi 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/dahdi directory or in output of the dahdi_tool +utility. + +XBUS: +A funny way to call an Astribank device. + +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 (FXS or FXO) +module or a single port in case of a BRI module. + + +Loading Firmware +^^^^^^^^^^^^^^^^ +Normally this is done using the script /usr/share/dahdi/xpp_fxloader. +If it works fine, you don't need to bother reading this section. +Once the firmware is loaded the USB Vendor ID and Product ID of the Astribank +became to be e4e4 11x2, and now the driver can pick it up. + +First and foremost: the simplest and most useful tool to debug problems +is lsusb. The output of lsusb should show you if the device is connected +if its firmware is loaded. + +The firmware files are named *.hex. They are presented in the text +hexadecimal format The files are copied from xpp/utils to /usr/share/dahdi +folder during the Dahdi 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 1130. +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 1131. + +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/dahdi/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). +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 +(and a new device number). + +In the second stage, the "FPGA" firmware is loaded. +The second-stage firmware loading is performed by using program fpga_load, +which is built in the directory xpp/utils and then copied to folder +/usr/sbin during Dahdi installation. + +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/dahdi/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 +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. + + +Firmware Loading with Hotplug +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The Hotplug framework was popular for hot-plugging different devices and +usually also for automatic device drivers loading. If Hotplug is used in +your system, you'll see many files in folder /etc/hotplug. Hotplug will +automatically load the most relevant USB and PCI kernel modules according +to the USB and PCI IDs provided by devices. Please note, that if the +Hotplug framework is in place and the correct configuration files are +located in the right place, then the firmware should be loaded automatically. + +In order to get the Hotplug framework to load the firmware into the +Astribank automatically, the configuration file xpp_fxloader.usermap and +the script xpp_fxloader should be copied into /etc/hotplug/usb/ . This is +done by 'make -C xpp/utils install'. + +File xpp_fxloader.usermap includes a map of USB IDs and the command to run +when such devices are encountered. It instructs the Hotplug to run the script +xpp_fxloader from that directory. This is also done by 'make -C +xpp/utils install' . + +When xpp_fxloader is run without any parameters it assumes that it was +run by the hotplug scripts. Then it will check if the "add" event was +accepted and if so, xpp_fxloader will install the required firmware file. +The xpp_fxloader will be called twice, as after the load of the USB +firmware the device will re-enumerate itself and thus "unplug" and +"replug" in order to load the FPGA firmware. + + +Firmware Loading with UDEV +^^^^^^^^^^^^^^^^^^^^^^^^^^ +The UDEV framework has replaced Hotplug in most recent systems. If you +have a recent 2.6 system without Hotplug and with many files in folder +/etc/udev, then there are good chances that are you using udev. +As in case of Hotplug, if your udev framework is configured properly +then the firmware should be loaded automatically. + +In order to get udev to automatically load the firmware into the Astribank, +the configuration file xpp.rules should be copied into folder /etc/udev/rules.d +and the script xpp_fxloader should be copied into folder /etc/hotplug/usb/ . +This is done by 'make -C xpp/utils install' during Dahdi installation. + +File xpp.rules instructs the udevd daemon to run xpp_fxloader script with +the option "udev" and with the Astribank USB ID obtained from the +device when it is plugged in. +Please note, that exactly like in case of Hotplug, the xpp_fxloader will be +called twice by the udevd. First time for the USB firmware loading and the +second time for FPGA firmware loading. + + +Firmware Resetting +^^^^^^^^^^^^^^^^^^ +Newer versions of the USB firmware can now be reset using 'fpga_load -r'. + +Also you can try the following: + + /usr/share/dahdi/xpp_fxloader reset + # if asterisk was running: you may need to stop/restart it now. + # if there are some "disconnected" spans in /proc/xpp/xbuses + # wait a while, until you see the 1152 IDs again, and then: + /etc/init.d/dahdi start + # and start/restart asterisk. + + +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 +(the output of lsmod). + +After the module xpp is loaded, you'll also be able to see the directory +/proc/xpp. For any Astribank device discovered, you will see there a +directory /proc/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 - the basic module, that communicates with Dahdi and provides + some common services to other modules. +* xpd_fxs - the module for controlling FXS modules. +* xpd_fxo - the module for controlling FXO modules. +* xpd_bri - the module for controlling BRI modules. +* xpd_pri - the module for controlling E1/T1 modules. +* xpp_usb - 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 installed on-demand: no need to install +the 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 +combination is listed as the kernel module xpp_usb. Therefore, the system +runs 'modprobe xpp_usb' if that module is not already loaded. + +The module xpp_usb depends on the dahdi and xpp modules. Both of them +are loaded before xpp_usb. As usual, parameters and rules form +/etc/modprobe.conf and/or from /etc/modprobe.d/* will be applied to +the module. + +When command 'modprobe xpp_usb' returns, the span type specific modules +(e.g., xpd_fxs, xpd_fxo) may or may not have been loaded yet. + +At this point the xpp driver "asks" the box about its software +(firmware) version) and the type of telephony modules it has. According +to the answers it receives, the xpp driver will "modprobe" the required +xpd_* modules. + + +Device Initializations Scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The chips in the device need to be initialized. This requires sending a +bunch of values to certain registers in those chips. We decided that +hardwiring those values in the driver code is not a good idea. +Before registering a XPD as a span in Dahdi, we run an initialization +script: /usr/share/dahdi/init_card_N_MM ( +where, + +* N - is 1 for an FXS span and 2 for an FXO span, 3 for BRI and 4 for PRI. +* MM - is a version number. Currently it equals 30. + +Those scripts must be executable. Funny things happen if such a script +exists but is not executable. + +If because of some reasons this fails (the script is not in the place, or the +file doesn't have the executable permissions), then you will get an error +message in the logs and the XPD will then be removed (you won't see directory +for that XPD under the corresponding /proc/xpp/XBUS-* directory) and will not +be registered in Dahdi. + +As the XPD is initialized, you'll see the green LEDs of the ports steadily +turn on and later off ("a train of lights"). This is a bit slower than the +faster "blinking" when the XPDs register as Dahdi spans. The initialization +of an FXS XPD may take a few seconds. + + +Registering in DAHDI +^^^^^^^^^^^^^^^^^^^^ +The XPDs will not automatically register as Dahdi spans. This is +intended to allow you to set the registration order (and hence the order +of Dahdi spans and channels) among multiple Astribank devices, +or between an Astribank and a different Dahdi device. + +When the XPD registers to Dahdi, all the green LEDs will be lit for a +short while. + +Spans are normally registered with the utility dahdi_registration. Simply +running 'dahdi_registration' shows the available XPDs and whether or not +they are registered. To register: + + dahdi_registration on + +For a system with several spans you'll see a "fast train of lights". + +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.. + +dahdi_registration checks if a span is registered or tries to register a +span using the file /proc/xpp/XBUS-nn/XPD-mm/dahdi_registration . Reading +from that file returns 0 if the span is unregisters or 1 if it is +registered. You can register a span or ask to unregister it by writing 1 +(register) or 0 (unregister) to that file. Registration should +generally always succeed. Unregistration may fail if a span is in use. + +You may choose to register the XPDs in Dahdi automatically. This may +make the startup sequence a bit simpler, but is generally not +recommended on a system with more than one Astribank or an Astribank and +a different Dahdi device. This behavior may be defined by setting +parameter zap_autoreg in the modprobe configuration file (A file under +/etc/modprobe.d or /etc/modprobe.conf): + + options xpp zap_autoreg=1 + + +DAHDI And Above +^^^^^^^^^^^^^^^ +From here you get a standard Dahdi span. It still needs to be +configured by dahdi_cfg and used by a program such as Asterisk like any +other Dahdi device. In order for you to get a dial-tone in a phone +connected to the FXS port or a fully synchronized BRI port (layer 2 +activated, as signalled by a more steady blink) you will actually need +both the span configured by Dahdi and the channels configured in +Asterisk. + +You should generally refer to the general Dahdi documentation on how to +configure those levels. e.g, the README file in the top-level directory, +and + + http://voip-info.org/wiki/view/Asterisk+config+zapata.conf[] + + +Dahdi now includes a utility called genzaptelconf (written as a big +ugly shell script) to configure Dahdi automatically as good as +possible. For analog channels it works quite well (because, IMHO, the +"configuration" level on Dahdi should be optional there - there are +already sane defaults). For digital spans - BRI and PRI , it may take +some tuning. + +Alternatively, write you own configuration, based on the sample from the +"Sample Configurations" section. + + +/proc Interface +~~~~~~~~~~~~~~~ +The Astribank drivers provide their own /proc interface under /proc/xpp. +Here we review the more useful details of the procfs interface. There +are many other debugging details that are exposed through the procfs +interface. + +Also note that those details are subject to changes. Generally the +recommended stable interface are the Dahdi-perl utilities from the +xpp/utils directory. + + +/proc/xpp/xbuses +^^^^^^^^^^^^^^^^ +File /proc/xpp/xbuses lists the connected Astribank devices (one line +per device). + +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 +source. You can change the synchronization source by writing special +command to the file. For example, command + echo SYNC=01 > /proc/xpp/sync + +Possible values are: + +:: + Make the Astribank XBUS- the sync source for other Astribanks. + +DAHDI:: + Make the Astribanks synchronize with the Dahdi timing master span. + You probably need this to get faxes from a non-Astribank adapter to an + Astribank. + +Though you'll normally use xpp_sync(8) for that. + +For each Astribank device there is folder /proc/xpp/XBUS-nn and for each device +module (span in the terms of Dahdi) there is folder /proc/XBUS-nn/XPD-mm. + + +/proc/xpp/XBUS-nn/waitfor_xpds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Reading from this file only returns when the Astribank has finished +initialization of the XPDs or in case of a timeout. It prints the number +of XPDs to initialize, and the number initialize. Unless something went +wrong, those two numbers are the same. Once the span was initialized, +reading from this file returns immediately: + + XPDS_READY: XBUS-00: 3/3 + + +/proc/xpp/XBUS-nn/XPD-mm/dahdi_registration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +is a read/write file. Reading from it gives 0 if the span is +unregistered, or the span number if it is registered. + +Writing to it allows manual registration / unregistration from Dahdi: +writing 1 registers a span (if it wasn't already registered) and writing +0 attempts to unregister it (if it is registered. Span unregistration +will fail if some channels from the span are used (e.g: by Asterisk). + +A more convenient interface to this is the command dahdi_registration that +registers or unregisters all the spans at once with a predefined order, +and this is what you should normally use. + +Alternatively you can use the parameter zap_autoreg to register spans +automatically. But this is only recommended on a system with a single +Astribank and no other Dahdi device. + + +/proc/xpp/XBUS-nn/XPD-mm/summary +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Contains detailed information about port statuses of the device module +(off-hook, on-hook etc.) For example, you can run the following command +in order to monitor the port statuses in the real time: + + watch -n1 cat /proc/xpp/XBUS-00/XPD-00/summary + + +/proc/xpp/XBUS-nn/XPD-mm/slics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Provides direct read/write interface to the registers of each chip. +Reading from the file shows the result of the last read request. To make +either a read request or a write request you need to write to that file. + +It is mainly used by the initialization scripts (card_init_*). + +Incorrect usage of this file is one possible way of damaging the +Astribank. + + +/proc/xpp/XBUS-nn/XPD-mm/fxo_info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Only for FXO modules. Apart from showing the status of the LEDs, it also +shows for each FXO port if it is connected to a provider: look for the +value of "battery" for that specific port, and a bunch of other +characteristics of the port. + + +/proc/xpp/XBUS-nn/XPD-mm/bri_info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 +the Layer 1 port statuses for all BRI devices in the real time: + + watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/bri_info' + +For the status of the D channel of the ports on all BRI spans, run: + + watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/bri_info' + + +/proc/xpp/XBUS-nn/XPD-mm/pri_info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 +the Layer 1 port statuses for all E1/T1 devices in the real time: + + watch -n1 -d 'grep "Layer 1:" /proc/xpp/XBUS-*/XPD-*/pri_info' + +For the status of the D channel of the ports on all PRI spans, run: + + watch -n1 -d 'grep D-Channel: /proc/xpp/XBUS-*/XPD-*/pri_info' + +Note: the layer 2 status is much more of a guesswork based on changes in +the contents of the channel that is supposed to be the D channel. + +Writing to this file can be used to change the type of the device. The +device type can only be changed when the XPD is not registered as a +Dahdi span. The value is a whitespace-separated list of values that can +be of: + +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. + +TE:: + Use the bottom port (green LED) and don't invert any wiring. Hint to + higher layers that this will be the TE side of the connection. This is + the default setup. + +NT:: + Use the top port (orange LED) and invert wiring (this is done to allow + connecting an NT port and a TE port using a standard straight 8 wires + "ethernet" cable). Hint to higher layers that this will be the NT side + of the connection. + +LOCALOOP:: + Set the device into local loop mode: loops the transmitted channels + directly into the received channels. + +NOLOCALLOOP:: + Ends local loop mode. + +Normally those are set by the PRI initialization script . See the +definition of XPP_PRI_SETUP in +xref:dahdi_init_configuration_file[the sample Dahdi init +configuration file] . + + +There are a bunch of other status files under /proc/xpp/. + + +/sys Interface +~~~~~~~~~~~~~~ +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/dahdi/astribank_hook with the +parameter 'add' or 'remove', if such script exists. An example script +that just adjusts the Astribank sync settings is included in xpp/utils. + +cls:: + CLear Statistics: writing to this file clear the procfs statistics for + this bus. + +connector:: + Connector string for the device. The place to which the Astribank is + connected. e.g: usb-0000:00:03.3-2 + +label:: + The label string of the Astribank unit. E.g: usb:00000135 + +status:: + 'connected' (normal operation) or 'disconnected' (has been disconnected, + some channels are still open). + +timing:: + Provides some statistics in case the Astribank is not the sync source. + The format of this file is subject to future changes. + + +Useful Module Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ +Compilation-time defaults for the all modules can be shown as part of the +description line for the parameter in the "modinfo" command output. + +zap_autoreg (xpp):: + Register spans automatically (1) or not (0). Default: 0. + Setting it simplifies operations with a single Astribank and no other + Dahdi hardware. However if you have such systems, automatic + registration can cause the order of spans to be unpredictable. + The standard startup scripts use 'dahdi_registration on' instead of this. + +initdir (xpp):: + This is the directory containing the initialization scripts. + The default is /usr/share/dahdi . + Setting this value could be useful if that location is inconvenient for you. + +rx_tasklet (xpp):: + Enable (1) or disable (0) doing most of the packets processing in + separate tasklets. This should probably help on higher-end systems with + multiple Astribanks. + +debug (all modules):: + It will make the driver to print tons of debugging messages. You can + set/unset the parameter at run-time. The parameter value is a bitmask + of several values. The different bits meaning as it defined in + xpp/zap_debug.h: + + * 0 - Disable debug messages + * 1 - GENERAL - General debug comments. + * 2 - PCM - PCM-related messages. Tends to flood logs. + * 4 - LEDS - Anything related to the LEDs status control. The driver + produces a lot of messages when the option is enabled. + * 8 - SYNC - Synchronization related messages. + * 16 - SIGNAL - Dahdi signalling related messages. + * 32 - PROC - Messages related to the procfs interface. + * 64 - REGS - Reading and writing to chip registers. Tends to flood + logs. + * 128 - DEVICES - Device instantiation, destruction and such. + * 256 - COMMANDS - Protocol commands. Tends to flood logs. + + For example, + + echo 33 >/sys/modules/xpp/parameters/debug + + forces module xpp to print general debugging messages (1) and procfs + debugging messages (32). + +vmwineon (xpd_fxs):: + Enable (1) or disable (0) sending the voicemail message waiting indication + signal to phones equipped with the Message Waiting neon lamp. It is + disabled by default because the feature requires extra work of the driver + even when such a phone is not used and also may cause some unusual + side effects with some phone models. + +usb1 (xpp_usb):: + Enable (1) or disable (0) support of USB1 devices. Disabled by default. + + USB1 devices are not well-tested. It seems that they don't work at all + for Astribank BRI. Generally they should work with the current code, but + we expect the voice quality issues. Hence we would like to make it + very clear that you if you have a USB1 port (rather than a USB2 one, as + recommended) you will have to take an action to enable the device. + +poll intervals (various):: + There are various values which the driver occasionally polls the device + for. For instance, the parameter poll_battery_interval for xpd_fxo + to poll the battery, in order to know if the telco line is actually + connected. + + The value of those parameters is typically a number in milliseconds. + 0 is used to disable polling. Under normal operation there should be + no reason to play with those parameters. + +dtmf_detection (xpd_fxs):: + Enable (1) or disable (0) support of hardware DTMF detection by the + Astribank. + + +NOTE: XPP here does not stand for X Printing Panel, XML Pull Parser, +X-Windows Phase Plane or XML Professional Publisher. It is simply the +Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom +Peripheral Device). An XBUS (originally XPP Bus) is actually a single +Astribank device and the XPDs have become the single modules in it. -- cgit v1.2.3