From 084f390a94c247d31d1ec296121ef7c7d3c4d0e1 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/linux/trunk@5402 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- drivers/dahdi/xpp/README.Astribank | 1362 ------------------------------------ 1 file changed, 1362 deletions(-) delete mode 100644 drivers/dahdi/xpp/README.Astribank (limited to 'drivers/dahdi/xpp') diff --git a/drivers/dahdi/xpp/README.Astribank b/drivers/dahdi/xpp/README.Astribank deleted file mode 100644 index 1918268..0000000 --- a/drivers/dahdi/xpp/README.Astribank +++ /dev/null @@ -1,1362 +0,0 @@ -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