This file documents the Zaptel drivers for the Xorcom Astribank8 Channel Bank.
The drivers reside in a separate subdirectory, xpp/ .


Building and Installation:
"""""""""""""""""""""""""
Building and installation is basically like the normal procedure of 
installing Zaptel with some additions.

Building drivers:
""""""""""""""""
Unlike earlier versions, the Astribank driver (xpp) will now build 
automatically. To build the drivers follow the usual Zaptel
documentation. E.g: run:

  make

in the top-level directory.

Next you will need to build the user-space tools needed for loading the
firmware and initialization files for the Astribank:

  make -C xpp/utils

INSTALLATION:
""""""""""""

apart from the standard 'make install' in the zaptel directory, 
run:

  make -C xpp/utils install

Alternatively, do the following manually:

All firmware files should be copied to a new directory:
  /usr/share/zaptel/

The xpp_fxloader and xpp_fxloader.usermap should be copied to:
 /etc/hotplug/usb/

In addition, the file xpp/xpp_modprobe contains optional modprobe settings.
It may be copied verbatim into /etc/modprobe.conf or (better) copied to
/etc/modprobe.d/ .


Note that loading through udev is not yet provided. Run 

  /etc/hotplug/usb/xpp_fxloader load

to load firmware.

The FXS calibration script requires the perl module Time::HiRes. This
modules is already packaged for most distributions including Debian, Fedora,
RedHat and CentOS. To test for the existance of this module run:
  perl -MTime::HiRes -e ''

This should run cleanly (without output) if the module exists and issue
a long error message otherwise. At least in RedHat, CentOS and Fedora-2
until Fedora-5 it is in a package named perl-Time-HiRes. In Debian and
Fedora-6 it is bundled with perl.


DEVICE STARTUP:
""""""""""""""

Terminology:
"""""""""""
Some technical terms that are used throughout the document and in the
driver / zaptel . Only used in the technical parts.

span:
Zaptel breaks the channels it knows bout to logical units called
"spans". A port in a E1/T1/ISDN card is usually a span. So is a complete
analog card. You can see the list of spans as the list of files under
/proc/zaptel or the list in zttool.

XBUS:
A funny way to call an Astribank device.

XPD:
This is basically a logical unit of the Astribank. It will be registered to
Zaptel as a single span. This will basically be 8 analog channels.


Loading Firmware:
""""""""""""""""
Normally this is done using the script xpp_fxloader.If it works fine,
you don't need to bother reading this section. 
Once the firmware is loaded the USB ID of the Astribank changes to e4e4
1132, and the driver can pick it up. You'll also see the top led lit.

First and foremost: the simplest and most useful tool to debug problems
here is lsusb. The output of lsusb should show exactly if the device is
connected and if its firmware is loaded. 

The firmware files are named *.hex. The are in the Intel hex format 
(read: plain text, but not readable) that is copied at install time from 
xpp/utils to /usr/share/zaptel .

The Astribank needs a firmware loaded into it. Without the firmware, 
the device will appear in lsusb with vendor ID e4e4 and product ID 1130.
The firmware is loaded in two stages. In the first stage we load the
"USB" firmware using the program fxload. After the first stage the USB
ID is e4e4 1131. In the second stage we load the "FPGA" firmware.

The first is done using the the program fxload. To load it manually, use
the command:

  fxload -t fx2 -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/USB_1130.hex

fxload is standard program that is typically part of the package 'fxload' 
or 'hotplug-utils' . /proc/bus/usb is the mount point of the USB
file-system (usbfs). MMM is the first number (bus number) and NNN is the
second number (device number) you see for the device in lsusb, with full
3 digits. If the load is successful, the device disconnects and
reconnects with USB product ID 1131 (and a new device number).

The second-stage loader is done using the program fpga_load, which is
built in the directory xpp/utils and installed to /usr/sbin/fpga_load .
Its syntax is based on fxload. To load with it manually, use:
  
  fpga_load -D /proc/bus/usb/MMM/NNN -I /usr/share/zaptel/FPGA_FXS.hex

Note that as the device has reconnected, it now has a new device
number. So you need to re-check the value of NNN with lsusb. Typically
this will be the old value + 1.


Firmware Loading with UDEV:
""""""""""""""""""""""""""
Firmware loading with udev should work but is not installed 
automatically, yet. See the comments in the beginning of the script
/etc/hotplug/usb/xpp_fxloader .

Loading The Modules:
"""""""""""""""""""
Here is what should happen:
In short: you should plug it or have it plugged at boot time, and all
the modules should load. You will see xpp_usb , xpd_fxs and possibly
xpd_fxo in the modules list (the output of lsmod).

After the module xpp is loaded, you'll also be able to see the directory
/proc/xpp . For any Astribank discovered there you will see a directory
/prc/xpp/XBUS-n (where n is a number: typically 0). Once a unit have
been discovered you'll see subdirectories: /proc/xpp/XBUS-n/XPD-m (where
m may be another number: 0, 1 ,etc).

Now to the ugly details:

The driver of the Astribank is composed of several modules: xpp is the
basic one, that contains the functionality to connect to Zaptel and other
common functions. xpd_fxs is the module for controlling FXS spans.
xpd_fxo is the module for controlling FXO spans. xpd_usb is the module
that holds the functionality needed to connect to the USB bus.

All modules depend on xpp, and modprobing them will install xpp as well.
However the xpd_* modules are only installed on-demand: no need to
install xpd_fxo if you only have FXS Astribank.

You either plug in the Astribank , or start the hotplug/udev system 
while an Astribank is connected, after the firmware is loaded. The 
Vendor-ID/Product-ID of the device is e4e4/1132 . The handler for that
combination is listed as the kernel module xpp_usb . Thus the system
runs 'modprobe xpp_usb' if that module is not already loaded.

The module xpp_usb depends on the modules zaptel and xpp . Both of which 
are loaded before xpp_usb is loaded. As usual, parameters and rules form
/etc/modprobe.conf and/or /etc/modprobe.d/* will apply to the module, as
modprobe is used.

The modules to handle the specific span types (xpd_fxs, xpd_fxo) may or
may not have been loaded yet at this stage (when the command 'modprobe
xpp_usb' returns).

At this point the xpp driver asks the box what logical units it has.
According to the answers it gets, it will figure what xpd_* modules it will
need, and modprobe for them. At some earlier version of the driver this has
required some special modprobe.conf setup, but this is no longer
the case.


Device Initializations Scripts:
""""""""""""""""""""""""""""""
The chips in the device need to be initialized. This involves sending a
bunch of values to certain registers in those chips. We decided that
hardwiring those values in the driver itself would not be a good idea.

before registering a XPD as a span in Zaptel, we run an initialization
script: /usr/share/zaptel/initialize_registers . If this fails (e.g:
because the script is not there, or is not executable), you will get an
error message in the logs [FIXME: quote error message] that the
invocation has failed. The XPD will then be removed (you won't see that
a directory for that XPD under the relevant /proc/xpp/XBUS-* directory)
and not be registered with Zaptel.

Registering With Zaptel:
"""""""""""""""""""""""
Now we finally got to the "lights party" part: the lights in a unit
(XPD) get lit before it registers with Zaptel and are turned off after
that.

You may choose not to register the XPDs to Zaptel automatically, to
allow finer control of the process. This is done using the module
parameter zap_autoreg. Set in the modprobe configuration file (e.g:
/etc/modprobe.conf ) the line:

  options xpp zap_autoreg=0

to disable automatic registration at startup. You will then need to
register the spans manually. 


SAMPLE CONFIGURATIONS:
""""""""""""""""""""""

/etc/zaptel.conf:

  Astribank 8:

    fxoks=1-14

  Astribank 16: 8FXS/8FXO

    fxoks=1-14
    fksks=15-22

/etc/asterisk/zapata.conf

  Astribank 8:
   
    [channels]
    signalling=fxo_ks
    ; The real analog ports:
    context=from-internal
    ; echocancel=yes
    ; echocancelwhenbriged=yes
    ; echotraining=9
    channel => 1-8

    ; output ports:
    context=astribank-outputs
    channel => 9-10
    ; input ports:
    immediate=yes
    context=astribank-inputs
    channel => 11-14
    immediate=no
  
  Astribank 16: 8FXS/8FXO
   
    [channels]
    signalling=fxo_ks
    ; The real analog ports:
    context=from-internal
    ; echocancel=yes
    ; echocancelwhenbriged=yes
    ; echotraining=9
    channel => 1-8

    ; output ports:
    context=astribank-outputs
    channel => 9-10
    ; input ports:
    immediate=yes
    context=astribank-inputs
    channel => 11-14
    immediate=no

    ; FXO ports
    signalling=fxs_ks
    context=from-pstn
    callerid=asreceived
    channel => 15-22

See also the output of genzaptelconf for examples of mailbox and 
callerid, and for channel numbers that will match your specific settings.
For that reason I only give the above two sample configurations.

When loaded, you should get one span, of 8 extensions, 2 output ports and 
4 input ports:

  root@rapid:~# cat /proc/zaptel/2 
  Span 1: XBUS-0/XPD-0 "Xorcom XPD #0/0: FXS"

           1 XPP_FXS/0-0 FXOKS (In use) 
           2 XPP_FXS/0-1 FXOKS (In use) 
           3 XPP_FXS/0-2 FXOKS (In use) 
           4 XPP_FXS/0-3 FXOKS (In use) 
           5 XPP_FXS/0-4 FXOKS (In use) 
           6 XPP_FXS/0-5 FXOKS (In use) 
           7 XPP_FXS/0-6 FXOKS (In use) 
           8 XPP_FXS/0-7 FXOKS (In use) 
           9 XPP_OUT/0-8 FXOKS (In use) 
          10 XPP_OUT/0-9 FXOKS (In use) 
          11 XPP_IN/0-10 FXOKS (In use) 
          12 XPP_IN/0-11 FXOKS (In use) 
          13 XPP_IN/0-12 FXOKS (In use) 
          14 XPP_IN/0-13 FXOKS (In use) 


/proc Interface
"""""""""""""""
The Astribank drivers provide their own /proc interface under /proc/xpp .
(Note that the details of this interface are still potentially subject to 
changes)

/proc/xpp/xbuses lists the connected devices (an xbus is such a device), 
one per line. A device is normally "connected". "missing" means that it
was disconnected, but Asterisk still holds channels from it open. You can
also see in the xbuses file to which physical connection the Astribank
is connected.

/proc/xpp/sync is a read/write file . It prints the current
synchronization source. printing to it can change the synchronization
source. Host-synchronization is currently the default but for better
sound quality you should synchronize from the Astribank.

/proc/xpp/XBUS-n gives information about device number n (starting from
0). under it, /proc/XBUS-n/XPD-m gives information regarding span number
m in that device.

/proc/xpp/XBUS-n/XPD-m/zt_registration is a read-write file for
manually registering/unregistering the span with Zaptel. A span will 
register automatically when generated, though. Span unregistration may
fail if some channels from the span are used (e.g: by Asterisk).
Registration is by writing 1 and unregistration is by writing 0 to the
file.

(There are a bunch of other status files under /proc/xpp/ )


Useful Module Parameters:
""""""""""""""""""""""""
zap_autoreg: (xpp)
Register spans automatically (1) or not (0). Default: 1. 
Unsetting this could be useful if you have several Astribanks and you 
want to set their registration order manually using zt_registration in 
the /proc interface.

initdir: (xpp)
This is the directory containing the initialization scripts.
The default is /usr/share/zaptel .
Setting this value could be useful if that location is inconvenient for you.

print_dbg: (all modules)
It will make the driver print tons of debugging messages. Can be sometime 
even handy, but overly-verbose in the case of xpp_usb. Can be safely 
set/unset at run-time using /sys/modules .



BTW: XPP here does not stand for X Printing Panel, XML Pull Parser, 
X-Windows Phase Plane or XML Professional Publisher. It is simply the 
Xorcom Peripheral Protocol, which connects a computer to a XPD (Xorcom 
Peripheral Device).
