iwl4965: add comments to rate scaling code

Add comments to rate scaling code.

Signed-off-by: Ben Cahill <ben.m.cahill@intel.com>
Signed-off-by: Zhu Yi <yi.zhu@intel.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>

1 files changed, 29 insertions, 16 deletions

diff --git a/drivers/net/wireless/iwlwifi/iwl-4965-rs.h b/drivers/net/wireless/iwlwifi/iwl-4965-rs.h
index 4259099eae71..86f62d809058 100644
--- a/drivers/net/wireless/iwlwifi/iwl-4965-rs.h
+++ b/drivers/net/wireless/iwlwifi/iwl-4965-rs.h
@@ -30,10 +30,10 @@
 #include "iwl-4965.h"
 
 struct iwl4965_rate_info {
-        u8 plcp;
-        u8 plcp_siso;
-        u8 plcp_mimo;
-        u8 ieee;
+        u8 plcp;        /* uCode API:  IWL_RATE_6M_PLCP, etc. */
+        u8 plcp_siso;   /* uCode API:  IWL_RATE_SISO_6M_PLCP, etc. */
+        u8 plcp_mimo;   /* uCode API:  IWL_RATE_MIMO_6M_PLCP, etc. */
+        u8 ieee;        /* MAC header:  IWL_RATE_6M_IEEE, etc. */
         u8 prev_ieee;    /* previous rate in IEEE speeds */
         u8 next_ieee;    /* next rate in IEEE speeds */
         u8 prev_rs;      /* previous rate used in rs algo */
@@ -42,6 +42,7 @@ struct iwl4965_rate_info {
         u8 next_rs_tgg;  /* next rate used in TGG rs algo */
 };
 
+/* For driver (not uCode API) */
 enum {
         IWL_RATE_1M_INDEX = 0,
         IWL_RATE_2M_INDEX,
@@ -83,6 +84,7 @@ enum {
 #define IWL_RATE_5M_MASK   (1<<IWL_RATE_5M_INDEX)
 #define IWL_RATE_11M_MASK  (1<<IWL_RATE_11M_INDEX)
 
+/* 4965 uCode API values for legacy bit rates, both OFDM and CCK */
 enum {
         IWL_RATE_6M_PLCP  = 13,
         IWL_RATE_9M_PLCP  = 15,
@@ -99,7 +101,7 @@ enum {
         IWL_RATE_11M_PLCP = 110,
 };
 
-/* OFDM HT rate plcp */
+/* 4965 uCode API values for OFDM high-throughput (HT) bit rates */
 enum {
         IWL_RATE_SISO_6M_PLCP = 0,
         IWL_RATE_SISO_12M_PLCP = 1,
@@ -121,6 +123,7 @@ enum {
         IWL_RATE_MIMO_INVM_PLCP = IWL_RATE_SISO_INVM_PLCP,
 };
 
+/* MAC header values for bit rates */
 enum {
         IWL_RATE_6M_IEEE  = 12,
         IWL_RATE_9M_IEEE  = 18,
@@ -170,13 +173,8 @@ enum {
 #define IWL_MIN_RSSI_VAL                 -100
 #define IWL_MAX_RSSI_VAL                    0
 
-#define IWL_LEGACY_SWITCH_ANTENNA       0
-#define IWL_LEGACY_SWITCH_SISO          1
-#define IWL_LEGACY_SWITCH_MIMO          2
-
-#define IWL_RS_GOOD_RATIO               12800
-
-#define IWL_ACTION_LIMIT                3
+/* These values specify how many Tx frame attempts before
+ * searching for a new modulation mode */
 #define IWL_LEGACY_FAILURE_LIMIT        160
 #define IWL_LEGACY_SUCCESS_LIMIT        480
 #define IWL_LEGACY_TABLE_COUNT          160
@@ -185,29 +183,44 @@ enum {
 #define IWL_NONE_LEGACY_SUCCESS_LIMIT   4500
 #define IWL_NONE_LEGACY_TABLE_COUNT     1500
 
-#define IWL_RATE_SCALE_SWITCH           (10880)
+/* Success ratio (ACKed / attempted tx frames) values (perfect is 128 * 100) */
+#define IWL_RS_GOOD_RATIO               12800   /* 100% */
+#define IWL_RATE_SCALE_SWITCH           10880   /*  85% */
+#define IWL_RATE_HIGH_TH                10880   /*  85% */
+#define IWL_RATE_INCREASE_TH            8960    /*  70% */
+#define IWL_RATE_DECREASE_TH            1920    /*  15% */
 
+/* possible actions when in legacy mode */
+#define IWL_LEGACY_SWITCH_ANTENNA       0
+#define IWL_LEGACY_SWITCH_SISO          1
+#define IWL_LEGACY_SWITCH_MIMO          2
+
+/* possible actions when in siso mode */
 #define IWL_SISO_SWITCH_ANTENNA         0
 #define IWL_SISO_SWITCH_MIMO            1
 #define IWL_SISO_SWITCH_GI              2
 
+/* possible actions when in mimo mode */
 #define IWL_MIMO_SWITCH_ANTENNA_A       0
 #define IWL_MIMO_SWITCH_ANTENNA_B       1
 #define IWL_MIMO_SWITCH_GI              2
 
-#define LQ_SIZE         2
+#define IWL_ACTION_LIMIT                3       /* # possible actions */
+
+#define LQ_SIZE         2       /* 2 mode tables:  "Active" and "Search" */
 
 extern const struct iwl4965_rate_info iwl4965_rates[IWL_RATE_COUNT];
 
 enum iwl4965_table_type {
         LQ_NONE,
-        LQ_G,
+        LQ_G,           /* legacy types */
         LQ_A,
-        LQ_SISO,
+        LQ_SISO,        /* high-throughput types */
         LQ_MIMO,
         LQ_MAX,
 };
 
+/* 4965 has 2 antennas/chains for Tx (but 3 for Rx) */
 enum iwl4965_antenna_type {
         ANT_NONE,
         ANT_MAIN,