From 08371ecc01a996f552ecfd4be9b3b738a9809e05 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Mon, 24 Jun 2019 13:43:06 +0200 Subject: doc/manuals, vty doc: more handover doc clarifications Related: OS#3487 Change-Id: I1639efb2dbcca4f0e9c33a74f3067606ce5f4209 --- doc/manuals/chapters/handover.adoc | 10 ++++--- include/osmocom/bsc/handover_cfg.h | 31 +++++++++++--------- src/osmo-bsc/handover_vty.c | 3 +- tests/handover_cfg.vty | 60 +++++++++++++++++++------------------- 4 files changed, 55 insertions(+), 49 deletions(-) diff --git a/doc/manuals/chapters/handover.adoc b/doc/manuals/chapters/handover.adoc index 2f9d598c6..bb99751d3 100644 --- a/doc/manuals/chapters/handover.adoc +++ b/doc/manuals/chapters/handover.adoc @@ -434,7 +434,8 @@ with the next Measurement Report received. Configuration settings relevant for algorithm 1 start with `handover1`. For further details, please refer to the OsmoBSC VTY Reference -(<>) or the telnet VTY online documentation. +(<>) or the telnet VTY online documentation. See the +`handover1` settings on the `config-net` and `config-net-bts` nodes. ==== Handover Algorithm 2 @@ -451,7 +452,8 @@ configurable (see `handover2 penalty-time` configuration items). Configuration settings relevant for algorithm 2 start with `handover2`. For further details, please refer to the OsmoBSC VTY Reference -<> or the telnet VTY online documentation. +<> or the telnet VTY online documentation. See the `handover2` +settings on the `config-net` and `config-net-bts` nodes. ===== Load Distribution @@ -472,8 +474,8 @@ In either case, load distribution will only occur towards neighbor cells that adhere to minimum reception levels and distance, see `min rxlev` and `max distance`. -Load distribution will take effect only for already established voice channels. -An MS will always first establish a voice call with its current cell choice; in +Load distribution will take effect only for already established channels. +For example, an MS will always first establish a voice call with its current cell choice; in load situations, it might be moved to another cell shortly after that. Considering the best neighbor _before_ starting a new voice call might be desirable, but is currently not implemented. Consider that RXLEV/RXQUAL ratings diff --git a/include/osmocom/bsc/handover_cfg.h b/include/osmocom/bsc/handover_cfg.h index 92b5cd44c..f174aad77 100644 --- a/include/osmocom/bsc/handover_cfg.h +++ b/include/osmocom/bsc/handover_cfg.h @@ -96,22 +96,22 @@ static inline const char *tdma2a(bool val) "handover1 ", "window rxlev averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER1 \ HO_CFG_STR_WIN_RXLEV \ - "How many RxLev measurements are used for averaging\n" \ + "How many RxLev measurements to use for averaging\n" \ "RxLev averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec1_rxqual_avg_win, 1, \ "handover1 ", "window rxqual averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER1 \ HO_CFG_STR_WIN_RXQUAL \ - "How many RxQual measurements are used for averaging\n" \ + "How many RxQual measurements to use for averaging\n" \ "RxQual averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec1_rxlev_neigh_avg_win, 10, \ "handover1 ", "window rxlev neighbor averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER1 \ HO_CFG_STR_WIN_RXLEV \ - "How many Neighbor RxLev measurements are used for averaging\n" \ - "How many Neighbor RxLev measurements are used for averaging\n" \ + "How many Neighbor RxLev measurements to use for averaging\n" \ + "How many Neighbor RxLev measurements to use for averaging\n" \ "Neighbor RxLev averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec1_pwr_interval, 6, \ @@ -142,22 +142,22 @@ static inline const char *tdma2a(bool val) "handover2 ", "window rxlev averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_WIN_RXLEV \ - "How many RxLev measurements are used for averaging\n" \ + "How many RxLev measurements to use for averaging\n" \ "RxLev averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec2_rxqual_avg_win, 1, \ "handover2 ", "window rxqual averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_WIN_RXQUAL \ - "How many RxQual measurements are used for averaging\n" \ + "How many RxQual measurements to use for averaging\n" \ "RxQual averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec2_rxlev_neigh_avg_win, 10, \ "handover2 ", "window rxlev neighbor averaging", "<1-10>", atoi, "%u", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_WIN_RXLEV \ - "How many Neighbor RxLev measurements are used for averaging\n" \ - "How many Neighbor RxLev measurements are used for averaging\n" \ + "How many Neighbor RxLev measurements to use for averaging\n" \ + "How many Neighbor RxLev measurements to use for averaging\n" \ "Neighbor RxLev averaging: " HO_CFG_STR_AVG_COUNT) \ \ HO_CFG_ONE_MEMBER(unsigned int, hodec2_pwr_interval, 6, \ @@ -184,7 +184,7 @@ static inline const char *tdma2a(bool val) HO_CFG_ONE_MEMBER(bool, hodec2_as_active, 0, \ "handover2 ", "assignment", "0|1", a2bool, "%d", bool2i, \ HO_CFG_STR_HANDOVER2 \ - "Enable or disable in-call channel re-assignment\n" \ + "Enable or disable in-call channel re-assignment within the same cell\n" \ "Disable in-call assignment\n" \ "Enable in-call assignment\n") \ \ @@ -200,7 +200,7 @@ static inline const char *tdma2a(bool val) HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_MIN \ "How weak may RxLev of an MS become before triggering HO\n" \ - "minimum RxLev (dBm)\n") \ + "minimum RxLev (dBm; note: negative values)\n") \ \ HO_CFG_ONE_MEMBER(int, hodec2_min_rxqual, 5, \ "handover2 ", "min rxqual", "<0-7>", atoi, "%d", as_is, \ @@ -247,27 +247,30 @@ static inline const char *tdma2a(bool val) "handover2 ", "penalty-time max-distance", "<0-99999>", atoi, "%d", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_PENALTY_TIME \ - "Time to suspend handovers after leaving this cell due to exceeding max distance\n" \ + "Time to suspend handover for a subscriber after leaving this cell due to exceeding max distance;" \ + " see also 'handover2 retries'\n" \ "Seconds\n") \ \ HO_CFG_ONE_MEMBER(int, hodec2_penalty_failed_ho, 60, \ "handover2 ", "penalty-time failed-ho", "<0-99999>", atoi, "%d", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_PENALTY_TIME \ - "Time to suspend handovers after handover failure to this cell\n" \ + "Time to suspend handover for a subscriber after a failed handover into this cell;" \ + " see also 'handover2 retries'\n" \ "Seconds\n") \ \ HO_CFG_ONE_MEMBER(int, hodec2_penalty_failed_as, 60, \ "handover2 ", "penalty-time failed-assignment", "<0-99999>", atoi, "%d", as_is, \ HO_CFG_STR_HANDOVER2 \ HO_CFG_STR_PENALTY_TIME \ - "Time to suspend handovers after assignment failure in this cell\n" \ + "Time to suspend handover for a subscriber after a failed re-assignment within this cell;" \ + " see also 'handover2 retries'\n" \ "Seconds\n") \ \ HO_CFG_ONE_MEMBER(int, hodec2_retries, 0, \ "handover2 ", "retries", "<0-9>", atoi, "%d", as_is, \ HO_CFG_STR_HANDOVER2 \ - "Immediately retry on handover/assignment failure\n" \ + "Number of times to immediately retry a failed handover/assignment, before a penalty time is applied\n" \ "Number of retries\n") \ #define HO_CFG_ALL_MEMBERS \ diff --git a/src/osmo-bsc/handover_vty.c b/src/osmo-bsc/handover_vty.c index 79795115e..e9333ec85 100644 --- a/src/osmo-bsc/handover_vty.c +++ b/src/osmo-bsc/handover_vty.c @@ -107,7 +107,8 @@ DEFUN(cfg_net_ho_congestion_check_interval, cfg_net_ho_congestion_check_interval "handover2 congestion-check (disabled|<1-999>|now)", HO_CFG_STR_HANDOVER2 "Configure congestion check interval\n" - "Disable congestion checking, do not handover based on cell overload\n" + "Disable congestion checking, do not handover based on cell load. Note: there is one global congestion check" + " interval, i.e. contrary to other handover2 settings, this is not configurable per individual cell.\n" "Congestion check interval in seconds (default " OSMO_STRINGIFY_VAL(HO_CFG_CONGESTION_CHECK_DEFAULT) ")\n" "Manually trigger a congestion check to run right now\n") diff --git a/tests/handover_cfg.vty b/tests/handover_cfg.vty index 94c20d962..8fdaf1f08 100644 --- a/tests/handover_cfg.vty +++ b/tests/handover_cfg.vty @@ -145,7 +145,7 @@ network OsmoBSC(config-net-bts)# ### Verify that 'min rxlev' value range stops at -50 OsmoBSC(config-net-bts)# handover2 min rxlev ? - <-110--50> minimum RxLev (dBm) + <-110--50> minimum RxLev (dBm; note: negative values) default Use default (-100), remove explicit setting on this node OsmoBSC(config-net-bts)# handover2 min rxlev -111 % Unknown command. @@ -218,14 +218,14 @@ OsmoBSC(config-net)# handover2 ? window Measurement averaging settings power Neighbor cell power triggering maximum Maximum Timing-Advance value (i.e. MS distance) before triggering HO - assignment Enable or disable in-call channel re-assignment + assignment Enable or disable in-call channel re-assignment within the same cell tdma-measurement Define measurement set of TDMA frames min Minimum Level/Quality thresholds before triggering HO afs-bias Configure bias to prefer AFS (AMR on TCH/F) over other codecs min-free-slots Minimum free TCH timeslots before cell is considered congested max-handovers Maximum number of concurrent handovers allowed per cell penalty-time Set penalty times to wait between repeated handovers - retries Immediately retry on handover/assignment failure + retries Number of times to immediately retry a failed handover/assignment, before a penalty time is applied congestion-check Configure congestion check interval OsmoBSC(config-net)# handover algorithm ? @@ -238,22 +238,22 @@ OsmoBSC(config-net)# handover1 window ? rxqual Received-Quality averaging OsmoBSC(config-net)# handover1 window rxlev ? - averaging How many RxLev measurements are used for averaging - neighbor How many Neighbor RxLev measurements are used for averaging + averaging How many RxLev measurements to use for averaging + neighbor How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net)# handover1 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)# handover1 window rxlev neighbor ? - averaging How many Neighbor RxLev measurements are used for averaging + averaging How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net)# handover1 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)# handover1 window rxqual ? - averaging How many RxQual measurements are used for averaging + averaging How many RxQual measurements to use for averaging OsmoBSC(config-net)# handover1 window rxqual averaging ? <1-10> RxQual averaging: Number of values to average over @@ -286,22 +286,22 @@ OsmoBSC(config-net)# handover2 window ? rxqual Received-Quality averaging OsmoBSC(config-net)# handover2 window rxlev ? - averaging How many RxLev measurements are used for averaging - neighbor How many Neighbor RxLev measurements are used for averaging + averaging How many RxLev measurements to use for averaging + neighbor How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net)# handover2 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)# handover2 window rxlev neighbor ? - averaging How many Neighbor RxLev measurements are used for averaging + averaging How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net)# handover2 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)# handover2 window rxqual ? - averaging How many RxQual measurements are used for averaging + averaging How many RxQual measurements to use for averaging OsmoBSC(config-net)# handover2 window rxqual averaging ? <1-10> RxQual averaging: Number of values to average over @@ -344,7 +344,7 @@ OsmoBSC(config-net)# handover2 min ? rxqual How bad may RxQual of an MS become before triggering HO OsmoBSC(config-net)# handover2 min rxlev ? - <-110--50> minimum RxLev (dBm) + <-110--50> minimum RxLev (dBm; note: negative values) default Use default (-100), remove explicit setting on this node OsmoBSC(config-net)# handover2 min rxqual ? @@ -383,9 +383,9 @@ OsmoBSC(config-net)# handover2 max-handovers ? default Use default (9999), remove explicit setting on this node OsmoBSC(config-net)# handover2 penalty-time ? - max-distance Time to suspend handovers after leaving this cell due to exceeding max distance - failed-ho Time to suspend handovers after handover failure to this cell - failed-assignment Time to suspend handovers after assignment failure in this cell + max-distance Time to suspend handover for a subscriber after leaving this cell due to exceeding max distance; see also 'handover2 retries' + failed-ho Time to suspend handover for a subscriber after a failed handover into this cell; see also 'handover2 retries' + failed-assignment Time to suspend handover for a subscriber after a failed re-assignment within this cell; see also 'handover2 retries' OsmoBSC(config-net)# handover2 penalty-time max-distance ? <0-99999> Seconds @@ -404,7 +404,7 @@ OsmoBSC(config-net)# handover2 retries ? default Use default (0), remove explicit setting on this node OsmoBSC(config-net)# handover2 congestion-check ? - disabled Disable congestion checking, do not handover based on cell overload + disabled Disable congestion checking, do not handover based on cell load. Note: there is one global congestion check interval, i.e. contrary to other handover2 settings, this is not configurable per individual cell. <1-999> Congestion check interval in seconds (default 10) now Manually trigger a congestion check to run right now @@ -437,14 +437,14 @@ OsmoBSC(config-net-bts)# handover2 ? window Measurement averaging settings power Neighbor cell power triggering maximum Maximum Timing-Advance value (i.e. MS distance) before triggering HO - assignment Enable or disable in-call channel re-assignment + assignment Enable or disable in-call channel re-assignment within the same cell tdma-measurement Define measurement set of TDMA frames min Minimum Level/Quality thresholds before triggering HO afs-bias Configure bias to prefer AFS (AMR on TCH/F) over other codecs min-free-slots Minimum free TCH timeslots before cell is considered congested max-handovers Maximum number of concurrent handovers allowed per cell penalty-time Set penalty times to wait between repeated handovers - retries Immediately retry on handover/assignment failure + retries Number of times to immediately retry a failed handover/assignment, before a penalty time is applied OsmoBSC(config-net-bts)# handover algorithm ? 1 Algorithm 1: trigger handover based on comparing current cell and neighbor RxLev and RxQual, only. @@ -456,22 +456,22 @@ OsmoBSC(config-net-bts)# handover1 window ? rxqual Received-Quality averaging OsmoBSC(config-net-bts)# handover1 window rxlev ? - averaging How many RxLev measurements are used for averaging - neighbor How many Neighbor RxLev measurements are used for averaging + averaging How many RxLev measurements to use for averaging + neighbor How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net-bts)# handover1 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)# handover1 window rxlev neighbor ? - averaging How many Neighbor RxLev measurements are used for averaging + averaging How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net-bts)# handover1 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)# handover1 window rxqual ? - averaging How many RxQual measurements are used for averaging + averaging How many RxQual measurements to use for averaging OsmoBSC(config-net-bts)# handover1 window rxqual averaging ? <1-10> RxQual averaging: Number of values to average over @@ -504,22 +504,22 @@ OsmoBSC(config-net-bts)# handover2 window ? rxqual Received-Quality averaging OsmoBSC(config-net-bts)# handover2 window rxlev ? - averaging How many RxLev measurements are used for averaging - neighbor How many Neighbor RxLev measurements are used for averaging + averaging How many RxLev measurements to use for averaging + neighbor How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net-bts)# handover2 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)# handover2 window rxlev neighbor ? - averaging How many Neighbor RxLev measurements are used for averaging + averaging How many Neighbor RxLev measurements to use for averaging OsmoBSC(config-net-bts)# handover2 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)# handover2 window rxqual ? - averaging How many RxQual measurements are used for averaging + averaging How many RxQual measurements to use for averaging OsmoBSC(config-net-bts)# handover2 window rxqual averaging ? <1-10> RxQual averaging: Number of values to average over @@ -562,7 +562,7 @@ OsmoBSC(config-net-bts)# handover2 min ? rxqual How bad may RxQual of an MS become before triggering HO OsmoBSC(config-net-bts)# handover2 min rxlev ? - <-110--50> minimum RxLev (dBm) + <-110--50> minimum RxLev (dBm; note: negative values) default Use default (-100), remove explicit setting on this node OsmoBSC(config-net-bts)# handover2 min rxqual ? @@ -601,9 +601,9 @@ OsmoBSC(config-net-bts)# handover2 max-handovers ? default Use default (9999), remove explicit setting on this node OsmoBSC(config-net-bts)# handover2 penalty-time ? - max-distance Time to suspend handovers after leaving this cell due to exceeding max distance - failed-ho Time to suspend handovers after handover failure to this cell - failed-assignment Time to suspend handovers after assignment failure in this cell + max-distance Time to suspend handover for a subscriber after leaving this cell due to exceeding max distance; see also 'handover2 retries' + failed-ho Time to suspend handover for a subscriber after a failed handover into this cell; see also 'handover2 retries' + failed-assignment Time to suspend handover for a subscriber after a failed re-assignment within this cell; see also 'handover2 retries' OsmoBSC(config-net-bts)# handover2 penalty-time max-distance ? <0-99999> Seconds -- cgit v1.2.3