HO prep: introduce per-BTS handover config, with defaults on net node

It is desirable to allow configuring handover for each individual network cell.
At the same time, it is desirable to set global defaults.

Treat the 'network' node handover parameters as global defaults, add another
set of parameters for each individual BTS.

This raises questions on how the 'network' node should affect the individual
BTS. The simplistic solution would have been: on creating a BTS in the config,
just copy the current defaults; with serious drawbacks:
- tweaking any parameter in the telnet VTY on network node will never affect
  any running BTS.
- network node defaults *must* be issued before the bts sections in the config
  file.
- when writing a config back to file, we would copy all net node defaults to
  each BTS node, making the network node configs pointless.

Instead, add a handover_cfg API that tracks whether a given node has a value
set or not. A bts node ho_cfg gets a pointer to the network node config and
returns those values if locally unset. If no value is set on any node, use the
"factory" defaults, which are hardcoded in the API. Only write back exactly
those config items that were actually issued in a config file / on the telnet
VTY. (ho_cfg API wise, we could trivially add another ho_cfg level per TRX if
we so desire in the future.)

Implement ho parameters as an opaque config struct with getters and setters to
ensure the tracking is always heeded. Opaqueness dictates allocating instead of
direct embedding in gsm_network and gsm_bts structs, ctx is gsm_net / bts.

This is 100% backwards compatible to
old configs.
- No VTY command syntax changes (only the online help).
- If a 'bts' sets nothing, it will use the 'network' defaults.
- The 'show network' output only changes in presence of individual BTS configs.

On 'show network', say "Handover: On|Off" as before, iff all BTS reflect
identical behavior. Otherwise, output BTS counts of handover being enabled or
not.

Use the same set of VTY commands (same VTY cmd syntax as before) on network and
BTS nodes, i.e. don't duplicate VTY code. From the current vty->node, figure
out which ho_cfg to modify.

For linking, add handover_cfg.c (the value API) in libcommon, while the
handover_vty.c is in libbsc. This is mainly because some utility programs use
gsm_network and hence suck in the ho stuff, but don't need the VTY commands.

Review the VTY online help strings.

Add VTY transcript test for handover options, testing config propagation from
network to bts nodes, 'show network' output and VTY online help strings.
(Needs recent addition of '... !' wildcard to osmo_interact_common.py.)

I considered leaving parts of this more readable, but in the end decided for
heavy use of macros to define and declare the API, because more values will be
added in upcoming patches and I want to prevent myself from messing them up.

Inspired-by: jolly/new_handover branch, which moves the config to 'bts' level
Depends: I7c1ebb2e7f059047903a53de26a0ec1ce7fa9b98 (osmo-python-tests)
Change-Id: I79d35f6d3c0fbee67904378ad7f216df34fde79a

2 files changed, 290 insertions, 0 deletions

diff --git a/tests/Makefile.am b/tests/Makefile.am
index 9207434f0..ba8a5e140 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -34,6 +34,7 @@ EXTRA_DIST = \
 	$(TESTSUITE) \
 	vty_test_runner.py \
 	ctrl_test_runner.py \
+	handover_cfg.vty \
 	$(NULL)
 
 TESTSUITE = $(srcdir)/testsuite
@@ -44,11 +45,21 @@ DISTCLEANFILES = \
 
 if ENABLE_EXT_TESTS
 python-tests: $(BUILT_SOURCES)
+	$(MAKE) vty-test
 	osmotestvty.py -p $(abs_top_srcdir) -w $(abs_top_builddir) -v
 	osmotestconfig.py -p $(abs_top_srcdir) -w $(abs_top_builddir) -v
 	$(srcdir)/vty_test_runner.py -w $(abs_top_builddir) -v
 	$(srcdir)/ctrl_test_runner.py -w $(abs_top_builddir) -v
 	rm -f $(top_builddir)/sms.db $(top_builddir)/gsn_restart $(top_builddir)/gtphub_restart_count
+
+# To update the VTY script from current application behavior,
+# pass -u to vty_script_runner.py by doing:
+#   make vty-test U=-u
+vty-test:
+	osmo_verify_transcript_vty.py -v \
+		-n OsmoBSC -p 4242 \
+		-r "$(top_builddir)/src/osmo-bsc/osmo-bsc -c $(top_srcdir)/doc/examples/osmo-bsc/osmo-bsc-minimal.cfg" \
+		$(U) $(srcdir)/*.vty
 else
 python-tests: $(BUILT_SOURCES)
 	echo "Not running python-based tests (determined at configure-time)"
diff --git a/tests/handover_cfg.vty b/tests/handover_cfg.vty
new file mode 100644
index 000000000..e181797f6
--- /dev/null
+++ b/tests/handover_cfg.vty
@@ -0,0 +1,279 @@
+OsmoBSC> show network
+...
+  Handover: Off
+...
+OsmoBSC> enable
+
+OsmoBSC# ### No handover config present
+OsmoBSC# show running-config
+... !handover
+
+OsmoBSC# ### Toggling handover on network level affects 'show network':
+OsmoBSC# configure terminal
+OsmoBSC(config)# network
+OsmoBSC(config-net)# do show network
+...
+  Handover: Off
+...
+OsmoBSC(config-net)# handover 1
+OsmoBSC(config-net)# do show network
+...
+  Handover: On
+...
+
+OsmoBSC(config-net)# ### If network level default is 'on', bts level can still override to 'off':
+OsmoBSC(config-net)# bts 0
+OsmoBSC(config-net-bts)# handover 0
+OsmoBSC(config-net-bts)# do show network
+...
+  Handover: Off
+...
+OsmoBSC(config-net-bts)# exit
+
+OsmoBSC(config-net)# ### Create a *second* BTS that is not explicitly 'off':
+OsmoBSC(config-net)# bts 1
+OsmoBSC(config-net-bts)# do show network
+...
+  Handover: On at 1 BTS, Off at 1 BTS
+...
+
+OsmoBSC(config-net-bts)# ### Add arbitrary handover config item for bts 1:
+OsmoBSC(config-net-bts)# handover power budget interval 23
+OsmoBSC(config-net-bts)# exit
+OsmoBSC(config-net)# ### HO is 'on' globally, bts 0 disables it, bts 1 tweaks a param:
+OsmoBSC(config-net)# show running-config
+...
+network
+... !handover
+ handover 1
+... !handover
+ bts 0
+... !handover
+  handover 0
+... !handover
+ bts 1
+... !handover
+  handover power budget interval 23
+... !handover
+
+OsmoBSC(config-net)# ### Set global default to 'off', now bts 1 also uses the global default of 'off':
+OsmoBSC(config-net)# handover 0
+OsmoBSC(config-net)# do show network
+...
+  Handover: Off
+...
+OsmoBSC(config-net)# show running-config
+...
+network
+... !handover
+ handover 0
+... !handover
+ bts 0
+... !handover
+  handover 0
+... !handover
+ bts 1
+... !handover
+  handover power budget interval 23
+... !handover
+
+OsmoBSC(config-net)# ### Remove the global setting, i.e. use the factory default net level, with same effect:
+OsmoBSC(config-net)# handover default
+% 'handover' setting removed, now is 0
+OsmoBSC(config-net)# handover default
+% 'handover' already was unset, still is 0
+OsmoBSC(config-net)# do show network
+...
+  Handover: Off
+...
+OsmoBSC(config-net)# show running-config
+...
+network
+... !handover
+ bts 0
+... !handover
+  handover 0
+... !handover
+ bts 1
+... !handover
+  handover power budget interval 23
+... !handover
+
+OsmoBSC(config-net)# ### Re-enable net-level handover, but bts 0 remains disabled explicitly
+OsmoBSC(config-net)# handover 1
+OsmoBSC(config-net)# do show network
+...
+  Handover: On at 1 BTS, Off at 1 BTS
+...
+OsmoBSC(config-net)# show running-config
+...
+network
+... !handover
+ handover 1
+... !handover
+ bts 0
+... !handover
+  handover 0
+... !handover
+ bts 1
+... !handover
+  handover power budget interval 23
+... !handover
+
+OsmoBSC(config-net)# ### Remove explicit setting of bts 0 to also use the global setting:
+OsmoBSC(config-net)# bts 0
+OsmoBSC(config-net-bts)# handover default
+% 'handover' setting removed, now is 1 (set on higher level node)
+OsmoBSC(config-net-bts)# handover default
+% 'handover' already was unset, still is 1 (set on higher level node)
+OsmoBSC(config-net-bts)# do show network
+...
+  Handover: On
+...
+OsmoBSC(config-net-bts)# show running-config
+...
+network
+... !handover
+ handover 1
+... !handover
+ bts 0
+... !handover
+ bts 1
+... !handover
+  handover power budget interval 23
+... !handover
+
+
+OsmoBSC(config-net-bts)# ### Checking online help
+OsmoBSC(config-net-bts)# exit
+OsmoBSC(config-net)# list
+...
+  handover (0|1|default)
+  handover window rxlev averaging (<1-10>|default)
+  handover window rxqual averaging (<1-10>|default)
+  handover window rxlev neighbor averaging (<1-10>|default)
+  handover power budget interval (<1-99>|default)
+  handover power budget hysteresis (<0-999>|default)
+  handover maximum distance (<0-9999>|default)
+...
+
+OsmoBSC(config-net)# handover?
+  handover  Handover options
+
+OsmoBSC(config-net)# handover ?
+  0        Disable in-call handover
+  1        Enable in-call handover
+  default  Enable/disable handover: Use default (0), remove explicit setting on this node
+  window   Measurement averaging settings
+  power    Neighbor cell power triggering
+  maximum  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+
+OsmoBSC(config-net)# handover window ?
+  rxlev   Received-Level averaging
+  rxqual  Received-Quality averaging
+
+OsmoBSC(config-net)# handover window rxlev ?
+  averaging  How many RxLev measurements are used for averaging
+  neighbor   How many Neighbor RxLev measurements are used for averaging
+
+OsmoBSC(config-net)# handover window rxlev averaging ?
+  <1-10>   RxLev averaging: Number of values to average over
+  default  Use default (10), remove explicit setting on this node
+
+OsmoBSC(config-net)# handover window rxlev neighbor ?
+  averaging  How many Neighbor RxLev measurements are used for averaging
+
+OsmoBSC(config-net)# handover window rxlev neighbor averaging ?
+  <1-10>   Neighbor RxLev averaging: Number of values to average over
+  default  Use default (10), remove explicit setting on this node
+
+OsmoBSC(config-net)# handover window rxqual ?
+  averaging  How many RxQual measurements are used for averaging
+
+OsmoBSC(config-net)# handover window rxqual averaging ?
+  <1-10>   RxQual averaging: Number of values to average over
+  default  Use default (1), remove explicit setting on this node
+
+OsmoBSC(config-net)# handover power ?
+  budget  Neighbor cell power triggering
+
+OsmoBSC(config-net)# handover power budget ?
+  interval    How often to check for a better cell (SACCH frames)
+  hysteresis  How many dBm stronger must a neighbor be to become a HO candidate
+
+OsmoBSC(config-net)# handover power budget interval ?
+  <1-99>   Check for stronger neighbor every N number of SACCH frames
+  default  Use default (6), remove explicit setting on this node
+
+OsmoBSC(config-net)# handover power budget hysteresis ?
+  <0-999>  Neighbor's strength difference in dBm
+  default  Use default (3), remove explicit setting on this node
+
+OsmoBSC(config-net)# handover maximum ?
+  distance  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+
+OsmoBSC(config-net)# handover maximum distance ?
+  <0-9999>  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+  default   Use default (9999), remove explicit setting on this node
+
+
+OsmoBSC(config-net)# ### Same on BTS level
+OsmoBSC(config-net)# bts 0
+OsmoBSC(config-net-bts)# handover?
+  handover  Handover options
+
+OsmoBSC(config-net-bts)# handover ?
+  0        Disable in-call handover
+  1        Enable in-call handover
+  default  Enable/disable handover: Use default (0), remove explicit setting on this node
+  window   Measurement averaging settings
+  power    Neighbor cell power triggering
+  maximum  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+
+OsmoBSC(config-net-bts)# handover window ?
+  rxlev   Received-Level averaging
+  rxqual  Received-Quality averaging
+
+OsmoBSC(config-net-bts)# handover window rxlev ?
+  averaging  How many RxLev measurements are used for averaging
+  neighbor   How many Neighbor RxLev measurements are used for averaging
+
+OsmoBSC(config-net-bts)# handover window rxlev averaging ?
+  <1-10>   RxLev averaging: Number of values to average over
+  default  Use default (10), remove explicit setting on this node
+
+OsmoBSC(config-net-bts)# handover window rxlev neighbor ?
+  averaging  How many Neighbor RxLev measurements are used for averaging
+
+OsmoBSC(config-net-bts)# handover window rxlev neighbor averaging ?
+  <1-10>   Neighbor RxLev averaging: Number of values to average over
+  default  Use default (10), remove explicit setting on this node
+
+OsmoBSC(config-net-bts)# handover window rxqual ?
+  averaging  How many RxQual measurements are used for averaging
+
+OsmoBSC(config-net-bts)# handover window rxqual averaging ?
+  <1-10>   RxQual averaging: Number of values to average over
+  default  Use default (1), remove explicit setting on this node
+
+OsmoBSC(config-net-bts)# handover power ?
+  budget  Neighbor cell power triggering
+
+OsmoBSC(config-net-bts)# handover power budget ?
+  interval    How often to check for a better cell (SACCH frames)
+  hysteresis  How many dBm stronger must a neighbor be to become a HO candidate
+
+OsmoBSC(config-net-bts)# handover power budget interval ?
+  <1-99>   Check for stronger neighbor every N number of SACCH frames
+  default  Use default (6), remove explicit setting on this node
+
+OsmoBSC(config-net-bts)# handover power budget hysteresis ?
+  <0-999>  Neighbor's strength difference in dBm
+  default  Use default (3), remove explicit setting on this node
+
+OsmoBSC(config-net-bts)# handover maximum ?
+  distance  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+
+OsmoBSC(config-net-bts)# handover maximum distance ?
+  <0-9999>  Maximum Timing-Advance value (i.e. MS distance) before triggering HO
+  default   Use default (9999), remove explicit setting on this node