Clarify (M)CS related VTY attributes

Some are used to control (M)CS values for downlink while some do it for
uplink. Let's make clear which one is used for what. Take the chance to
document the fields a bit better than they were.

Some more information about the origin of cs_downgrade_threshold can be
found in the commit introducing it: 70b96aa232bd9784a94247bf7b193cb2147ada9d.

Related: OS#4286
Change-Id: I4e890e924b094a1937fbd3794de96704cf0421a8

3 files changed, 17 insertions, 14 deletions

diff --git a/doc/manuals/vty/osmo-pcu_vty_reference.xml b/doc/manuals/vty/osmo-pcu_vty_reference.xml
index eed4d832..da6c76c9 100644
--- a/doc/manuals/vty/osmo-pcu_vty_reference.xml
+++ b/doc/manuals/vty/osmo-pcu_vty_reference.xml
@@ -1536,7 +1536,7 @@
     <command id='cs threshold &lt;0-100&gt; &lt;0-100&gt;'>
       <params>
         <param name='cs' doc='Coding Scheme configuration' />
-        <param name='threshold' doc='set thresholds for error rate based CS adjustment' />
+        <param name='threshold' doc='set thresholds for error rate based downlink (M)CS adjustment' />
         <param name='&lt;0-100&gt;' doc='lower limit in %' />
         <param name='&lt;0-100&gt;' doc='upper limit in %' />
       </params>
@@ -1545,13 +1545,13 @@
       <params>
         <param name='no' doc='Negate a command or set its defaults' />
         <param name='cs' doc='Coding Scheme configuration' />
-        <param name='threshold' doc='set thresholds for error rate based CS adjustment' />
+        <param name='threshold' doc='set thresholds for error rate based downlink (M)CS adjustment' />
       </params>
     </command>
     <command id='cs downgrade-threshold &lt;1-10000&gt;'>
       <params>
         <param name='cs' doc='Coding Scheme configuration' />
-        <param name='downgrade-threshold' doc='set threshold for data size based CS downgrade' />
+        <param name='downgrade-threshold' doc='set threshold for data size based downlink (M)CS downgrade' />
         <param name='&lt;1-10000&gt;' doc='downgrade if less octets left' />
       </params>
     </command>
@@ -1559,13 +1559,13 @@
       <params>
         <param name='no' doc='Negate a command or set its defaults' />
         <param name='cs' doc='Coding Scheme configuration' />
-        <param name='downgrade-threshold' doc='set threshold for data size based CS downgrade' />
+        <param name='downgrade-threshold' doc='set threshold for data size based downlink (M)CS downgrade' />
       </params>
     </command>
     <command id='cs link-quality-ranges cs1 &lt;0-35&gt; cs2 &lt;0-35&gt; &lt;0-35&gt; cs3 &lt;0-35&gt; &lt;0-35&gt; cs4 &lt;0-35&gt;'>
       <params>
         <param name='cs' doc='Coding Scheme configuration' />
-        <param name='link-quality-ranges' doc='Set link quality ranges' />
+        <param name='link-quality-ranges' doc='Set link quality ranges for each uplink CS' />
         <param name='cs1' doc='Set quality range for CS-1 (high value only)' />
         <param name='&lt;0-35&gt;' doc='CS-1 high (dB)' />
         <param name='cs2' doc='Set quality range for CS-2' />
@@ -1581,7 +1581,7 @@
     <command id='mcs link-quality-ranges mcs1 &lt;0-35&gt; mcs2 &lt;0-35&gt; &lt;0-35&gt; mcs3 &lt;0-35&gt; &lt;0-35&gt; mcs4 &lt;0-35&gt; &lt;0-35&gt; mcs5 &lt;0-35&gt; &lt;0-35&gt; mcs6 &lt;0-35&gt; &lt;0-35&gt; mcs7 &lt;0-35&gt; &lt;0-35&gt; mcs8 &lt;0-35&gt; &lt;0-35&gt; mcs9 &lt;0-35&gt;'>
       <params>
         <param name='mcs' doc='Coding Scheme configuration' />
-        <param name='link-quality-ranges' doc='Set link quality ranges' />
+        <param name='link-quality-ranges' doc='Set link quality ranges for each uplink MCS' />
         <param name='mcs1' doc='Set quality range for MCS-1 (high value only)' />
         <param name='&lt;0-35&gt;' doc='MCS-1 high (dB)' />
         <param name='mcs2' doc='Set quality range for MCS-2' />
diff --git a/src/bts.h b/src/bts.h
index 54a29cb7..7ef5a3f5 100644
--- a/src/bts.h
+++ b/src/bts.h
@@ -142,12 +142,15 @@ struct gprs_rlcmac_bts {
 	/* 0 to support resegmentation in DL, 1 for no reseg */
 	uint8_t dl_arq_type;
 
-	uint8_t cs_adj_enabled;
-	uint8_t cs_adj_upper_limit;
-	uint8_t cs_adj_lower_limit;
+	uint8_t cs_adj_enabled; /* whether cs_adj_{upper,lower}_limit are used to adjust DL CS */
+	uint8_t cs_adj_upper_limit; /* downgrade DL CS if error rate above its value */
+	uint8_t cs_adj_lower_limit; /* upgrade DL CS if error rate below its value */
+	/* downgrade DL CS when less than specified octets are left in tx queue. Optimization, see paper:
+	  "Theoretical Analysis of GPRS Throughput and Delay" */
+	uint16_t cs_downgrade_threshold;
+	/* Link quality range for each UL (M)CS. Below or above, next/prev (M)CS is selected. */
 	struct {int16_t low; int16_t high; } cs_lqual_ranges[MAX_GPRS_CS];
 	struct {int16_t low; int16_t high; } mcs_lqual_ranges[MAX_EDGE_MCS];
-	uint16_t cs_downgrade_threshold; /* downgrade if less packets left (DL) */
 	uint16_t ws_base;
 	uint16_t ws_pdch; /* increase WS by this value per PDCH */
 
diff --git a/src/pcu_vty.c b/src/pcu_vty.c
index 996ce61c..2fd57d09 100644
--- a/src/pcu_vty.c
+++ b/src/pcu_vty.c
@@ -938,7 +938,7 @@ DEFUN_DEPRECATED(cfg_pcu_no_ms_idle_time,
 	return CMD_SUCCESS;
 }
 
-#define CS_ERR_LIMITS_STR "set thresholds for error rate based CS adjustment\n"
+#define CS_ERR_LIMITS_STR "set thresholds for error rate based downlink (M)CS adjustment\n"
 DEFUN(cfg_pcu_cs_err_limits,
       cfg_pcu_cs_err_limits_cmd,
       "cs threshold <0-100> <0-100>",
@@ -977,7 +977,7 @@ DEFUN(cfg_pcu_no_cs_err_limits,
 	return CMD_SUCCESS;
 }
 
-#define CS_DOWNGRADE_STR "set threshold for data size based CS downgrade\n"
+#define CS_DOWNGRADE_STR "set threshold for data size based downlink (M)CS downgrade\n"
 DEFUN(cfg_pcu_cs_downgrade_thrsh,
       cfg_pcu_cs_downgrade_thrsh_cmd,
       "cs downgrade-threshold <1-10000>",
@@ -1006,7 +1006,7 @@ DEFUN(cfg_pcu_no_cs_downgrade_thrsh,
 DEFUN(cfg_pcu_cs_lqual_ranges,
       cfg_pcu_cs_lqual_ranges_cmd,
       "cs link-quality-ranges cs1 <0-35> cs2 <0-35> <0-35> cs3 <0-35> <0-35> cs4 <0-35>",
-      CS_STR "Set link quality ranges\n"
+      CS_STR "Set link quality ranges for each uplink CS\n"
       "Set quality range for CS-1 (high value only)\n"
       "CS-1 high (dB)\n"
       "Set quality range for CS-2\n"
@@ -1040,7 +1040,7 @@ DEFUN(cfg_pcu_cs_lqual_ranges,
 DEFUN(cfg_pcu_mcs_lqual_ranges,
       cfg_pcu_mcs_lqual_ranges_cmd,
       "mcs link-quality-ranges mcs1 <0-35> mcs2 <0-35> <0-35> mcs3 <0-35> <0-35> mcs4 <0-35> <0-35> mcs5 <0-35> <0-35> mcs6 <0-35> <0-35> mcs7 <0-35> <0-35> mcs8 <0-35> <0-35> mcs9 <0-35>",
-      CS_STR "Set link quality ranges\n"
+      CS_STR "Set link quality ranges for each uplink MCS\n"
       "Set quality range for MCS-1 (high value only)\n"
       "MCS-1 high (dB)\n"
       "Set quality range for MCS-2\n"