[zaptel-commits] tzafrir: branch 1.4 r2703 - /branches/1.4/README

[SVN commits to the Zaptel project]

Author: tzafrir
Date: Fri Jul  6 18:24:46 2007
New Revision: 2703

URL: http://svn.digium.com/view/zaptel?view=rev&rev=2703
Log:
Two more sections to the README. Though I'm not quite happy with 
their style.

Modified:
    branches/1.4/README

Modified: branches/1.4/README
URL: http://svn.digium.com/view/zaptel/branches/1.4/README?view=diff&rev=2703&r1=2702&r2=2703
==============================================================================
--- branches/1.4/README (original)
+++ branches/1.4/README Fri Jul  6 18:24:46 2007
@@ -165,6 +165,64 @@
   perldoc ./xpp/utils/xpp_blink
 
 
+Zaptel Device Files
+-------------------
+Userspace programs will usually interact with Zaptel through device
+files under the /dev/zap directory (pedantically: characted device files 
+with major number 196) . Those device files can be generated statically
+or dynamically through the udev system.
+
+* /dev/zap/ctl (196:0) - a general device file for various information and
+  control operations on the zaptel channels.
+* /dev/zap/NNN (196:NNN) - for NNN in the range 1-249. A device file for
+  zaptel channel NNN. It can be used to read data from the channel
+  and write data to the channel.
+* /dev/zap/transcode (196:250) - Used to connect to a zaptel transcoding
+  device.
+* /dev/zap/timer (196:253) - Allows setting timers. Used anywhere?
+* /dev/zap/channel (196:254) - Can be used to open an arbitrary zaptel
+  channel. This is an alternative to /dev/zap/NNN that is not limited to
+  249 channels.
+* /dev/zap/pseudo (196:255) - A timing-only device. Every time you open
+  it, a new Zaptel channel is created. That Zaptel channel is "pseudo" -
+  Zaptel recieves no data in it, and only sends garbage data with the
+  same timing as the Zaptel timing master device.
+
+
+Zaptel Timing
+-------------
+A PBX system should generally have a single clock. If you are connected
+to a telephony provider via a digital interface (e.g: E1, T1) you should
+also typically use the provider's clock (as you get through the
+interface). Hence one important job of Asterisk is to provide timing to
+the PBX. 
+
+Zaptel "ticks" once per millisecond (1000 times per second). On each
+tick every active zaptel channel reads and 8 bytes of data. Asterisk
+also uses this for timing, through a zaptel pseudo channel it opens.
+
+However, not all PBX systems are connected to a telephony provider via
+a T1 or similar connection. With an analog connection you are not synced
+to the other party. And some systems don't have Zaptel hardware at all.
+Even a digital card may be used for other uses or is simply not
+connected to a provider. Zaptel cards are also capable of providing timing 
+from a clock on card. Cheap x100P clone cards are sometimes used for
+that pupose.
+
+If all the above fail, you can use the module ztdummy to provide timing
+alone without needing any zaptel hardware. It will work with most
+systems and kernels.
+
+You can check the zaptel timing source with zttest, which is a small 
+utility that is included with zaptel. It runs in cycles. In each such
+cycle it tries to read 8192 bytes, and sees how long it takes. If zaptel
+is not loaded or you don't have the device files, it will fail
+immedietly. If you lack a timing device it will hang forever in the
+first cycle. Eitherwise it will just give you in each cycle the percent
+of how close it was. Also try running it with the option -v for a
+verbose output.
+
+
 What is the license for the zaptel driver?
 ------------------------------------------
 libpri is distributed under the terms of the GNU General Public License,