Add man pages based on Zaptel's man pages.

git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/trunk@4368 a0bf4364-ded3-4de4-8d8a-66a801d63aff

10 files changed, 697 insertions, 0 deletions

diff --git a/doc/dahdi_cfg.8 b/doc/dahdi_cfg.8
new file mode 100644
index 0000000..f9b167f
--- /dev/null
+++ b/doc/dahdi_cfg.8
@@ -0,0 +1,70 @@
+.TH "DAHDI_CFG" "8" "16 Jun 2008" "" ""
+
+.SH NAME
+dahdi_cfg \- configures dahdi kernel modules from dahdi.conf
+.SH SYNOPSIS
+
+.B dahdi_cfg [-c \fICFG_FILE\fB] [-s] [-f] [-t] [-v [-v ... ] ]
+
+.B dahdi_cfg -h
+
+.SH DESCRIPTION
+.B dahdi_cfg 
+configures dahdi interface cards from a config file.
+
+You  generally  need to run it with a valid configurations
+in order for zaptel modules to work properly.
+
+It must be run to configure every DAHDI span. Normally it is run from
+the DAHDI init script.
+
+.SH OPTIONS
+
+.B -c \fICFG_FILE
+.RS
+Use an alternative configuration file instead of
+.I /etc/dahdi.conf
+.RE
+
+.B -s
+.RS
+Only shutdown spans.
+.RE
+
+.B -f
+.RS
+Always configure every channel, even if it appears not to have changed.
+.RE
+
+.B -t
+.RS
+Test mode. Don't do anything, just report what you wanted to do.
+.RE
+
+.B -v
+.RS
+Be more verbose. Add extra v-s for extra verbosity.
+.RE
+
+.B -h
+.RS
+Display a brief help message.
+.RE
+
+.SH FILES
+
+.I /etc/dahdi.conf
+.RS
+The default location for the configuration file.
+.RE
+
+.SH SEE ALSO
+dahdi_tool(8), dahdi_monitor(8), asterisk(8).
+
+.SH AUTHOR
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
+the Debian system (but may be used by others).  Permission is
+granted to copy, distribute and/or modify this document under
+the terms of the GNU General Public License, Version 2 any 
+later version published by the Free Software Foundation.
diff --git a/doc/dahdi_diag.8 b/doc/dahdi_diag.8
new file mode 100644
index 0000000..eabd6c1
--- /dev/null
+++ b/doc/dahdi_diag.8
@@ -0,0 +1,52 @@
+.TH dahdi_diag 8 "2008-01-07" 
+.SH NAME 
+dahdi_diag \(em Dump Zaptel channel parameters
+.SH SYNOPSIS 
+.B dahdi_diag 
+.I channel
+
+.SH DESCRIPTION 
+.B dahdi_diag
+asks the kernel to dump parameters for Zaptel channel no.
+.I channel
+to the kernel logs. You will be able to see them using, e.g. dmesg(1).
+
+
+.SH OPTIONS
+.I channel
+.RS
+The number of the Zaptel channel whose parammeters should be dumped.
+May be any Zaptel channel (even if it is open).
+.RE
+
+.SH EXAMPLE
+
+  # /tmp/dahdi_diag 5
+  # dmesg | tail -n 15
+  Dump of Zaptel Channel 5 (XPP_BRI_TE/00/01/1,5,2):
+
+  flags: 501 hex, writechunk: c5190948, readchunk: c5190954
+  rxgain: ccad2e80, txgain: ccad2e80, gainalloc: 0
+  span: c48a900c, sig: 80 hex, sigcap: 80 hex
+  inreadbuf: -1, outreadbuf: 0, inwritebuf: 0, outwritebuf: -1
+  blocksize: 160, numbufs: 4, txbufpolicy: 0, txbufpolicy: 0
+  txdisable: 0, rxdisable: 0, iomask: 0
+  curzone: c78e7000, tonezone: 0, curtone: 00000000, tonep: 0
+  digitmode: 0, txdialbuf: , dialing: 0, aftdialtimer: 0, cadpos. 0
+  confna: 0, confn: 0, confmode: 0, confmute: 0
+  ec: 00000000, echocancel: 0, deflaw: 0, xlaw: ccab5e80
+  echostate: 00, echotimer: 0, echolastupdate: 0
+  itimer: 0, otimer: 0, ringdebtimer: 0
+
+.SH SEE ALSO 
+dahdi_cfg(8), asterisk(8), dmesg(1). 
+
+.SH AUTHOR 
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
+ 
+On Debian systems, the complete text of the GNU General Public 
+License can be found in /usr/share/common-licenses/GPL. 
diff --git a/doc/dahdi_monitor.8 b/doc/dahdi_monitor.8
new file mode 100644
index 0000000..ed989be
--- /dev/null
+++ b/doc/dahdi_monitor.8
@@ -0,0 +1,43 @@
+.TH "DAHDI_MONITOR" "8" "16 June 2008" "" ""
+
+.SH NAME
+dahdi_monitor \- checks the rx/tx levels of the dahdi inteface cards.
+.SH SYNOPSIS
+
+.B dahdi_monitor \fIchannel number\fB [-v] [-f \fIFILE\fB]
+
+.SH DESCRIPTION
+
+dahdi_monitor monitors a zaptel channel. It gives you a visual
+representation of the sound strengths and makes it easy to see if
+the received or transmitted signals are too high or out of
+balance
+
+.SH OPTIONS
+The first (mandatory) parameter is the number of the channel
+to monitor.
+
+.B -v
+.RS
+Display visual audio levels.
+.RE
+
+.B -f \fIFILE
+.RS
+Write output to FILE
+.RE
+
+Some extra, yet undocumented, options.
+
+.SH SEE ALSO
+.PP
+dahdi_tool(8), dahdi_cfg(8), asterisk(8).
+
+.SH AUTHOR
+.PP
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
+the Debian system (but may be used by others).  Permission is
+granted to copy, distribute and/or modify this document under
+the terms of the GNU General Public License, Version 2 any 
+later version published by the Free Software Foundation.
diff --git a/doc/dahdi_scan.8 b/doc/dahdi_scan.8
new file mode 100644
index 0000000..c351db9
--- /dev/null
+++ b/doc/dahdi_scan.8
@@ -0,0 +1,101 @@
+.TH dahdi_scan 8 "2008-03-18" 
+.SH NAME 
+dahdi_scan \(em Print Configuration of Zaptel Spans
+.SH SYNOPSIS 
+.B dahdi_scan
+.I [spans]
+
+.SH DESCRIPTION 
+.B dahdi_scan
+prints information about dahdi spans in the system. For analog spans it
+also provides a list of channels.
+
+By default it prints information about all the spans in the system.
+However if parameters are provided, they will be considered to be a list
+of span numbers and information will be printed for them.
+
+Output is printed to the standard output. The format is that of an
+Asterisk configuration file (similar to a "ini" configuration file),
+where the name of the section is the number of the span. Note that the
+specifically for analog spans some keys may appear more than once, and
+hence you can not use a parser for an "ini" format and assume you have a
+dictionary.
+
+.SH EXAMPLES
+Printing information for spans 1, 2 and 4:
+
+  dahdi_span 1 2 4
+
+And to print all the spans:
+
+  dahdi_span
+
+Information about a certain analog span:
+
+  [5]
+  active=yes
+  alarms=OK
+  description=Xorcom XPD #00/10: FXS
+  name=XBUS-00/XPD-10
+  manufacturer=Xorcom Inc.
+  devicetype=Astribank: Unit 1 Subunit 0: FXS
+  location=usb-0000:00:03.3-4
+  basechan=125
+  totchans=8
+  irq=0
+  type=analog
+  port=125,FXS
+  port=126,FXS
+  port=127,FXS
+  port=128,FXS
+  port=129,FXS
+  port=130,FXS
+  port=131,FXS
+  port=132,FXS
+
+And an example of a digital span:
+
+  [1]
+  active=yes
+  alarms=RED
+  description=T2XXP (PCI) Card 0 Span 1
+  name=TE2/0/1
+  manufacturer=Digium
+  devicetype=Wildcard TE205P (4th Gen)
+  location=Board ID Switch 0
+  basechan=1
+  totchans=24
+  irq=193
+  type=digital-T1
+  syncsrc=0
+  lbo=0 db (CSU)/0-133 feet (DSX-1)
+  coding_opts=B8ZS,AMI
+  framing_opts=ESF,D4
+  coding=B8ZS
+  framing=ESF
+
+The "type" field may contain: "analog", "digital-T1", "digital-E1",
+"digital-J1" or "digital-BRI".
+
+.SH FILES
+Requires read access to /dev/zap/ctl .
+
+.SH SEE ALSO 
+dahdi_cfg(8), asterisk(8). 
+
+.SH BUGS
+The program still does not do everything described in the man page.
+
+It also assumes that spans don't skip channel numbers, and that their 
+channels numbers are "running". This is anyway almost always the case. 
+And always the case in a normal boot process.
+
+.SH AUTHOR 
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
+ 
+On Debian systems, the complete text of the GNU General Public 
+License can be found in /usr/share/common-licenses/GPL. 
diff --git a/doc/dahdi_test.8 b/doc/dahdi_test.8
new file mode 100644
index 0000000..c61f0f6
--- /dev/null
+++ b/doc/dahdi_test.8
@@ -0,0 +1,49 @@
+.TH dahdi_test 8 "2005-06-25" 
+.SH "NAME" 
+dahdi_test \(em Test if the dahdi timer provides timely response
+.SH "SYNOPSIS" 
+.B dahdi_test 
+.I [ -v ]
+
+.SH DESCRIPTION 
+.B dahdi_test
+dahdi_test runs a timing test in a loop and prints the result of each loop.
+The test is as follows:
+
+It reads 8192 bytes from the dahdi timer device (\fI/dev/dahdi/pseudo\fR). 
+This should take exactly 8000 ms . It uses calls to
+.I gettimeofday(2) 
+before and after that read to check that indeed exactly 8000ms have passed.
+
+Values of 100% and 99.99% Are normally considered a definite 
+.I pass.
+Values of 99.98% and 99.97% are probably OK as well.
+
+.SH OPTIONS
+.B -v
+.RS
+Be more verbose: print one line per test.
+.RE
+
+.B -c 
+.I count
+.RS
+Run for 
+.I count
+times instead of running forever.
+.RE
+
+.SH FILES
+.B /dev/dahdi/pseudo
+.RS
+.RE
+The device file used to access the dahdi timer.
+
+.SH SEE ALSO 
+dahdi_tool(8), dahdi_cfg(8), asterisk(8). gettimeofday(2)
+
+.SH AUTHOR 
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
diff --git a/doc/dahdi_tool.8 b/doc/dahdi_tool.8
new file mode 100644
index 0000000..7cad136
--- /dev/null
+++ b/doc/dahdi_tool.8
@@ -0,0 +1,25 @@
+.TH "DAHDI_TOOL" "8" "16 June 2008" "" ""
+
+.SH NAME
+dahdi_tool \- Zaptel Tool shows status of Digium's interface cards.
+.SH SYNOPSIS
+
+.B dahdi_tool
+
+.SH DESCRIPTION
+dahdi_tool shows the current status the DAHDI inteface cards plugged 
+to the computer.
+
+It displays values like Current Alarms, SyncSource, Tx/Rx
+Levels for each DAHDI interface.
+
+.SH SEE ALSO
+dahdi_monitor(8), asterisk (8).
+
+.SH AUTHOR
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
+the Debian system (but may be used by others).  Permission is
+granted to copy, distribute and/or modify this document under
+the terms of the GNU General Public License, Version 2 any 
+later version published by the Free Software Foundation.
diff --git a/doc/fxotune.8 b/doc/fxotune.8
new file mode 100644
index 0000000..7f0236f
--- /dev/null
+++ b/doc/fxotune.8
@@ -0,0 +1,207 @@
+.TH FXOTUNE "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
+.SH NAME
+fxotune \- automatically tune DAHDI FXO channels
+.SH SYNOPSIS
+.B fxotune -i 
+.I [options]
+- detect mode
+
+.B fxotune -d
+.I [ options ]
+- dump mode
+
+.B fxotune -s
+- Startup mode
+.SH
+.SH DESCRIPTION
+.B fxotune 
+is a script that fine-tune parameters of the FXO modules of the 
+card. It has three modes of operation:
+
+.I Detect mode (-i):
+it detects and tunes all the available FXO channels.
+It writes settings to a configuration file (/etc/fxotune.conf)
+from which it can be loaded (e.g: at startup) using -s .
+
+.I Dump mode (-d):
+Runs detection on a single Zaptel channel, and just dumps waveforms to
+.B fxotune_dump.vals
+is generated in the current directory.
+
+.I Startup mode (-s):
+fxotune just reads the settings from fxotune.conf into the FXO modules.
+
+You are advised to run fxotune on all FXO ports you have that support 
+it and that are connected. Note that the tunning is affected by e.g.
+the physical parameters of the connection, and thus if it has been 
+radically changed, you may need to re-run fxotune.
+
+FXOTune only works for the Digium TDM400P/800P/2400P cards and
+compatible and the Xorcom Astribank devices. Other cards (notably X100P
+cards and clones) do not have the hardware to support such tuning.
+
+The tuning process needs a clear line to do the tuning.  In order to do
+that, it runs in cycles of the following: sets the line off-hook, dials
+a dial string (which should set the PSTN provider waiting for the next
+digit), and then starts tuning. It has a limited ammount of time for
+tuning before the PSTN gives up and gives a busy tone. So after a while
+it hangs up and starts a new cycle.
+
+.B fxotune
+has two operation modes: tune (-i) and set (-s). In the tune mode it 
+generates /etc/fxotune.conf, and in the set mode it merely applies the 
+parameters from fxotune.conf to device's ports.
+
+.SH OPTIONS
+The following options below except -v (verbose) affect only the
+detection process and hence apply only to the 
+.I detect
+and 
+.I dump
+modes.
+
+In addition, to maintain compatibility with older versions of fxotune,
+if in detect or dump mode there is a parameter with option before it, it
+is considered to be the 
+.I dialstring
+parameter (-n).
+
+.B -b
+.I startdev
+.RS
+Start tuning from dahdi channel num. \fI startdev\fR: skip all previous
+channels. By default starting from channel 1.
+
+In dump mode (-d) this is the single channel that will be tested.
+.RE
+
+.B -e
+.I stopdev
+.RS
+Tune only up to dahdi channel num. \fI stopdev\fR: skip all previous
+channels. By default stopping at channel 252.
+
+In dump mode (-d) this parameter is ignored.
+.RE
+
+.B -l
+.I delay-to-silence
+.RS
+Time in seconds to wait after dialing the dial-string to get a clear line.
+The default is 0. 
+before 
+.RE
+
+.B -m
+.I silence-good-for
+.RS
+Time in seconds which states how long the PSTN will wait after we dialed
+the dial-string until it starts giving a busy tone. You can test this by
+connecting an analog phone to the line and dialing.
+
+The default is 18 (18 seconds). 
+.RE
+
+.B -n
+.I dial-string
+.RS
+Digits to dial to the PSTN in order to get it stop its dialtone and
+waiting for the next digit. 
+
+The default is "4" (sending just the digit 4). It should work in most
+cases. Again, this can be tested by connecting a phone to the PSTN line
+and dialing the dial-string.
+.RE
+
+.B -t
+.I detect-type
+.RS
+This option allows using the older detection method used by fxotune of
+zaptel 1.2. use 
+.B -t 1
+for that older method. whereas
+.B -t 2
+(the default) uses the current method.
+
+This option only applies to detect mode (-i).
+.RE
+
+.B -v[vvvv]
+.RS
+Sets debugging on. The more v-s, the higher debug level. 
+
+Note that: -vv -v  will actually set debug level to 1 instead of 3.
+.RE
+
+.B -w
+.I wave-form
+.RS
+The default: -1, for multitone waveform. Alternatively: a frequency of a
+single tone.
+
+This option only applies to dump mode (-d).
+.RE
+
+
+.SH EXAMPLES
+.RS
+fxotune -i 9
+.RE
+if you need to dial 9 for an external line. If you always get a line, you
+can simply use any digit.
+.RE
+
+.B -s
+.RS
+Load settings from the last test. Used at startup.
+.RE
+
+.SH FILES
+.I /etc/fxotune.conf
+.RS
+The configuration file generated by fxotune in detect mode and from which
+configuration is loaded when 
+.B -s
+is used.
+
+.SH NOTES
+Running fxotune takes approximately a minute per port. If you wish to only 
+run fxotune for several ports, you can use the options -b and -e to set a 
+specific range of ports. Another useful trick is to actually keep asterisk 
+running, and only "destroy" the dahdi channels you wish to tune (dahdi 
+destroy channel NNN): other channels will be used by Asterisk, and hence 
+skipped. This can be useful if you have many FXO ports that are not connected.
+
+.B fxotune
+writes immedietly to 
+.B /etc/fxotune.conf
+so if you stop it half-way, you may get a half-configured system. If you
+have already tuned your FXO channels and wish to test-run fxotune again, 
+you are advised to backup /etc/fxotune.conf .
+
+The default for -m is 18 seconds. This asusmes that you get a clear line 
+for at least 18 seconds. It is advised that you test that timeout earlier
+by connecting a phone to the FXO line, dialing 4 (or whatever dial string 
+you put with -n) and see how much time of silence you have.
+
+If you connect your device to a PSTN provider that is not in the US, there
+is a similar operation you should apply before even getting to fxotune:
+setting the opermode. The opermode sets a number of country-specific 
+parameters. For the Digium analog cards this is set through the kernel module 
+parameter 'opermode' . For the Xorcom Astribank this is set through the 
+variable 'opermode' in /etc/dahdi/xpp.conf .
+For valid values of this parameter, see
+/usr/share/asterisk/init_fxo_modes (FIXME: this has changed and will
+change. Tzafrir).
+
+.SH SEE ALSO 
+dahdi_cfg(8), dahdi_tool(8), dahdi_monitor(8), asterisk(8). 
+
+.SH AUTHOR 
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
+
+On Debian systems, the complete text of the GNU General Public 
+License can be found in /usr/share/common-licenses/GPL. 
diff --git a/doc/fxstest.8 b/doc/fxstest.8
new file mode 100644
index 0000000..6caa855
--- /dev/null
+++ b/doc/fxstest.8
@@ -0,0 +1,60 @@
+.TH "FXSTEST" "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
+
+.SH NAME
+fxstest \- Simple tests for Zaptel FXS adapters
+.SH SYNOPSIS
+
+.B fxstest /dev/dahdi/\fIN comand\fR
+
+.SH DESCRIPTION
+fxstest can be used to issue one of a number simple tests to FXS
+adapters (analog adapters intended to connect phones). 
+
+.SH OPTIONS
+All of those tests operate on a single dahdi channel which has to be an
+FXS port, and must not be in use by Asterisk or any other program.
+
+The command has two mandatory parameters.
+The first parameter is the device file to operate on. It is typically
+/dev/dahdi/NN , a device file under /dev/dahdi .
+
+The second parameter is the name of the command to run on that channel:
+
+.I stats
+.RS
+Reports voltages
+.RE
+
+.I regdump
+.RS
+Dumps ProSLIC registers
+.RE
+
+.I tones
+.RS
+Plays a series of tones
+.RE
+
+.I polarity
+.RS
+Requests channel to reverse polarity.
+.RE
+
+.I ring
+.RS
+Rings phone
+.RE
+
+.SH "SEE ALSO"
+.PP
+dahdi_tool(8), dahdi_cfg(8), dahdi_monitor(8), asterisk(8).
+.SH BUGS
+Does not allow testing channels beyond 249. Should support opening
+channels through /dev/dahdi/channel .
+.SH AUTHOR
+.PP
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> .
+Permission is granted to copy, distribute and/or modify this document 
+under the terms of the GNU General Public License, Version 2 any 
+later version published by the Free Software Foundation.
+.PP
diff --git a/doc/patgen.8 b/doc/patgen.8
new file mode 100644
index 0000000..1e5102e
--- /dev/null
+++ b/doc/patgen.8
@@ -0,0 +1,42 @@
+.TH patgen 8 "2008-01-08" 
+.SH NAME 
+patgen \(em Generates a Pattern for a DAHDI Clear Channel Test
+.SH SYNOPSIS 
+.B patgen 
+.I dahdi-device
+
+.SH DESCRIPTION 
+.B patgen
+Sends test data to a DAHDI channel. The channel should be of CLEAR
+signalling (e.g: B channel of a PRI line). pattest(8) is used to test
+the data at the other side.  See its manual for more information.
+
+.B patgen
+Must be able to write to the channel. Hence this cannot be used for a
+channel used by Asterisk.
+
+.SH OPTIONS
+.I dahdi-device
+.RS
+A DAHDI device file.
+.RE
+
+.SH EXAMPLE
+  patgen /dev/dahdi/5
+
+.SH BUGS
+Will not work with channels whose number > 249 as they don't have device
+files. For a simple workaround, see dahdi_diag.c .
+
+.SH SEE ALSO 
+pattest(8), dahdi_cfg(8), asterisk(8). 
+
+.SH AUTHOR 
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
+ 
+On Debian systems, the complete text of the GNU General Public 
+License can be found in /usr/share/common-licenses/GPL. 
diff --git a/doc/pattest.8 b/doc/pattest.8
new file mode 100644
index 0000000..0211c8d
--- /dev/null
+++ b/doc/pattest.8
@@ -0,0 +1,48 @@
+.TH pattest 8 "2008-01-08" 
+.SH NAME 
+pattest \(em Tests a Pattern for a DAHDI Clear Channel Test
+.SH SYNOPSIS 
+.B pattest 
+.I dahdi-device
+
+.SH DESCRIPTION 
+.B pattest
+Recieves test data from a DAHDI channel and checks if it matches the 
+test pattern. The channel should be of CLEAR signalling (e.g: B channel 
+of a PRI line). patgen(8) is used to generate the data at the other side.  
+
+.B pattest
+Must be able to read from the channel. Hence this cannot be used for a
+channel used by Asterisk.
+
+The pattern is a simple series of values from 0 to 255. Hence it takes
+at most one sample to get in sync with the other side. If there is no
+output, all is well. Output is an error message.
+
+.SH OPTIONS
+.I dahdi-device
+.RS
+A DAHDI device file.
+.RE
+
+.SH EXAMPLE
+  pattest /dev/dahdi/5
+
+.SH BUGS
+Will not work with channels whose number > 249 as they don't have device
+files. For a simple workaround, see dahdi_diag.c .
+
+Gives way too many errors when does not get any input.
+
+.SH SEE ALSO 
+patgen(8), dahdi_cfg(8), asterisk(8). 
+
+.SH AUTHOR 
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
+Permission is granted to copy, distribute and/or modify this document under 
+the terms of the GNU General Public License, Version 2 any  
+later version published by the Free Software Foundation. 
+ 
+On Debian systems, the complete text of the GNU General Public 
+License can be found in /usr/share/common-licenses/GPL.