dahdi_span_types: allow defaults + overrides

* Allow wildcards for both device and span number (as before).
  Example:
     *        *:T1

* But now we are carefull to follow strict order in the configuration
  file. This means, if there are multiple matches -- last one wins.

* So we can use specialisation:
     *        *:T1	# Everything is T1
     FOO      [34]:T1	# Except spans 3,4 on the FOO device

* Added --dry-run and --verbose options.

* Updated the man-page:
  - Fixed "registered" => "assigned".
  - Use "line mode" for E1/J1/T1.
  - Document current changes.

Signed-off-by: Tzafrir Cohen <tzafrir.cohen@xorcom.com>
Acked-By: Russ Meyerriecks <rmeyerriecks@digium.com>

dahdi_span_types

@@ -27,6 +27,19 @@
 #   - "@location"  - Location attribute from sysfs (embeded inside '<>')
 #   - "/devpath"   - The sysfs absolute devpath
 #
+# * Wildcard are allowed in the configuration file:
+#   - In the device specifiers (keys)
+#   - In the span numbers
+#   - Example for "match-all":    *   *:T1
+#
+# * During "set":
+#   - If there are multiple matches, for a span, all are applied
+#   - They are always applied in their order in the configuration file
+#   - This means the last match wins
+#   - Example:
+#         *                   *:T1        # All span on all devices are T1
+#         usb:X1234567        [34]:E1	   # Except spans 3,4 on specific device
+#
 # * During "dumpconfig", for each device we take the first available key:
 #   - The preference is: "hwid" or else "@location" or else "/devpath"
 #   - This can be overriden via the SPAN_ASSIGNMENTS_KEY environment variable
@@ -34,6 +47,8 @@
 #
 # Command line options:
 #  - The '-h|--help' show a usage message.
+#  - The '-v|--verbose' show debugging messages (on stderr)
+#  - The '-n|--dry-run' During "set", only show what would be done
 #  - The '-k <key>|--key <key>' overrides the SPAN_ASSIGNMENTS_KEY environment
 #    variable.
 #
@@ -59,12 +74,14 @@ usage() {
 	echo >&2 ""
 	echo >&2 "       options:"
 	echo >&2 "         -h|--help      - Show this help"
+	echo >&2 "         -v|--verbose'  - Show debugging messages (on stderr)"
+	echo >&2 "         -n|--dry-run'  - During 'set', only show what would be done"
 	echo >&2 "         -k|--key <k>   - Override prefered key during dumpconfig action"
 	exit 1
 }
 
 # Parse command line options
-TEMP=`getopt -o hk: --long help,key: -n "$0" -- "$@"`
+TEMP=`getopt -o hnvk: --long help,dry-run,verbose,key: -n "$0" -- "$@"`
 if [ $? != 0 ]; then
 	echo >&2 "Bad options"
 	usage
@@ -78,6 +95,14 @@ while true ; do
 	-h|--help)
 		usage
 		;;
+	-n|--dry-run)
+		shift
+		dry_run=true
+		;;
+	-v|--verbose)
+		shift
+		verbose=true
+		;;
 	-k|--key)
 		SPAN_ASSIGNMENTS_KEY="$2"
 		shift
@@ -138,11 +163,12 @@ show_spantypes() {
 		cat "$device/spantype" | while read st; do
 			case "$st" in
 			*:[ETJ]1)
-				printf "%-10s %-20s %s\n" \
+				printf "%-10s %-20s %-30s %s\n" \
-					"$st" "[$hardware_id]" "$location"
+					"$st" "[$hardware_id]" "$location" \
+					"$devpath"
 				;;
 			esac
-		done | sort -n
+		done
 	done
 }
 
@@ -185,70 +211,78 @@ filter_conf() {
 	sed -e 's/#.*//' -e '/^[ \t]*$/d' "$DAHDISPANTYPESCONF"
 }
 
-conf_spans() {
+handle_span() {
-	hardware_id="$1"
+	device="$1"
-	location="$2"
+	spantype="$2"
-	devpath="$3"
+	attr_file="$device/spantype"
-	filter_conf | (
+	devpath=`cd "$device" && pwd -P`
-		# Collect device spans
+	devname=`echo "$device" | sed "s,$devbase/,,"`
-		# in a subshell, so $SPANS is not lost
+	location='@'`attr_clean "$device/location"`
-		SPANS=''
+	hardware_id=`attr_clean "$device/hardware_id"`
-		while read id spans; do
+	spanno=`echo "$spantype" | cut -d: -f1`
+	#echo >&2 "DEBUG: $device $spanno ($spantype)"
+	filter_conf | while read id span_spec; do
+			sn=`echo "$span_spec" | cut -d: -f1`
+			val=`echo "$span_spec" | cut -d: -f2`
+			case "$spanno" in
+			$sn)
+				;;
+			*)
+				#echo >&2 "no-match($device $spanno): $sn"
+				continue
+				;;
+			esac
+			found=no
 			# GLOBBING
 			case "$location" in
 			$id)
-				#echo >&2 "match($id): $spans"
+				#echo >&2 "match($id): $span_spec"
-				SPANS="$SPANS $spans"
+				found=yes
 				;;
 			esac
 			case "$hardware_id" in
 			$id)
-				#echo >&2 "match([$id]): $spans"
+				#echo >&2 "match([$id]): $span_spec"
-				SPANS="$SPANS $spans"
+				found=yes
 				;;
 			esac
 			case "$devpath" in
 			$id)
-				#echo >&2 "match([$id]): $spans"
+				#echo >&2 "match([$id]): $span_spec"
-				SPANS="$SPANS $spans"
+				found=yes
 				;;
 			esac
-		done
+			if [ "$found" = 'yes' ]; then
-		echo "$SPANS"
+				if [ "$dry_run" = 'true' -o "$verbose" = 'true' ]; then
-	)
+					echo >&2 "Set $devname span $spanno = $val"
-}
+				fi
-
+				if [ "$dry_run" != 'true' ]; then
-device_set_spantype() {
+					echo "$spanno:$val" > "$attr_file"
-	device="$1"
+				fi
-	attr_file="$device/spantype"
+			fi
-	devpath=`cd "$device" && pwd -P`
-	location='@'`attr_clean "$device/location"`
-	hardware_id=`attr_clean "$device/hardware_id"`
-	spanspecs=`conf_spans "$hardware_id" "$location" "$devpath"`
-	#echo >&2 "MATCHED($device): $spanspecs"
-	cut -d: -f1 "$attr_file" | while read spanno; do
-			for sp in $spanspecs
-			do
-				s=`echo "$sp" | cut -d: -f1`
-				v=`echo "$sp" | cut -d: -f2`
-				case "$spanno" in
-				$s)
-					#echo >&2 "conf($attr_file): $spanno:$v"
-					echo "$spanno:$v" > "$attr_file"
-					;;
-				esac
-			done
 		done
 }
 
-set_spantypes() {
+set_all_devices() {
 	if [ ! -f "$DAHDISPANTYPESCONF" ]; then
 		echo >&2 "$0: Missing configuration '$DAHDISPANTYPESCONF'"
 		exit 1
 	fi
 	for device in $DEVICES
 	do
-		device_set_spantype "$device"
+		devname=`echo "$device" | sed "s,$devbase/,,"`
+		cat "$device/spantype" | while read spantype; do
+			case "$spantype" in
+			*:[ETJ]1)
+				handle_span "$device" "$spantype"
+				;;
+			*)
+				if [ "$dry_run" = 'true' -o "$verbose" = 'true' ]; then
+					echo >&2 "Skipping non-E1/T1/J1 span ($devname -- $spantype)"
+				fi
+				;;
+			esac
+		done
 	done
 }
 
@@ -260,7 +294,7 @@ dumpconfig)
 	dump_config
 	;;
 set)
-	set_spantypes
+	set_all_devices
 	;;
 *)
 	usage

doc/dahdi_span_types.8

@@ -1,27 +1,46 @@
-.TH "SPAN_TYPES" "8" "13 Oct 2013" "" ""
+.TH "DAHDI_SPAN_TYPES" "8" "23 Jan 2014" "" ""
 
 .SH NAME
-dahdi_span_types \- set DAHDI spans properties before registration (E1/T1)
+dahdi_span_types \- set line modes of DAHDI spans before assignment
 .SH SYNOPSIS
 
-.B dahdi_span_types <list|dumpconfig|set> [\fIdevpath \fB[\fIdevpath \fB...]]
+.B dahdi_span_types [\fIoptions\fB] <list|dumpconfig|set> \fB[\fIdevpath \fB...]
 
 .SH DESCRIPTION
-The span type (E1/T1/J1) must be set to a span before registering it
+The span type (the line mode: E1/T1/J1) must be set to a span before
-with DAHDI, as E1 spans use more channels. \fBdahdi_span_types\fR applies the
+DAHDI assigns it a span number, as E1 spans use more channels.
-span type configuration to an unregistered span.
+\fBdahdi_span_types\fR applies the span type configuration to an
+un-assigned span.
 
 Using it only makes sense when the kernel module parameter
-\fBdahdi.auto_assign_span\fR is unset, otherwise the DAHDI spans register
+\fBdahdi.auto_assign_span\fR is unset, otherwise DAHDI automatically
-automatically.
+assign span numbers during device registration.
 
-.SH OPTIONS
 .B dahdi_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.
 
+.SH OPTIONS
+
+.B -h|--help
+.RS
+Output usage message and exit
+.RE
+
+.B -n|--dry-run
+.RS
+During \fB"set"\fR operation, only show what would be done, without actually
+changing anything.
+.RE
+
+.B -v|--verbose
+.RS
+During \fB"set"\fR operation, show the actions that are being performed.
+.RE
+
+.SH SUB-COMMANDS
 .B set
 .RS
 Reads settings from \fBspan-types.conf\fR and applies them to the
@@ -31,8 +50,8 @@ specified).
 
 .B list
 .RS
-List types for all spans in the system which may be set with dahdi_span_types
+List line modes for all spans in the system which may be set with
-(E1/T1/J1 spans).
+dahdi_span_types (E1/T1/J1 spans).
 .RE
 
 .B dumpconfig
@@ -46,8 +65,9 @@ uses this command internally.
 .RE
 
 .SH CONFIGURATION
+.SS General structure
 .B span-types.conf
-is a file with lines specifying registration of spans.
+is a file with lines specifying line modes of spans.
 
 Empty lines or lines beginning with '#' are ignored.
 
@@ -56,7 +76,7 @@ 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
+define the line modes of its spans. A line may have multiple
 \fIspanspecs\fR in a single line (though dumpconfig generates a
 configuration with one per line).
 
@@ -66,8 +86,8 @@ 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
+The value in this field is matched (when the command \fBset\fR is
-\fBremove\fR) are used) to the following values:
+used) to the following values:
 
  \fIhwid\fR
  \fB@\fIlocation\fR
@@ -75,22 +95,28 @@ The value in this field is matched (when the commands \fBadd\fR and
 
 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
+first cleaned up: '!' is replaced with '/' and any character not in
-"a-zA-Z0-9/:.-" is removed.
+"a-zA-Z0-9/:.-" is replaced by "_".
+
+Note that while span\-types.conf allows an arbitrarily-complex
+combination of E1, J1 and T1 ports, it would normally have just a single
+wildcard line setting the line mode (the first line in the example below).
 
 .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
+used to set span type with DAHDI in the SysFS interface. A
-specification has three colon-separated numbers:
+specification has two colon-separated fields:
 
 .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 .
+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.
+This field may contain shell wildcards (*, ? and [])
 .RE
 
 .B span_type
@@ -98,6 +124,21 @@ The relative number of the span in the device. E.g.: port number.
 E1/T1/J1
 .RE
 
+.SS Multiple matches
+During \fBset\fR operation, the \fBdahdi_span_types\fR applies all
+matching settings to a span. This is done in the order of lines in the
+configuration files.
+
+Thus, if there are multiple matches to a span -- the last match
+will \fIwin\fR (all will be applied to the kernel in order. The last
+one in the file will be applied last).
+
+Example:
+.EX
+*             *:T1      # All spans on all devices will be T1
+usb:X1234567  [34]:E1   # Except spans 3,4 on the device which will be E1
+.EE
+
 
 .SH ENVIRONMENT
 
@@ -109,14 +150,14 @@ overridden from the environment.
 
 .B DAHDISPANTYPESCONF
 .RS
-The path to span-types.conf resides. /etc/dahdi/span-types.conf if
+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
+.B /etc/dahdi/span\-types.conf
 .RS
 The default location for the configuration file.
 .RE
@@ -129,8 +170,8 @@ 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
+of the device. Span-specifications can be written to it to change line
-(but only for a span that is not registered).
+modes (but only for a span that is not assigned yet).
 .RE