[Pkg-voip-commits] [dahdi-tools] 120/285: Man pages for span_types and span_assignments
tzafrir at debian.org
tzafrir at debian.org
Thu Jul 7 19:18:42 UTC 2016
This is an automated email from the git hooks/post-receive script.
tzafrir pushed a commit to branch master
in repository dahdi-tools.
commit 5e30a1401f046f651aea221bc9e4852bf942eddf
Author: Tzafrir Cohen <tzafrir.cohen at xorcom.com>
Date: Sun Oct 13 23:28:29 2013 +0300
Man pages for span_types and span_assignments
Signed-off-by: Tzafrir Cohen <tzafrir.cohen at xorcom.com>
---
doc/span_assignments.8 | 222 +++++++++++++++++++++++++++++++++++++++++++++++++
doc/span_types.8 | 146 ++++++++++++++++++++++++++++++++
xpp/dahdi_registration | 34 +++++++-
3 files changed, 399 insertions(+), 3 deletions(-)
diff --git a/doc/span_assignments.8 b/doc/span_assignments.8
new file mode 100644
index 0000000..d517a74
--- /dev/null
+++ b/doc/span_assignments.8
@@ -0,0 +1,222 @@
+.TH "SPAN_ASSIGNMENTS" "8" "13 Oct 2013" "" ""
+
+.SH NAME
+span_assignments \- handle DAHDI spans registration
+.SH SYNOPSIS
+
+.B span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] <add|remove> \fIdevpath
+\fB[\fIdevpath \fB...]
+
+.B span_assignments [\-v|\-\-verbose] [\-n|\-\-dry\-run] auto
+
+.B span_assignments [\-v|\-\-verbose] list
+
+.B span_assignments [\-v|\-\-verbose] [\-k|\-\-key \fIkey\fB] dumpconfig
+
+.B span_assignments \-h|\-\-help
+
+.SH DESCRIPTION
+When the kernel module parameter \fBdahdi.auto_assign_span\fR is unset,
+DAHDI devices (such as DAHDI PCI cards) that register with DAHDI don't
+register their spans (e.g.: each digital port is normally a span) with
+DAHDI. This allows user-space to order DAHDI to register them to specific
+span and channel numbers. This allows registering different spans out of
+order.
+
+.B span_assignments
+is used to register those spans or to help creating the configuration
+file used in their registration:
+.B /etc/dahdi/pinned-spans.conf .
+
+.SH OPTIONS
+
+There are several sub-commands:
+
+.B add \fIdevpath \fB[\fIdevpath \fB...]
+.RS
+Parameters are paths (in SysFS) to DAHDI devices with unregistered
+spans. The command will register with DAHDI according to according to
+configuration in \fBpinned-spans.conf\fR.
+.RE
+
+.B remove \fIdevpath \fB[\fIdevpath \fB...]
+.RS
+Parameters are paths (in SysFS) to DAHDI devices with registered
+spans. The command will unregister with DAHDI.
+.RE
+
+.B auto
+.RS
+Register all non-registered spans. Each span registers to first
+available span number and channel numbers, as if
+\fBdahdi.auto_assign_span\fR was set.
+.RE
+
+.B list
+.RS
+List all spans in the system.
+.RE
+
+.B dumpconfig
+.RS
+List all registered spans in the system in a format fit to be used in
+\fBpinned-spans.conf\fR. Use this to generate a configuration file after
+you have (perhaps manually) registered all existing spans.
+
+.B dahdi_genconf pinnedspans
+uses this command internally.
+.RE
+
+.B \-v \-\-verbose
+.RS
+Verbose output.
+.RE
+
+.B \-n \-\-dry\-run
+.RS
+Don't register / unregister spans. Only print commands used to do so.
+.RE
+
+.B \-k \fIkey
+.RS
+For \fBdumpconfig\fR \- The key by which to identify the hardware in the
+generated configuration. Legal values:
+
+.B hwid
+.RS
+Hardware identifier (e.g.: software-readable serial number). This is the
+default. If the device has no hwid, devpath is used.
+.RE
+
+.B location
+.RS
+The location field (file) in the SysFS device node (directory) for the
+DAHDI device. If not available (typically: DAHDI version <= 2.7.x),
+devpath is used.
+.RE
+
+.B devpath
+.RS
+Path in SysFS to the device node.
+.RE
+.RE
+
+.SH CONFIGURATOIN
+.B pinned-spans.conf
+is a file with lines specifying registration of spans.
+
+Empty lines or lines beginning with '#' are ignored.
+
+Each line is in the format of:
+
+.I ID spanspec ...
+
+The \fIID\fR field specifies the DAHDI device and the \fIspanspecs\fR
+define how to register its spans. A line may have multiple
+\fIspanspecs\fR in a single line (though dumpconfig generates a
+configuration with one per line).
+
+.SS Span Identifier
+A DAHDI device may be specified either by a hardware identifier (a
+software readable serial number or whatever) or the location in which
+it is installed on the system. The former makes it simpler to change
+connector / slot whereas the latter makes it simpler to replace a unit.
+
+The value in this field is matched (when the commands \fBadd\fR and
+\fBremove\fR) are used) to the following values:
+
+ \fIhwid\fR
+ \fB@\fIlocation\fR
+ \fIdevpath\fR
+
+See above for their descriptions. The value may include shell wildcards:
+*, ? and [], which are used in the match. The values to be matched are
+first cleaned up: '!' is replaced with '/' and any character beyond
+"a-zA-Z0-9/:.-" is removed.
+
+.SS Span Specification
+
+Each line should have one or more span specifications: this is the value
+used to register a span with DAHDI in the SysFS interface. A
+specification has three colon-separated numbers:
+
+.I rel_span_no:span_no:first_chan
+
+for instance, the following are four span specifications for a quad-E1
+device: 1:6:53 2:7:84 3:8:115 4:9:146 occupying spans 6-9 and channels
+53-176.
+
+.B rel_span_no
+.RS
+The relative number of the span in the device. E.g.: port number.
+.RE
+
+.B span_no
+.RS
+The desired DAHDI span number. Must be available.
+.RE
+
+.B first_chan
+.RS
+The desired DAHDI channel number for the first DAHDI channel in the span.
+All channels of the span will be registered following it and hence that
+space must be available.
+.RE
+
+
+.SH ENVIRONMENT
+
+.B DAHDICONFDIR
+.RS
+The directory in which pinned-spans.conf resides. /etc/dahdi if not
+overridden from the environment.
+.RE
+
+.B pinned_spans_conf
+.RS
+The path to pinned-spans.conf resides. /etc/dahdi/pinned-spans.conf if
+not overridden from the environment.
+.RE
+
+.B SPAN_ASSIGNMENTS_KEY
+.RS
+The default value for \-k . Defaults to "hwid" if not overridden from the
+environment.
+.RE
+
+
+.SH FILES
+
+.B /etc/dahdi/pinned-spans.conf
+.RS
+The default location for the configuration file.
+.RE
+
+.B /sys/bus/dahdi_devices/devices/\fIdevice\fR
+.RS
+SysFS node for the device. In this directory reside the following
+files, among others:
+
+.B location
+.RS
+The value of the device's location field.
+.RE
+
+.B assign_span, unassign_span, auto_assign
+.RS
+Write only files for the operations. Used by \fBadd\fR, \fBremove\fR and
+\fBauto\fR, respectively.
+.RE
+
+.RE
+
+.SH SEE ALSO
+span_types(8), dahdi_genconf(8), dahdi_cfg(8)
+
+.SH AUTHOR
+span_assignments was written by Oron Peled. This manual page was
+written by Tzafrir Cohen. 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/span_types.8 b/doc/span_types.8
new file mode 100644
index 0000000..4c7dd25
--- /dev/null
+++ b/doc/span_types.8
@@ -0,0 +1,146 @@
+.TH "SPAN_ASSIGNMENTS" "8" "13 Oct 2013" "" ""
+
+.SH NAME
+span_assignments \- set DAHDI spans properties before registration (E1/T1)
+.SH SYNOPSIS
+
+.B span_assignments <list|dumpconfig|set> [\fIdevpath \fB[\fIdevpath \fB...]]
+
+.SH DESCRIPTION
+The span type (E1/T1/J1) must be set to a span before registering it
+with DAHDI, as E1 spans use more channels. \fBspan_types\fR applies the
+span type configuration to an unregistered span.
+
+Using it only makes sense when the kernel module parameter
+\fBdahdi.auto_assign_span\fR is unset, otherwise the DAHDI spans register
+automatically.
+
+.SH OPTIONS
+.B span_types
+takes a command and an optional list of devices. If no device is given,
+the command is applied to all devices.
+
+The device is marked as a path in the SysFS tree.
+
+.B set
+.RS
+Reads settings from \fBspan-types.conf\fR and applies them to the
+device(s) specified in the command line (or all devices, if none
+specified).
+.RE
+
+.B list
+.RS
+List types for all spans in the system which may be set with span_types
+(E1/T1/J1 spans).
+.RE
+
+.B dumpconfig
+.RS
+List types for the spans in a format fit to be used in
+\fBspan-types.conf\fR. Use this to generate a configuration file after
+you have (perhaps manually) set all existing spans.
+
+.B dahdi_genconf spantypes
+uses this command internally.
+.RE
+
+.SH CONFIGURATION
+.B span-types.conf
+is a file with lines specifying registration of spans.
+
+Empty lines or lines beginning with '#' are ignored.
+
+Each line is in the format of:
+
+.I ID spanspec ...
+
+The \fIID\fR field specifies the DAHDI device and the \fIspanspecs\fR
+define how to register its spans. A line may have multiple
+\fIspanspecs\fR in a single line (though dumpconfig generates a
+configuration with one per line).
+
+.SS Span Identifier
+A DAHDI device may be specified either by a hardware identifier (a
+software readable serial number or whatever) or the location in which
+it is installed on the system. The former makes it simpler to change
+connector / slot whereas the latter makes it simpler to replace a unit.
+
+The value in this field is matched (when the commands \fBadd\fR and
+\fBremove\fR) are used) to the following values:
+
+ \fIhwid\fR
+ \fB@\fIlocation\fR
+ \fIdevpath\fR
+
+See above for their descriptions. The value may include shell wildcards:
+*, ? and [], which are used in the match. The values to be matched are
+first cleaned up: '!' is replaced with '/' and any character beyond
+"a-zA-Z0-9/:.-" is removed.
+
+.SS Span Specification
+
+Each line should have one or more span specifications: this is the value
+used to register a span with DAHDI in the SysFS interface. A
+specification has three colon-separated numbers:
+
+.I rel_span_no:span_type
+
+for instance, the following are four span specifications specify ports 1 and 2 as E1 and ports 3 and 4 as T1: [12]:E1 [34]:T1 .
+
+.B rel_span_no
+.RS
+The relative number of the span in the device. E.g.: port number.
+.RE
+
+.B span_type
+.RS
+E1/T1/J1
+.RE
+
+
+.SH ENVIRONMENT
+
+.B DAHDICONFDIR
+.RS
+The directory in which span-types.conf resides. /etc/dahdi if not
+overridden from the environment.
+.RE
+
+.B span_types_conf
+.RS
+The path to span-types.conf resides. /etc/dahdi/span-types.conf if
+not overridden from the environment.
+.RE
+
+
+.SH FILES
+
+.B /etc/dahdi/span-types.conf
+.RS
+The default location for the configuration file.
+.RE
+
+.B /sys/bus/dahdi_devices/devices/\fIdevice\fR
+.RS
+SysFS node for the device. In this directory reside the following
+files, among others:
+
+.B spantype
+.RS
+read/write file. Reading from it returns current configuration for spans
+of the device. Span-specifications can be written to it to change types
+(but only for a span that is not registered).
+.RE
+
+
+.SH SEE ALSO
+span_assignments(8), dahdi_genconf(8), dahdi_cfg(8)
+
+.SH AUTHOR
+span_assignments was written by Oron Peled. This manual page was
+written by Tzafrir Cohen. 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/xpp/dahdi_registration b/xpp/dahdi_registration
index cdd715d..eb1579a 100755
--- a/xpp/dahdi_registration
+++ b/xpp/dahdi_registration
@@ -134,9 +134,10 @@ Span registration should generally always succeed. Span unregistration may
fail if channels from the span are in use by e.g. asterisk. In such a case
you'll also see those channels as '(In use)' in the output of lsdahdi(8).
-dahdi_registration is intended to be used when the xpp module parameter
-B<dahdi_autoreg> is false (and implicitly: when the dahdi module parameter
-B<auto_assign_span> is true.
+dahdi_registration is intended to be used when the kernel module parameter
+B<xpp.dahdi_autoreg> is false (and implicitly: when the module parameter
+B<dahdi.auto_assign_span> is true). See also the NOTES section regarding
+C<span_assignments>.
If dahdi_autoreg is true, the program will normally do nothing.
@@ -209,3 +210,30 @@ This should allow you to register / unregister a specific XPD rather
than all of them.
=back
+
+=head1 NOTES
+
+dahdi_registration is intended to be used when the kernel module
+parameter B<xpp.dahdi_autoreg> is false (and implicitly: when the module
+parameter B<dahdi.auto_assign_span> is true), that is, Astribank devices
+as detected by XPP (xbus / xpd) do not register automatically with the
+DAHDI core. This tool is used to register tem in an explicit order. It
+works well, but only if you can arange for all of the Astribanks of the
+system to be available (and not already registered) at a specific point
+in time.
+
+Newer versions of DAHDI added support for registering a span to a
+specific span/channelss numbers specification. This allows registering
+them out of order. To use this capability, the module parameter
+B<dahdi.auto_assign_span> should be unset (set to 0) and thus spans of
+detected DAHDI devices could be registered using C<span_assignments>
+(which may also be run automatically from a udev hook).
+
+In this case there is no point in delaying XPP device registration with
+dahdi and the parameter B<xpp.dahdi_autoreg> should be set.
+dahdi_registration will simply become a no-op.
+
+=head1 SEE ALSO
+
+B<dahdi_cfg>(8), B<span_assignments>(8).
+
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-voip/dahdi-tools.git
More information about the Pkg-voip-commits
mailing list