~ubuntu-branches/ubuntu/quantal/zaptel/quantal

« back to all changes in this revision

Viewing changes to README

  • Committer: Bazaar Package Importer
  • Author(s): Tzafrir Cohen
  • Date: 2008-08-28 22:58:23 UTC
  • mfrom: (11.1.11 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080828225823-r8bdunirm8hmc76m
Tags: 1:1.4.11~dfsg-2
* Patch xpp_fxs_power: Fixed an issue with hook detection of the Astribank
  FXS module.
* Don't fail init.d script if fxotune fails. This may happen if running it
  when Asterisk is already running.
* Bump standards version to 3.8.0.0 .
* Ignore false lintian warning ("m-a a-i" has "a a").
* Patch xpp_fxo_cid_always: do always pass PCM if that's what the user
  asked.
* Patch vzaphfc_proc_root_dir: fix vzaphfc on 2.6.26.
* Patch wcte12xp_flags: Proper time for irq save flags.
* Patch headers_2627: Fix location of semaphore.h for 2.6.27 .
* Patch xpp_fxs_dtmf_leak: Don't play DTMFs to the wrong channel.
* Patch wctdm_fix_alarm: Fix sending channel alarms.
* Patch device_class_2626: Fix building 2.6.26 (Closes: #493397).
* Using dh_lintian for lintian overrides, hence requiring debhelper 6.0.7.
* Lintian: we know we have direct changes. Too bad we're half-upstream :-(
* Fix doc-base section names. 

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
Zapata Telephony Interface Driver
2
 
 
3
 
Note:
4
 
See
5
 
http://www.voip-info.org/tiki-index.php?page=Asterisk%20Zaptel%20Installation
6
 
for more verbose and updated version of this document.
7
 
 
8
 
Requirements:
9
 
        Some of the testing programs still require the zapata library
10
 
        The zttool program requires libnewt
11
 
 
12
 
To install:
13
 
        check zconfig.h for any specific configuration changes
14
 
        make
15
 
        make install
16
 
 
17
 
Here is a list of what module to use with what hardware
18
 
 
19
 
Module Name     Hardware
20
 
tor2            T400P - Quad Span T1 Card
21
 
                E400P - Quad Span E1 Card
22
 
 
23
 
wct4xxp         TE405P - Quad Span T1/E1 Card (5v version)
24
 
                TE410P - Quad Span T1/E1 Card (3.3v version)
25
 
 
26
 
wct1xxp         T100P - Single Span T1 Card
27
 
                E100P - Single Span E1 Card
28
 
 
29
 
wcte11xp        TE110P - Single Span T1/E1 Card
30
 
 
31
 
wcfxo           X100P - Single port FXO interface
32
 
                X101P - Single port FXO interface 
33
 
 
34
 
wctdm or        TDM400P - Modular FXS/FXO interface (1-4 ports)
35
 
wcfxs
36
 
 
37
 
wcusb or        S100U - Single port FXS USB Interface
38
 
wcfxsusb        
39
 
 
40
 
torisa          Old Tormenta1 ISA Card
41
 
 
42
 
ztdummy         UHCI USB Zaptel Timing Only Interface
 
2
=================================
 
3
Asterisk Development Team <asteriskteam@digium.com>
 
4
$Revision: 4289 $, $Date: 2008-05-14 14:18:06 -0500 (Wed, 14 May 2008) $
 
5
 
 
6
Zaptel is a short for ZAPata TELephony.
 
7
 
 
8
Supported Hardware
 
9
------------------
 
10
Digital Cards
 
11
~~~~~~~~~~~~~
 
12
- wct4xxp:
 
13
  * Digium TE205P/TE207P/TE210P/TE212P: PCI dual-port T1/E1/J1
 
14
  * Digium TE405P/TE407P/TE410P/TE412P: PCI quad-port T1/E1/J1
 
15
  * Digium TE220: PCI-Express dual-port T1/E1/J1
 
16
  * Digium TE420: PCI-Express quad-port T1/E1/J1
 
17
- wcte12xp:
 
18
  * Digium TE120P: PCI single-port T1/E1/J1
 
19
  * Digium TE121: PCI-Express single-port T1/E1/J1
 
20
  * Digium TE122: PCI single-port T1/E1/J1
 
21
- wcte11xp:
 
22
  * Digium TE110P: PCI single-port T1/E1/J1
 
23
- wct1xxp: 
 
24
  * Digium T100P: PCI single-port T1
 
25
  * Digium E100P: PCI single-port E1
 
26
- tor2: Tormenta quad-span T1/E1 card from the Zapata Telephony project
 
27
- torisa: The old dual-span ISA T1 card from Zapata Telephony
 
28
 
 
29
 
 
30
Analog Cards
 
31
~~~~~~~~~~~~
 
32
- wctdm24xxp: 
 
33
  * Digium TDM2400P/AEX2400: up to 24 analog ports
 
34
  * Digium TDM800P/AEX800: up to 8 analog ports
 
35
  * Digium TDM410: up to 4 analog ports
 
36
- wctdm:
 
37
  * Digium TDM400P: up to 4 analog ports
 
38
- xpp: Xorcom Astribank: a USB connected unit of up to 32 ports
 
39
  (includeing the digital BRI and E1/T1 modules)
 
40
- wcfxo: X100P, similar and clones. A simple single-port FXO card
 
41
- wcusb: Digium S100U: A simple single-port USB FXS unit
 
42
 
 
43
 
 
44
Other Drivers
 
45
~~~~~~~~~~~~~
 
46
- pciradio: Zapata Telephony PCI Quad Radio Interface
 
47
- wctc4xxp: Digium hardware transcoder cards (also need zttranscode)
 
48
- ztd-eth: TDM over Ethernet (TDMoE) driver. Requires ztdynamic
 
49
- ztd-loc: Mirror a local span. Requires ztdynamic
 
50
- ztdummy: A dummy driver that only provides a zaptel timing source.
 
51
 
 
52
 
 
53
Build Requirements
 
54
------------------
 
55
You will need a matching kernel source tree and a working Linux build 
 
56
system. Some of the programs require some additional libraries.
 
57
 
 
58
The script install_prereq should help you install the
 
59
required packages. To see what it suggests, run:
 
60
 
 
61
  ./install_prereq test
 
62
 
 
63
You can either copy/paste that code to a terminal to run it, or just
 
64
run:
 
65
 
 
66
  ./install_prereq install
 
67
 
 
68
 
 
69
Kernel Source / "Headers"
 
70
~~~~~~~~~~~~~~~~~~~~~~~~~
 
71
- Building zaptel requires a kernel build tree.
 
72
- This should basically be at least a partial kernel source tree and
 
73
  most importantly, the exact kernel .config file used for the build as
 
74
  well as several files generated at kernel build time.
 
75
- KERNEL_VERSION is the output of the command `uname -r`
 
76
- If you build your own kernel, you need to point to the exact kernel
 
77
  build tree. Luckily for you, this will typically be pointed by the
 
78
  symbolic link /lib/modules/KERNEL_VERSION/build which is the location
 
79
  zaptel checks by default.
 
80
- If you use a kernel from your distribution you will typically have a
 
81
  package with all the files required to build a kernel modules for your
 
82
  kernel image.
 
83
  * On Debian Etch and above and any Ubuntu this is
 
84
    +++ linux-headers-`uname -r` +++
 
85
  * On Fedora, RHEL and compatibles (e.g. CentOS) this is the
 
86
    kernel-devel package. Or if you run kernel-smp or kernel-xen, you
 
87
    need kernel-smp-devel or kernel-xen-devel, respectively.
 
88
  * On SUSE you seem to need the package kernel-source .
 
89
  * In some distributions (e.g.: in RHEL/CentOS, Fedora, Ubuntu) the 
 
90
    installation of the kernel-devel / kernel-headers package will 
 
91
    be of a version that is newer than the one you currently run. In 
 
92
    such a case you may need to upgrade the kernel package itself as 
 
93
    well and reboot.
 
94
- To point explicitly to a different build tree: set KSRC to the kernel 
 
95
  source tree and KVERS to the exact kernel version:
 
96
 
 
97
  make KVERS=2.6.18.Custom KSRC=/home/tzafrir/kernels/2.6.18
 
98
 
 
99
 
 
100
Kernel Configuration
 
101
~~~~~~~~~~~~~~~~~~~~
 
102
If you build a custom kernel, note the following configuration items:
 
103
 
 
104
- CONFIG_CRC_CCITT must be enabled ('y' or 'm'). On 2.6 kernels this can 
 
105
  be selected These can be selected from the "Library Routines" submenu 
 
106
  during kernel configuration via "make menuconfig".
 
107
- If you don't have any zaptel hardware, you need ztdummy. ztdummy takes
 
108
  its timing from the kernel. It can use either of the following:
 
109
  * ztdummy on i386/x86_64 with kernels >= 2.6.22 can (and should) use 
 
110
    high resolution times (CONFIG_HIGH_RES_TIMERS), and (if available, 
 
111
    the system HPET. This shows as "source: HRTimer". This is
 
112
    recommended.
 
113
  * ztdummy on i386/x86_64 and later kernels (>= 2.6.15) can use the 
 
114
    system's RTC (Real Time Clock). This shows as "source: RTC".
 
115
  * Failing that, on Linux 2.6 kernels with HZ=1000 (was the default
 
116
    before 2.6.13). This shows as "source: Linux26".
 
117
  * Alternatives to that for ztdummy are a UHCI USB controller (USB
 
118
    controllers made by Intel or VIA) or a kernel that has HZ=1000
 
119
    (default on kernels 2.6.0-2.6.12, optional on newer kernels. Not
 
120
    possible on 2.4). This shows as: "source: UHCI".
 
121
 
 
122
 
 
123
A Build System
 
124
~~~~~~~~~~~~~~
 
125
gcc and friends. Generally you will need to install the package gcc.
 
126
There may be cases where you will need a specific version of gcc to build
 
127
kernel modules.
 
128
 
 
129
 
 
130
Extra Libraries
 
131
~~~~~~~~~~~~~~~
 
132
Some libraries are needed for extra utilities that are provided with
 
133
Zaptel
 
134
 
 
135
- libusb is needed for building fpga_load, needed for firmware loading of
 
136
  the Xorcom Astribank.
 
137
- libnewt is needed to build the optional but useful utility zttool.
 
138
 
 
139
 
 
140
Distribution-Specific Instructions
 
141
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
142
==== Debian 4.0 (Etch)
 
143
  apt-get install linux-headers-`uname -r` build-essential libnewt-dev libusb-dev
 
144
 
 
145
==== Debian 3.1 (Sarge)
 
146
  apt-get install kernel-headers-`uname -r` build-essential libnewt-dev libusb-dev
 
147
 
 
148
==== RHEL4 / CentOS 4
 
149
You need the following non-kernel-related packages:
 
150
 
 
151
  yum install gcc newt-devel libusb-devel
 
152
 
 
153
If the following command produces an error, you need to install
 
154
the kernel devel package:
 
155
 
 
156
  ls /lib/modules/`uname -r`/build/.config
 
157
 
 
158
The right one depends on your kernel version. If the following command
 
159
produces output you have an SMP kernel:
 
160
 
 
161
  uname -r | grep smp
 
162
 
 
163
and thus need to run:
 
164
 
 
165
  yum install kernel-smp kernel-smp-devel
 
166
 
 
167
If that command produced no output, you have a non-SMP kernel:
 
168
 
 
169
  yum install kernel kernel-devel
 
170
 
 
171
At this point you should probably reboot to get the new kernel in effect.
 
172
 
 
173
 
 
174
Installation
 
175
------------
 
176
Note: If using `sudo` to build/install, you may need to add /sbin to your PATH.
 
177
----------------------------------
 
178
./configure
 
179
# optional step: select custom configuration:
 
180
#make menuconfig
 
181
make
 
182
make install
 
183
# To install init scripts and config files:
 
184
#make config
 
185
----------------------------------
 
186
 
 
187
 
 
188
Build Tweaks
 
189
~~~~~~~~~~~~
 
190
Selecting Modules and Utilities
 
191
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
192
You can select the modules and utilities you wish to build and firmwares
 
193
you wish to download by running `make menuselect` . The selection of modules 
 
194
that you build (or rather: not build) is saved in the file 
 
195
`menuselect.makeopts`. 
 
196
 
 
197
 
 
198
Extra Modules
 
199
^^^^^^^^^^^^^
 
200
To build extra modules / modules directory not included in the Zaptel 
 
201
distribution, use the optional variables MODULES_EXTRA and
 
202
SUBDIRS_EXTRA:
 
203
 
 
204
  make MODULES_EXTRA="mod1 mod2"
 
205
  make MODULES_EXTRA="mod1 mod2" SUBDIRS_EXTRA="subdir1/ subdir1/"
 
206
 
 
207
Note that those names are not guaranteed to continue to work on newer
 
208
versions. Hopefully there will be no need for such extra configuration.
 
209
 
 
210
Partial Build/Install
 
211
^^^^^^^^^^^^^^^^^^^^^
 
212
There are some make targets that are provided to build or install just
 
213
parts of Zaptel:
 
214
 
 
215
. Build targets:
 
216
  - make modules: build just the kernel modules.
 
217
  - make programs: Build just the Zaptel userspace programs. partial 
 
218
    targets of it:
 
219
    * make 'utilname': builds 'utilname' alone (e.g: `make ztdiag`)
 
220
    * make utils: Build libtonezone.
 
221
    * make libs: Build libtonezone.
 
222
. Install targets:
 
223
  - make install-modules: install just kernel modules.
 
224
  - make firmware: download and install firmwares for Digium cards
 
225
  - make install-programs: Userspace: Partial targets of it are:
 
226
    * make install-utils: install Zaptel userspace programs and
 
227
      and basic support files.
 
228
    * make install-libs: install libtonezone
 
229
    * make install-include: install zaptel.h
 
230
  - make config: should be run once to configure 
 
231
 
 
232
Building to a Subtree
 
233
^^^^^^^^^^^^^^^^^^^^^
 
234
The following may be useful when testing the package or when preparing a
 
235
package for a binary distribution (such as an rpm package) installing
 
236
onto a subtree rather than on th real system. 
 
237
 
 
238
  make install DESTDIR=targetdir
 
239
 
 
240
This can be useful for any partial install target of the above (e.g:
 
241
install-modules or install-programs).
 
242
 
 
243
the targetdir must be an absolute path, at least if you install the
 
244
modules. To install to a relative path you can use something like:
 
245
 
 
246
  make install-modules DESTDIR=$PWD/target
 
247
 
 
248
The 'install' target might fail if run as a user to a DESTDIR when
 
249
attempting to generate device files. In that case, try:
 
250
 
 
251
  make install DESTDIR=$PWD/target DYNFS=
 
252
 
 
253
 
 
254
Test Install: live_zap
 
255
^^^^^^^^^^^^^^^^^^^^^^
 
256
If you need to test a version of Zaptel without touching the version
 
257
installed on your system, you can use the script live_zap . Note,
 
258
however, that it may take some extra configuration to be used right.
 
259
 
 
260
Basic usage:
 
261
 
 
262
  ./configure
 
263
  make
 
264
  ./live_zap install # instead of 'make install'
 
265
  ./live_zap config  # instead of 'make config'
 
266
  ./live_zap unload  # instead of '/etc/init.d/zaptel stop'
 
267
  ./live_zap load    # instead of '/etc/init.d/zaptel start'
 
268
 
 
269
Everything is installed under the subdirectory live/ . You will probably
 
270
need to adjust MODULES . Generally you should not edit the script
 
271
itself, but , rather, edit live/live.conf . Please let me know if you
 
272
needed to change anything in the script beyond changing live.conf so I
 
273
can include useful fixes.
 
274
 
 
275
Testing on a different maching:
 
276
 
 
277
  ./configure
 
278
  make
 
279
  ./live_zap install # instead of 'make install'
 
280
  ./live_zap config  # instead of 'make config'
 
281
  ./live_zap rsync root@remotehost
 
282
  ssh root@remotehost
 
283
  # in the remote host:
 
284
  cd /tmp
 
285
  ./live_zap unload
 
286
  ./live_zap load
 
287
 
 
288
 
 
289
./configure Options
 
290
^^^^^^^^^^^^^^^^^^^
 
291
The configure script various several tests and based on them generates
 
292
some files ( build_tools/menuselect-deps and makeopts). You can pass it
 
293
--with options and variable settings, for instance:
 
294
 
 
295
  ./configure --without-ncurses CC="gcc-4.10"
 
296
 
 
297
If you just want to recreate the same files without a full detection
 
298
run, use:
 
299
 
 
300
  ./config.status
 
301
 
 
302
To re-run ./configure with the same parameters it was run with last
 
303
time, use:
 
304
 
 
305
  ./ocnfig.status --recheck
 
306
 
 
307
 
 
308
Configuration
 
309
-------------
 
310
zaptel.conf
 
311
~~~~~~~~~~~
 
312
The main method to configure Zaptel devices is using the utility
 
313
*ztcfg*. ztcfg reads data from the configuration file /etc/zaptel.conf ,
 
314
figures out what configuration to send to channels, and send it. 
 
315
 
 
316
A sample annotated zaptel.conf is included in this directory and
 
317
installed by default to /etc/zaptel.conf . Edit it to suit your
 
318
configuration. Alternatively use the script genzaptelconf to generate
 
319
one that should work with your system.
 
320
 
 
321
 
 
322
sysconfig/default
 
323
~~~~~~~~~~~~~~~~~
 
324
The configuration file of the zaptel init.d script is either
 
325
/etc/default/zaptel (Debian systems) or /etc/sysconfig/zaptel (most
 
326
others). That file is used to override defaults that are set at the
 
327
beginning of the init.d script.
 
328
 
 
329
For instance, to define for the init.d script to load the modules wctdm
 
330
and xpp_usb (in that order) add the following line to that file:
 
331
 
 
332
  MODULES="wctdm xpp_usb"
 
333
 
 
334
Currently that file must set "TELEPHONY=yes" for the zaptel init.d to
 
335
work.
 
336
 
 
337
Module Parameters
 
338
~~~~~~~~~~~~~~~~~
 
339
The kernel modules can be configured through module parameters. Module
 
340
parameters can optionally be set at load time. They are normally set (if
 
341
needed) by a line in a file under /etc/modprobe.d/ or in the file
 
342
/etc/modprobe.conf (Or /etc/modules.conf in kernel 2.4).
 
343
 
 
344
Example line:
 
345
 
 
346
  options zaptel debug=1
 
347
 
 
348
The module parameters can normally be modified at runtime through sysfs:
 
349
 
 
350
  pungenday:~# cat /sys/module/zaptel/parameters/debug 
 
351
  0
 
352
  pungenday:~# echo 1 >/sys/module/zaptel/parameters/debug
 
353
  pungenday:~# cat /sys/module/zaptel/parameters/debug 
 
354
  1
 
355
 
 
356
Viewing and setting parameters that way is possible as of kernel 2.6 .
 
357
In kernels older than 2.6.10, the sysfs "files" for the parameters
 
358
reside directly under /sys/module/'module_name' .
 
359
 
 
360
Useful module parameters:
 
361
 
 
362
debug (most modules)::
 
363
  Sets debug mode / debug level. With most modules 'debug' can be either
 
364
  disabled (0, the default value) or enabled (any other value). 
 
365
  +
 
366
  +
 
367
  wctdm and wcte1xp print several extra debugging messages if the value
 
368
  of debug is more than 1.
 
369
  +
 
370
  +
 
371
  Some modules have "debugging flags" bits - the value of debug is a
 
372
  bitmask and several messages are printed if some bits are set:
 
373
  - ztdummy:
 
374
    * 1: DEBUG_GENERAL - general error messages.
 
375
    * 2: DEBUG_TICKS - Show that the module is alive :-)
 
376
  - wctdm24xxp:
 
377
    * 1: DEBUG_CARD
 
378
    * 2: DEBUG_ECHOCAN
 
379
  - wct4xxp:
 
380
    * 1: DEBUG_MAIN
 
381
    * 2: DEBUG_DTMF
 
382
    * 4: DEBUG_REGS
 
383
    * 8: DEBUG_TSI
 
384
    * 16: DEBUG_ECHOCAN
 
385
    * 32: DEBUG_RBS
 
386
    * 64: DEBUG_FRAMER
 
387
  - xpp: Previously (before 1.2.26 / 1.4.11) it was called "print_dbg". 
 
388
    See also README.Astribank:
 
389
    * 1: GENERAL - General debug comments.
 
390
    * 2: PCM - PCM-related messages. Tend to flood logs.
 
391
    * 4: LEDS - Anything related to the LEDs status control. The driver
 
392
      produces a lot of messages when the option is enabled.
 
393
    * 8: SYNC - Synchronization related messages.
 
394
    * 16: SIGNAL - Zaptel signalling related messages.
 
395
    * 32: PROC - Messages related to the procfs interface.
 
396
    * 64: REGS - Reading and writing to chip registers. Tends to flood
 
397
          logs.
 
398
    * 128: DEVICES - Device instantiation, destruction and such.
 
399
    * 256 - COMMANDS - Protocol commands. Tends to flood logs.
 
400
 
 
401
deftaps (zaptel)::
 
402
  The default size for the echo canceller. The number is in "taps", that
 
403
  is "samples", 1/8 ms. The default is 64 - for a tail size of 8 ms.
 
404
  +
 
405
  +
 
406
  Asterisk's chan_zap tends to pass its own value anyway, with a
 
407
  different default size. So normally setting this doesn't change
 
408
  anything.
 
409
 
 
410
To get a list of parameters supported by a module, use 
 
411
 
 
412
  modinfo module_name
 
413
 
 
414
Or, for a module you have just built:
 
415
 
 
416
  modinfo ./module_name.ko
 
417
 
 
418
For the xpp modules this will also include the description and default
 
419
value of the module. You can find a list of useful xpp module parameters
 
420
in README.Astribank .
 
421
 
 
422
 
 
423
Reference Configuration
 
424
-----------------------
 
425
include::zaptel.conf.asciidoc[]
 
426
 
 
427
Tonezones
 
428
~~~~~~~~~
 
429
The file zonedata.c contains the information about the tone zones used
 
430
in libtonezone (and hence also in ztcfg). Here is a list of those zones:
 
431
 
 
432
include::tonezones.txt[]
 
433
 
 
434
 
 
435
Zaptel PERL modules
 
436
-------------------
 
437
The directory xpp/utils has, in addition to helper utilities for the
 
438
Xorcom Astribank, a collection of perl modules to provide information
 
439
related to Zaptel. The perl modules themselves are under xpp/utils/zconf .
 
440
In xpp/utils there are several utilities that use those modules:
 
441
- xpp-specific: zt_registration, xpp_sync, xpp_blink .
 
442
- General: lszaptel, zapconf, zaptel_hardware
 
443
 
 
444
The zaptel perl modules will currently only be automatically installed
 
445
if you happen to isntall the xpp module. This should be the defualt, but
 
446
you can also initiate it manually by running:
 
447
 
 
448
  make -C xpp/utils install
 
449
 
 
450
Those utilities require the perl modules to be installed, however they
 
451
will also look for them in the directory zconf, and thus can be run
 
452
directly from the zaptel source tree. For example:
 
453
 
 
454
  ./xpp/utils/zaptel_hardware
 
455
 
 
456
To get usage information on a program, you can also use perldoc
 
457
(sometimes provided in a package separate from perl itself). For
 
458
instance:
 
459
 
 
460
  perldoc ./xpp/utils/lszaptel
 
461
 
 
462
Some of them are specific for the Xorcom Astribank and described in its
 
463
docuemntation. the others are:
 
464
 
 
465
lszaptel:: 
 
466
  A somewhat glorified `cat /proc/zaptel/*`.
 
467
zapconf:: 
 
468
  An currently experimental and intended to eventually replace
 
469
  genzaptelconf by a more maintainable code.
 
470
zaptel_drivers::
 
471
  A two-liner script (not installed by default) that simply returns the
 
472
  modules that should be modprobed on this system.
 
473
zaptel_hardware:: 
 
474
  Uses the information from sysfs and its own knowledge to show
 
475
  what PCI/USB Zaptel hardware is connected and if it is currently used
 
476
  by a driver. Shows also some more information for Astrobanks from
 
477
  /proc/xpp .
 
478
 
 
479
Internals
 
480
---------
 
481
Zaptel Device Files
 
482
~~~~~~~~~~~~~~~~~~~
 
483
Userspace programs will usually interact with Zaptel through device
 
484
files under the /dev/zap directory (pedantically: characted device files 
 
485
with major number 196) . Those device files can be generated statically
 
486
or dynamically through the udev system.
 
487
 
 
488
* /dev/zap/ctl (196:0) - a general device file for various information and
 
489
  control operations on the zaptel channels.
 
490
* /dev/zap/NNN (196:NNN) - for NNN in the range 1-249. A device file for
 
491
  zaptel channel NNN. It can be used to read data from the channel
 
492
  and write data to the channel.
 
493
* /dev/zap/transcode (196:250) - Used to connect to a zaptel transcoding
 
494
  device.
 
495
* /dev/zap/timer (196:253) - Allows setting timers. Used anywhere?
 
496
* /dev/zap/channel (196:254) - Can be used to open an arbitrary zaptel
 
497
  channel. This is an alternative to /dev/zap/NNN that is not limited to
 
498
  249 channels.
 
499
* /dev/zap/pseudo (196:255) - A timing-only device. Every time you open
 
500
  it, a new Zaptel channel is created. That Zaptel channel is "pseudo" -
 
501
  Zaptel recieves no data in it, and only sends garbage data with the
 
502
  same timing as the Zaptel timing master device.
 
503
 
 
504
 
 
505
Zaptel Timing
 
506
~~~~~~~~~~~~~
 
507
A PBX system should generally have a single clock. If you are connected
 
508
to a telephony provider via a digital interface (e.g: E1, T1) you should
 
509
also typically use the provider's clock (as you get through the
 
510
interface). Hence one important job of Asterisk is to provide timing to
 
511
the PBX. 
 
512
 
 
513
Zaptel "ticks" once per millisecond (1000 times per second). On each
 
514
tick every active zaptel channel reads and 8 bytes of data. Asterisk
 
515
also uses this for timing, through a zaptel pseudo channel it opens.
 
516
 
 
517
However, not all PBX systems are connected to a telephony provider via
 
518
a T1 or similar connection. With an analog connection you are not synced
 
519
to the other party. And some systems don't have Zaptel hardware at all.
 
520
Even a digital card may be used for other uses or is simply not
 
521
connected to a provider. Zaptel cards are also capable of providing timing 
 
522
from a clock on card. Cheap x100P clone cards are sometimes used for
 
523
that pupose.
 
524
 
 
525
If all the above fail, you can use the module ztdummy to provide timing
 
526
alone without needing any zaptel hardware. It will work with most
 
527
systems and kernels.
 
528
 
 
529
You can check the zaptel timing source with zttest, which is a small 
 
530
utility that is included with zaptel. It runs in cycles. In each such
 
531
cycle it tries to read 8192 bytes, and sees how long it takes. If zaptel
 
532
is not loaded or you don't have the device files, it will fail
 
533
immedietly. If you lack a timing device it will hang forever in the
 
534
first cycle. Eitherwise it will just give you in each cycle the percent
 
535
of how close it was. Also try running it with the option -v for a
 
536
verbose output.
 
537
 
 
538
To check the clock source that is built into ztdummy, you can either
 
539
look at title of its span in /proc/zaptel file for a "source:" in the
 
540
description. Or even run:
 
541
 
 
542
  strings zaptel.ko | grep source:
 
543
 
 
544
 
 
545
Spans and Channels
 
546
~~~~~~~~~~~~~~~~~~
 
547
Zaptel provides telephony *channels* to the userspace applications. 
 
548
Those channels are channels are incoreperated into logical units called
 
549
*spans*.
 
550
 
 
551
With digital telephony adapters (e.g: E1 or T1), a span normally 
 
552
represents a single port. With analog telephony a span typically
 
553
represents a PCI adapter or a similar logical unit.
 
554
 
 
555
Both channels and spans are identified by enumerating numbers (beginning
 
556
with 1). The number of the channel is the lowest unused one when it is
 
557
generated, and ditto for spans.
 
558
 
 
559
 
 
560
PROCFS Interface: /proc/zaptel
 
561
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
562
A simple way to get the current list of spans and channels each span
 
563
contains is the files under /proc/zaptel . /proc/zaptel is generated by
 
564
zaptel as it loads. As each span registers to Zaptel, a file under
 
565
/proc/zaptel is created for it. The name of that file is the number of
 
566
that span.
 
567
 
 
568
Each file has a 1-line title for the span followed by an empty line and
 
569
then a line for each channel of the span. 
 
570
 
 
571
The title line shows the number of the span, its name and title, and 
 
572
(potentially) the alarms in which it is.
 
573
 
 
574
The title shows the span number and name, followed by any allarms the
 
575
span may have: For example, here is the first span in my system (with no
 
576
alarms):
 
577
 
 
578
  Span 1: XBUS-00/XPD-00 "Xorcom XPD #0/0: FXS"
 
579
 
 
580
The channel line for each channel shows its channel number, name and the
 
581
actual signalling assigned to it through ztcfg. Before being configured
 
582
by ztcfg: This is Zaptel channel 2, whose name is 'XPP_FXS/0/0/1'.
 
583
 
 
584
           2 XPP_FXS/0/0/1
 
585
 
 
586
After being configured by ztcfg: the signalling 'FXOLS' was added. FXS
 
587
channels have FXO signalling and vice versa:
 
588
 
 
589
           2 XPP_FXS/0/0/1 FXOLS
 
590
 
 
591
If the channel is in use (typically opened by Asterisk) then you will
 
592
see an extra '(In use)':
 
593
 
 
594
           2 XPP_FXS/0/0/1 FXOLS (In use)
 
595
 
 
596
 
 
597
ABI Compatibility
 
598
~~~~~~~~~~~~~~~~~
 
599
Like any other kernel code, Zaptel strives to maintain a stable
 
600
interface to userspace programs. The API of Zaptel to userspace
 
601
programs, zaptel.h, has remained backword-compatible for a long time and
 
602
is expected to remain so in the future. With the ABI (the bits
 
603
themselves) things are slightly trickier.
 
604
 
 
605
Zaptel's interface to userspace is mostly ioctl(3) calls. Ioctl calls
 
606
are identified by a number that stems from various things, one of which
 
607
is the size of the data structure passed between the kernel and
 
608
userspace. 
 
609
 
 
610
Many of the Zaptel ioctl-s use some sepcific structs to pass information
 
611
between kernel and userspace. In some cases the need arose to pass a few
 
612
more data members in each call. Simply adding a new member to the struct
 
613
would have meant a new number for the ioctl, as its number depends on
 
614
the size of the data passed.
 
615
 
 
616
Thus we would add a new ioctl with the same base number and with the
 
617
original struct.
 
618
 
 
619
So suppose we had the following ioctl:
 
620
----------------------------------
 
621
struct zt_example {
 
622
        int sample;
 
623
}
 
624
 
 
625
#define ZT_EXAMPLE     _IOWR (ZT_CODE, 62, struct zt_example)
 
626
----------------------------------
 
627
 
 
628
And we want to add the field 'int onemore', we won't just add it to the
 
629
struct. We will do something that is more complex:
 
630
------------------------------------
 
631
/* The original, unchanged: */
 
632
struct zt_example_v1 {
 
633
        int sample;
 
634
}
 
635
 
 
636
/* The new struct: */
 
637
struct zt_example {
 
638
        int sample;
 
639
        int onemore;
 
640
}
 
641
 
 
642
#define ZT_EXAMPLE_V1  _IOWR (ZT_CODE, 62, struct zt_example_v1)
 
643
#define ZT_EXAMPLE     _IOWR (ZT_CODE, 62, struct zt_example)
 
644
------------------------------------
 
645
We actually have here two different ioctls: the old ZT_EXAMPLE would be
 
646
0xC0044A3E . ZT_EXAMPLE_V1 would have the same value. But the new value
 
647
of ZT_EXAMPLE would be 0xC0084A3E .
 
648
 
 
649
Programs built with the original zaptel.h (before the change) use the
 
650
original ioctl, whether or not the kerenl code is actually of the newer
 
651
version. Thus in most cases there are no compatibility issues.
 
652
 
 
653
When can we have compatibility issues? if we have code built with the
 
654
new zaptel.h, but the loaded kernel code (modules) are of the older
 
655
version. Thus the userspace program will try to use the newer ZT_EXAMPLE
 
656
(0xC0084A3E). But the kernel code has no handler for that ioctl. The
 
657
result: the error 25, ENOTTY, which means "Inappropriate ioctl for
 
658
device".
 
659
 
 
660
As a by-product of that method, for each interface change a new #define
 
661
is added. That definition is for the old version and thus it might
 
662
appear slightly confusing in the code, but it is useful for writing code
 
663
that works with both versions of Zaptel. 
 
664
 
 
665
 
 
666
Past Incompatibilities
 
667
^^^^^^^^^^^^^^^^^^^^^^
 
668
 
 
669
.Zaptel 1.4.10:
 
670
* Semantics of ZT_LOADZONE. Using newer ztcfg with older modules will
 
671
  yield -EINVAL with the kernel message 'Invalid tone (96) defined'
 
672
 
 
673
.Zaptel 1.4.8:
 
674
* ZT_GET_PARAMS_V1
 
675
* ZT_SET_PARAMS_V1
 
676
* ZT_SPANINFO_V2
 
677
 
 
678
.Zaptel 1.4.6:
 
679
* ZT_SPANINFO_V1
 
680
 
 
681
ZT_SPANINFO_V1 was originally called (up to zaptel 1.4.8)
 
682
"ZT_SPANINFO_COMPAT".
 
683
 
 
684
 
 
685
PPP Support
 
686
-----------
 
687
Zaptel digital cards can provide data channels through ppp as
 
688
point-to-point connections. This requires a plugin to the ppp daemon
 
689
that is included in the ppp/ subdirectory. To install it:
 
690
 
 
691
1. Make sure you have the PPP source / headers installed. On Debian:
 
692
 
 
693
   apt-get install ppp-dev
 
694
 
 
695
2. Run 'make' on the ppp subdirectory:
 
696
 
 
697
   make -C ppp 
 
698
   make -C ppp install
 
699
 
 
700
3. Make sure your kernel has support for both PPP (which is common is
 
701
   distribution kernels and for HDLC (much less common) - CONFIG_PPP and
 
702
   CONFIG_HDLC .
43
703
 
44
704
 
45
705
What is the license for the zaptel driver?
46
 
===================================================
 
706
------------------------------------------
47
707
libpri is distributed under the terms of the GNU General Public License, 
48
708
which permit its use and linking with other GPL'd software only.  
49
709
The GNU GPL is included in the file LICENSE in this directory.
50
710
 
51
711
If you wish to use the zaptel drivers in an application for which the 
52
712
GPL is not appropriate (e.g. a proprietary embedded system), licenses
53
 
under more flexible terms can be readily obtained through Digium, Inc. 
54
 
at reasonable cost.
55
 
 
56
 
 
57
 
Brief F.A.Q
58
 
===========
59
 
 
60
 
Q. Zaptel compiled with no errors but when I try to modprobe zaptel I
61
 
receive "FATAL: Error insering zaptel (/lib/modules/2.6.x.x/misc/zaptel.ko):
62
 
Unknown symol in module or unknown parameter (see dmesg)
63
 
 
64
 
A. You need to recompile your kernel with CONFIG_CRC_CCITT=y or
65
 
CONFIG_CRC_CCITT=m. To do this, run 'make menuconfig' and change it under 
66
 
'Library Routines -> CRC-CCIT functions'. If you compiled it as a module,
67
 
load it, otherwise reboot.
 
713
under more flexible terms can be readily obtained through Digium, Inc.at reasonable cost.
 
714
 
68
715
 
69
716
How do I report bugs or contribute?
70
 
===================================
 
717
-----------------------------------
71
718
Please report bug and patches to the Asterisk.org bug tracker at
72
719
http://bugs.digium.com in the "zaptel" category.
73
720
 
 
721
 
74
722
Does anything use this library so far?
75
 
======================================
 
723
--------------------------------------
76
724
Yes, the Asterisk Open Source PBX does. http://www.asterisk.org
77
725
 
 
726
 
 
727
Links
 
728
-----
 
729
- http://asterisk.org/[] - The Asterisk PBX
 
730
- http://voip-info.org/[]
 
731
- http://voip-info.org/wiki/view/Asterisk+Zaptel+Installation[]
 
732
- http://www.zapatatelephony.org/[] - A historical site.
 
733
- http://rapid.tzafrir.org.il/docs/README.html[Up-to-date HTML version
 
734
  of this file]