Man pages for span_types and span_assignments

Signed-off-by: Tzafrir Cohen <tzafrir.cohen@xorcom.com>
This commit is contained in:
Tzafrir Cohen 2013-10-13 23:28:29 +03:00
parent 2f688f83c4
commit 5e30a1401f
3 changed files with 399 additions and 3 deletions

222
doc/span_assignments.8 Normal file
View File

@ -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.

146
doc/span_types.8 Normal file
View File

@ -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.

View File

@ -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 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). 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 dahdi_registration is intended to be used when the kernel module parameter
B<dahdi_autoreg> is false (and implicitly: when the dahdi module parameter B<xpp.dahdi_autoreg> is false (and implicitly: when the module parameter
B<auto_assign_span> is true. 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. 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. than all of them.
=back =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).