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] \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 [\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 is false (and implicitly: when the dahdi module parameter -B is true. +dahdi_registration is intended to be used when the kernel module parameter +B is false (and implicitly: when the module parameter +B is true). See also the NOTES section regarding +C. 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 is false (and implicitly: when the module +parameter B 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 should be unset (set to 0) and thus spans of +detected DAHDI devices could be registered using C +(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 should be set. +dahdi_registration will simply become a no-op. + +=head1 SEE ALSO + +B(8), B(8). +