iwl4965: add comments to rate scaling code
authorBen Cahill <ben.m.cahill@intel.com>
Thu, 29 Nov 2007 03:09:44 +0000 (11:09 +0800)
committerDavid S. Miller <davem@davemloft.net>
Mon, 28 Jan 2008 23:05:15 +0000 (15:05 -0800)
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>
drivers/net/wireless/iwlwifi/iwl-4965-rs.c
drivers/net/wireless/iwlwifi/iwl-4965-rs.h
drivers/net/wireless/iwlwifi/iwl-4965.h
drivers/net/wireless/iwlwifi/iwl4965-base.c

index 8d3d9f72a8ce254b64308beb786ed8d39c92a523..218c5a355ddbfa9b8a8745320be6c71254f98655 100644 (file)
 #define IWL_NUMBER_TRY      1
 #define IWL_HT_NUMBER_TRY   3
 
-#define IWL_RATE_MAX_WINDOW            62
-#define IWL_RATE_HIGH_TH               10880
-#define IWL_RATE_MIN_FAILURE_TH                6
-#define IWL_RATE_MIN_SUCCESS_TH                8
-#define IWL_RATE_DECREASE_TH           1920
-#define IWL_RATE_INCREASE_TH            8960
-#define IWL_RATE_SCALE_FLUSH_INTVL   (2*HZ)        /*2 seconds */
+#define IWL_RATE_MAX_WINDOW            62      /* # tx in history window */
+#define IWL_RATE_MIN_FAILURE_TH                6       /* min failures to calc tpt */
+#define IWL_RATE_MIN_SUCCESS_TH                8       /* min successes to calc tpt */
+
+/* max time to accum history 2 seconds */
+#define IWL_RATE_SCALE_FLUSH_INTVL   (2*HZ)
 
 static u8 rs_ht_to_legacy[] = {
        IWL_RATE_6M_INDEX, IWL_RATE_6M_INDEX,
@@ -69,54 +68,74 @@ struct iwl4965_rate {
        u32 rate_n_flags;
 } __attribute__ ((packed));
 
+/**
+ * struct iwl4965_rate_scale_data -- tx success history for one rate
+ */
 struct iwl4965_rate_scale_data {
-       u64 data;
-       s32 success_counter;
-       s32 success_ratio;
-       s32 counter;
-       s32 average_tpt;
+       u64 data;               /* bitmap of successful frames */
+       s32 success_counter;    /* number of frames successful */
+       s32 success_ratio;      /* per-cent * 128  */
+       s32 counter;            /* number of frames attempted */
+       s32 average_tpt;        /* success ratio * expected throughput */
        unsigned long stamp;
 };
 
+/**
+ * struct iwl4965_scale_tbl_info -- tx params and success history for all rates
+ *
+ * There are two of these in struct iwl_rate_scale_priv,
+ * one for "active", and one for "search".
+ */
 struct iwl4965_scale_tbl_info {
        enum iwl4965_table_type lq_type;
        enum iwl4965_antenna_type antenna_type;
-       u8 is_SGI;
-       u8 is_fat;
-       u8 is_dup;
-       u8 action;
-       s32 *expected_tpt;
-       struct iwl4965_rate current_rate;
-       struct iwl4965_rate_scale_data win[IWL_RATE_COUNT];
+       u8 is_SGI;      /* 1 = short guard interval */
+       u8 is_fat;      /* 1 = 40 MHz channel width */
+       u8 is_dup;      /* 1 = duplicated data streams */
+       u8 action;      /* change modulation; IWL_[LEGACY/SISO/MIMO]_SWITCH_* */
+       s32 *expected_tpt;      /* throughput metrics; expected_tpt_G, etc. */
+       struct iwl4965_rate current_rate;  /* rate_n_flags, uCode API format */
+       struct iwl4965_rate_scale_data win[IWL_RATE_COUNT]; /* rate histories */
 };
 
+/**
+ * struct iwl_rate_scale_priv -- driver's rate scaling private structure
+ *
+ * Pointer to this gets passed back and forth between driver and mac80211.
+ */
 struct iwl4965_rate_scale_priv {
-       u8 active_tbl;
-       u8 enable_counter;
-       u8 stay_in_tbl;
-       u8 search_better_tbl;
+       u8 active_tbl;          /* index of active table, range 0-1 */
+       u8 enable_counter;      /* indicates HT mode */
+       u8 stay_in_tbl;         /* 1: disallow, 0: allow search for new mode */
+       u8 search_better_tbl;   /* 1: currently trying alternate mode */
        s32 last_tpt;
+
+       /* The following determine when to search for a new mode */
        u32 table_count_limit;
-       u32 max_failure_limit;
-       u32 max_success_limit;
+       u32 max_failure_limit;  /* # failed frames before new search */
+       u32 max_success_limit;  /* # successful frames before new search */
        u32 table_count;
-       u32 total_failed;
-       u32 total_success;
-       u32 flush_timer;
-       u8 action_counter;
+       u32 total_failed;       /* total failed frames, any/all rates */
+       u32 total_success;      /* total successful frames, any/all rates */
+       u32 flush_timer;        /* time staying in mode before new search */
+
+       u8 action_counter;      /* # mode-switch actions tried */
        u8 antenna;
        u8 valid_antenna;
        u8 is_green;
        u8 is_dup;
        u8 phymode;
        u8 ibss_sta_added;
+
+       /* The following are bitmaps of rates; IWL_RATE_6M_MASK, etc. */
        u32 supp_rates;
        u16 active_rate;
        u16 active_siso_rate;
        u16 active_mimo_rate;
        u16 active_rate_basic;
+
        struct iwl4965_link_quality_cmd lq;
-       struct iwl4965_scale_tbl_info lq_info[LQ_SIZE];
+       struct iwl4965_scale_tbl_info lq_info[LQ_SIZE]; /* "active", "search" */
 #ifdef CONFIG_MAC80211_DEBUGFS
        struct dentry *rs_sta_dbgfs_scale_table_file;
        struct dentry *rs_sta_dbgfs_stats_table_file;
@@ -142,6 +161,12 @@ static void rs_dbgfs_set_mcs(struct iwl4965_rate_scale_priv *rs_priv,
                                struct iwl4965_rate *mcs, int index)
 {}
 #endif
+
+/*
+ * Expected throughput metrics for following rates:
+ * 1, 2, 5.5, 11, 6, 9, 12, 18, 24, 36, 48, 54, 60 MBits
+ * "G" is the only table that supports CCK (the first 4 rates).
+ */
 static s32 expected_tpt_A[IWL_RATE_COUNT] = {
        0, 0, 0, 0, 40, 57, 72, 98, 121, 154, 177, 186, 186
 };
@@ -244,6 +269,13 @@ static void rs_rate_scale_clear_window(struct iwl4965_rate_scale_data *window)
        window->stamp = 0;
 }
 
+/**
+ * rs_collect_tx_data - Update the success/failure sliding window
+ *
+ * We keep a sliding window of the last 62 packets transmitted
+ * at this rate.  window->data contains the bitmask of successful
+ * packets.
+ */
 static int rs_collect_tx_data(struct iwl4965_rate_scale_data *windows,
                              int scale_index, s32 tpt, u32 status)
 {
@@ -255,10 +287,18 @@ static int rs_collect_tx_data(struct iwl4965_rate_scale_data *windows,
        if (scale_index < 0 || scale_index >= IWL_RATE_COUNT)
                return -EINVAL;
 
+       /* Select data for current tx bit rate */
        window = &(windows[scale_index]);
 
+       /*
+        * Keep track of only the latest 62 tx frame attempts in this rate's
+        * history window; anything older isn't really relevant any more.
+        * If we have filled up the sliding window, drop the oldest attempt;
+        * if the oldest attempt (highest bit in bitmap) shows "success",
+        * subtract "1" from the success counter (this is the main reason
+        * we keep these bitmaps!).
+        */
        if (window->counter >= win_size) {
-
                window->counter = win_size - 1;
                mask = 1;
                mask = (mask << (win_size - 1));
@@ -268,7 +308,11 @@ static int rs_collect_tx_data(struct iwl4965_rate_scale_data *windows,
                }
        }
 
+       /* Increment frames-attempted counter */
        window->counter = window->counter + 1;
+
+       /* Shift bitmap by one frame (throw away oldest history),
+        * OR in "1", and increment "success" if this frame was successful. */
        mask = window->data;
        window->data = (mask << 1);
        if (status != 0) {
@@ -276,6 +320,7 @@ static int rs_collect_tx_data(struct iwl4965_rate_scale_data *windows,
                window->data |= 0x1;
        }
 
+       /* Calculate current success ratio, avoid divide-by-0! */
        if (window->counter > 0)
                window->success_ratio = 128 * (100 * window->success_counter)
                                        / window->counter;
@@ -284,17 +329,22 @@ static int rs_collect_tx_data(struct iwl4965_rate_scale_data *windows,
 
        fail_count = window->counter - window->success_counter;
 
+       /* Calculate average throughput, if we have enough history. */
        if ((fail_count >= IWL_RATE_MIN_FAILURE_TH) ||
            (window->success_counter >= IWL_RATE_MIN_SUCCESS_TH))
                window->average_tpt = (window->success_ratio * tpt + 64) / 128;
        else
                window->average_tpt = IWL_INVALID_VALUE;
 
+       /* Tag this window as having been updated */
        window->stamp = jiffies;
 
        return 0;
 }
 
+/*
+ * Fill uCode API rate_n_flags field, based on "search" or "active" table.
+ */
 static void rs_mcs_from_tbl(struct iwl4965_rate *mcs_rate,
                           struct iwl4965_scale_tbl_info *tbl,
                           int index, u8 use_green)
@@ -349,6 +399,10 @@ static void rs_mcs_from_tbl(struct iwl4965_rate *mcs_rate,
        }
 }
 
+/*
+ * Interpret uCode API's rate_n_flags format,
+ * fill "search" or "active" tx mode table.
+ */
 static int rs_get_tbl_info_from_mcs(const struct iwl4965_rate *mcs_rate,
                                    int phymode, struct iwl4965_scale_tbl_info *tbl,
                                    int *rate_idx)
@@ -362,11 +416,12 @@ static int rs_get_tbl_info_from_mcs(const struct iwl4965_rate *mcs_rate,
                *rate_idx = -1;
                return -EINVAL;
        }
-       tbl->is_SGI = 0;
+       tbl->is_SGI = 0;        /* default legacy setup */
        tbl->is_fat = 0;
        tbl->is_dup = 0;
-       tbl->antenna_type = ANT_BOTH;
+       tbl->antenna_type = ANT_BOTH;   /* default MIMO setup */
 
+       /* legacy rate format */
        if (!(mcs_rate->rate_n_flags & RATE_MCS_HT_MSK)) {
                ant_msk = (mcs_rate->rate_n_flags & RATE_MCS_ANT_AB_MSK);
 
@@ -386,6 +441,7 @@ static int rs_get_tbl_info_from_mcs(const struct iwl4965_rate *mcs_rate,
                }
                *rate_idx = index;
 
+       /* HT rate format, SISO (might be 20 MHz legacy or 40 MHz fat width) */
        } else if (iwl4965_rate_get_rate(mcs_rate->rate_n_flags)
                                        <= IWL_RATE_SISO_60M_PLCP) {
                tbl->lq_type = LQ_SISO;
@@ -410,6 +466,8 @@ static int rs_get_tbl_info_from_mcs(const struct iwl4965_rate *mcs_rate,
                        tbl->is_dup = 1;
 
                *rate_idx = index;
+
+       /* HT rate format, MIMO (might be 20 MHz legacy or 40 MHz fat width) */
        } else {
                tbl->lq_type = LQ_MIMO;
                if (mcs_rate->rate_n_flags & RATE_MCS_SGI_MSK)
@@ -564,8 +622,9 @@ static void rs_get_lower_rate(struct iwl4965_rate_scale_priv *lq_data,
 
        rs_get_supported_rates(lq_data, NULL, tbl->lq_type, &rate_mask);
 
-       /* mask with station rate restriction */
+       /* Mask with station rate restriction */
        if (is_legacy(tbl->lq_type)) {
+               /* supp_rates has no CCK bits in A mode */
                if (lq_data->phymode == (u8) MODE_IEEE80211A)
                        rate_mask  = (u16)(rate_mask &
                           (lq_data->supp_rates << IWL_FIRST_OFDM_RATE));
@@ -573,7 +632,7 @@ static void rs_get_lower_rate(struct iwl4965_rate_scale_priv *lq_data,
                        rate_mask = (u16)(rate_mask & lq_data->supp_rates);
        }
 
-       /* if we did switched from HT to legacy check current rate */
+       /* If we switched from HT to legacy, check current rate */
        if (switch_to_legacy && (rate_mask & (1 << scale_index))) {
                rs_mcs_from_tbl(mcs_rate, tbl, scale_index, is_green);
                return;
@@ -588,6 +647,9 @@ static void rs_get_lower_rate(struct iwl4965_rate_scale_priv *lq_data,
                rs_mcs_from_tbl(mcs_rate, tbl, scale_index, is_green);
 }
 
+/*
+ * mac80211 sends us Tx status
+ */
 static void rs_tx_status(void *priv_rate,
                         struct net_device *dev,
                         struct sk_buff *skb,
@@ -641,11 +703,14 @@ static void rs_tx_status(void *priv_rate,
        table = &lq->lq;
        active_index = lq->active_tbl;
 
+       /* Get mac80211 antenna info */
        lq->antenna = (lq->valid_antenna & local->hw.conf.antenna_sel_tx);
        if (!lq->antenna)
                lq->antenna = lq->valid_antenna;
 
+       /* Ignore mac80211 antenna info for now */
        lq->antenna = lq->valid_antenna;
+
        curr_tbl = &(lq->lq_info[active_index]);
        search_tbl = &(lq->lq_info[(1 - active_index)]);
        window = (struct iwl4965_rate_scale_data *)
@@ -664,6 +729,14 @@ static void rs_tx_status(void *priv_rate,
                return;
        }
 
+       /*
+        * Ignore this Tx frame response if its initial rate doesn't match
+        * that of latest Link Quality command.  There may be stragglers
+        * from a previous Link Quality command, but we're no longer interested
+        * in those; they're either from the "active" mode while we're trying
+        * to check "search" mode, or a prior "search" mode after we've moved
+        * to a new "search" mode (which might become the new "active" mode).
+        */
        if (retries &&
            (tx_mcs.rate_n_flags !=
                                le32_to_cpu(table->rs_table[0].rate_n_flags))) {
@@ -674,12 +747,17 @@ static void rs_tx_status(void *priv_rate,
                return;
        }
 
+       /* Update frame history window with "failure" for each Tx retry. */
        while (retries) {
+               /* Look up the rate and other info used for each tx attempt.
+                * Each tx attempt steps one entry deeper in the rate table. */
                tx_mcs.rate_n_flags =
                    le32_to_cpu(table->rs_table[index].rate_n_flags);
                rs_get_tbl_info_from_mcs(&tx_mcs, priv->phymode,
                                          &tbl_type, &rs_index);
 
+               /* If type matches "search" table,
+                * add failure to "search" history */
                if ((tbl_type.lq_type == search_tbl->lq_type) &&
                    (tbl_type.antenna_type == search_tbl->antenna_type) &&
                    (tbl_type.is_SGI == search_tbl->is_SGI)) {
@@ -687,8 +765,10 @@ static void rs_tx_status(void *priv_rate,
                                tpt = search_tbl->expected_tpt[rs_index];
                        else
                                tpt = 0;
-                       rs_collect_tx_data(search_win,
-                                           rs_index, tpt, 0);
+                       rs_collect_tx_data(search_win, rs_index, tpt, 0);
+
+               /* Else if type matches "current/active" table,
+                * add failure to "current/active" history */
                } else if ((tbl_type.lq_type == curr_tbl->lq_type) &&
                           (tbl_type.antenna_type == curr_tbl->antenna_type) &&
                           (tbl_type.is_SGI == curr_tbl->is_SGI)) {
@@ -698,6 +778,9 @@ static void rs_tx_status(void *priv_rate,
                                tpt = 0;
                        rs_collect_tx_data(window, rs_index, tpt, 0);
                }
+
+               /* If not searching for a new mode, increment failed counter
+                * ... this helps determine when to start searching again */
                if (lq->stay_in_tbl)
                        lq->total_failed++;
                --retries;
@@ -705,6 +788,11 @@ static void rs_tx_status(void *priv_rate,
 
        }
 
+       /*
+        * Find (by rate) the history window to update with final Tx attempt;
+        * if Tx was successful first try, use original rate,
+        * else look up the rate that was, finally, successful.
+        */
        if (!tx_resp->retry_count)
                tx_mcs.rate_n_flags = tx_resp->control.tx_rate;
        else
@@ -714,11 +802,14 @@ static void rs_tx_status(void *priv_rate,
        rs_get_tbl_info_from_mcs(&tx_mcs, priv->phymode,
                                  &tbl_type, &rs_index);
 
+       /* Update frame history window with "success" if Tx got ACKed ... */
        if (tx_resp->flags & IEEE80211_TX_STATUS_ACK)
                status = 1;
        else
                status = 0;
 
+       /* If type matches "search" table,
+        * add final tx status to "search" history */
        if ((tbl_type.lq_type == search_tbl->lq_type) &&
            (tbl_type.antenna_type == search_tbl->antenna_type) &&
            (tbl_type.is_SGI == search_tbl->is_SGI)) {
@@ -728,6 +819,9 @@ static void rs_tx_status(void *priv_rate,
                        tpt = 0;
                rs_collect_tx_data(search_win,
                                    rs_index, tpt, status);
+
+       /* Else if type matches "current/active" table,
+        * add final tx status to "current/active" history */
        } else if ((tbl_type.lq_type == curr_tbl->lq_type) &&
                   (tbl_type.antenna_type == curr_tbl->antenna_type) &&
                   (tbl_type.is_SGI == curr_tbl->is_SGI)) {
@@ -738,6 +832,8 @@ static void rs_tx_status(void *priv_rate,
                rs_collect_tx_data(window, rs_index, tpt, status);
        }
 
+       /* If not searching for new mode, increment success/failed counter
+        * ... these help determine when to start searching again */
        if (lq->stay_in_tbl) {
                if (status)
                        lq->total_success++;
@@ -745,6 +841,7 @@ static void rs_tx_status(void *priv_rate,
                        lq->total_failed++;
        }
 
+       /* See if there's a better rate or modulation mode to try. */
        rs_rate_scale_perform(priv, dev, hdr, sta);
        sta_info_put(sta);
        return;
@@ -774,11 +871,19 @@ static u8 rs_is_other_ant_connected(u8 valid_antenna,
        return 0;
 }
 
+/*
+ * Begin a period of staying with a selected modulation mode.
+ * Set "stay_in_tbl" flag to prevent any mode switches.
+ * Set frame tx success limits according to legacy vs. high-throughput,
+ * and reset overall (spanning all rates) tx success history statistics.
+ * These control how long we stay using same modulation mode before
+ * searching for a new mode.
+ */
 static void rs_set_stay_in_table(u8 is_legacy,
                                 struct iwl4965_rate_scale_priv *lq_data)
 {
        IWL_DEBUG_HT("we are staying in the same table\n");
-       lq_data->stay_in_tbl = 1;
+       lq_data->stay_in_tbl = 1;       /* only place this gets set */
        if (is_legacy) {
                lq_data->table_count_limit = IWL_LEGACY_TABLE_COUNT;
                lq_data->max_failure_limit = IWL_LEGACY_FAILURE_LIMIT;
@@ -793,6 +898,9 @@ static void rs_set_stay_in_table(u8 is_legacy,
        lq_data->total_success = 0;
 }
 
+/*
+ * Find correct throughput table for given mode of modulation
+ */
 static void rs_get_expected_tpt_table(struct iwl4965_rate_scale_priv *lq_data,
                                      struct iwl4965_scale_tbl_info *tbl)
 {
@@ -827,17 +935,33 @@ static void rs_get_expected_tpt_table(struct iwl4965_rate_scale_priv *lq_data,
 }
 
 #ifdef CONFIG_IWL4965_HT
+/*
+ * Find starting rate for new "search" high-throughput mode of modulation.
+ * Goal is to find lowest expected rate (under perfect conditions) that is
+ * above the current measured throughput of "active" mode, to give new mode
+ * a fair chance to prove itself without too many challenges.
+ *
+ * This gets called when transitioning to more aggressive modulation
+ * (i.e. legacy to SISO or MIMO, or SISO to MIMO), as well as less aggressive
+ * (i.e. MIMO to SISO).  When moving to MIMO, bit rate will typically need
+ * to decrease to match "active" throughput.  When moving from MIMO to SISO,
+ * bit rate will typically need to increase, but not if performance was bad.
+ */
 static s32 rs_get_best_rate(struct iwl4965_priv *priv,
                            struct iwl4965_rate_scale_priv *lq_data,
-                           struct iwl4965_scale_tbl_info *tbl,
+                           struct iwl4965_scale_tbl_info *tbl, /* "search" */
                            u16 rate_mask, s8 index, s8 rate)
 {
+       /* "active" values */
        struct iwl4965_scale_tbl_info *active_tbl =
            &(lq_data->lq_info[lq_data->active_tbl]);
-       s32 new_rate, high, low, start_hi;
        s32 active_sr = active_tbl->win[index].success_ratio;
-       s32 *tpt_tbl = tbl->expected_tpt;
        s32 active_tpt = active_tbl->expected_tpt[index];
+
+       /* expected "search" throughput */
+       s32 *tpt_tbl = tbl->expected_tpt;
+
+       s32 new_rate, high, low, start_hi;
        u16 high_low;
 
        new_rate = high = low = start_hi = IWL_RATE_INVALID;
@@ -848,6 +972,21 @@ static s32 rs_get_best_rate(struct iwl4965_priv *priv,
                low = high_low & 0xff;
                high = (high_low >> 8) & 0xff;
 
+               /*
+                * Lower the "search" bit rate, to give new "search" mode
+                * approximately the same throughput as "active" if:
+                *
+                * 1) "Active" mode has been working modestly well (but not
+                *    great), and expected "search" throughput (under perfect
+                *    conditions) at candidate rate is above the actual
+                *    measured "active" throughput (but less than expected
+                *    "active" throughput under perfect conditions).
+                * OR
+                * 2) "Active" mode has been working perfectly or very well
+                *    and expected "search" throughput (under perfect
+                *    conditions) at candidate rate is above expected
+                *    "active" throughput (under perfect conditions).
+                */
                if ((((100 * tpt_tbl[rate]) > lq_data->last_tpt) &&
                     ((active_sr > IWL_RATE_DECREASE_TH) &&
                      (active_sr <= IWL_RATE_HIGH_TH) &&
@@ -855,21 +994,38 @@ static s32 rs_get_best_rate(struct iwl4965_priv *priv,
                    ((active_sr >= IWL_RATE_SCALE_SWITCH) &&
                     (tpt_tbl[rate] > active_tpt))) {
 
+                       /* (2nd or later pass)
+                        * If we've already tried to raise the rate, and are
+                        * now trying to lower it, use the higher rate. */
                        if (start_hi != IWL_RATE_INVALID) {
                                new_rate = start_hi;
                                break;
                        }
+
                        new_rate = rate;
+
+                       /* Loop again with lower rate */
                        if (low != IWL_RATE_INVALID)
                                rate = low;
+
+                       /* Lower rate not available, use the original */
                        else
                                break;
+
+               /* Else try to raise the "search" rate to match "active" */
                } else {
+                       /* (2nd or later pass)
+                        * If we've already tried to lower the rate, and are
+                        * now trying to raise it, use the lower rate. */
                        if (new_rate != IWL_RATE_INVALID)
                                break;
+
+                       /* Loop again with higher rate */
                        else if (high != IWL_RATE_INVALID) {
                                start_hi = high;
                                rate = high;
+
+                       /* Higher rate not available, use the original */
                        } else {
                                new_rate = rate;
                                break;
@@ -886,6 +1042,9 @@ static inline u8 rs_is_both_ant_supp(u8 valid_antenna)
        return (rs_is_ant_connected(valid_antenna, ANT_BOTH));
 }
 
+/*
+ * Set up search table for MIMO
+ */
 static int rs_switch_to_mimo(struct iwl4965_priv *priv,
                             struct iwl4965_rate_scale_priv *lq_data,
                             struct iwl4965_scale_tbl_info *tbl, int index)
@@ -906,6 +1065,7 @@ static int rs_switch_to_mimo(struct iwl4965_priv *priv,
        if (priv->current_assoc_ht.tx_mimo_ps_mode == IWL_MIMO_PS_STATIC)
                return -1;
 
+       /* Need both Tx chains/antennas to support MIMO */
        if (!rs_is_both_ant_supp(lq_data->antenna))
                return -1;
 
@@ -943,6 +1103,9 @@ static int rs_switch_to_mimo(struct iwl4965_priv *priv,
 #endif                         /*CONFIG_IWL4965_HT */
 }
 
+/*
+ * Set up search table for SISO
+ */
 static int rs_switch_to_siso(struct iwl4965_priv *priv,
                             struct iwl4965_rate_scale_priv *lq_data,
                             struct iwl4965_scale_tbl_info *tbl, int index)
@@ -999,6 +1162,9 @@ static int rs_switch_to_siso(struct iwl4965_priv *priv,
 #endif                         /*CONFIG_IWL4965_HT */
 }
 
+/*
+ * Try to switch to new modulation mode from legacy
+ */
 static int rs_move_legacy_other(struct iwl4965_priv *priv,
                                struct iwl4965_rate_scale_priv *lq_data,
                                int index)
@@ -1020,12 +1186,17 @@ static int rs_move_legacy_other(struct iwl4965_priv *priv,
 
                        search_tbl->lq_type = LQ_NONE;
                        lq_data->action_counter++;
+
+                       /* Don't change antenna if success has been great */
                        if (window->success_ratio >= IWL_RS_GOOD_RATIO)
                                break;
+
+                       /* Don't change antenna if other one is not connected */
                        if (!rs_is_other_ant_connected(lq_data->antenna,
                                                        tbl->antenna_type))
                                break;
 
+                       /* Set up search table to try other antenna */
                        memcpy(search_tbl, tbl, sz);
 
                        rs_toggle_antenna(&(search_tbl->current_rate),
@@ -1036,6 +1207,8 @@ static int rs_move_legacy_other(struct iwl4965_priv *priv,
 
                case IWL_LEGACY_SWITCH_SISO:
                        IWL_DEBUG_HT("LQ: Legacy switch to SISO\n");
+
+                       /* Set up search table to try SISO */
                        memcpy(search_tbl, tbl, sz);
                        search_tbl->lq_type = LQ_SISO;
                        search_tbl->is_SGI = 0;
@@ -1051,6 +1224,8 @@ static int rs_move_legacy_other(struct iwl4965_priv *priv,
                        break;
                case IWL_LEGACY_SWITCH_MIMO:
                        IWL_DEBUG_HT("LQ: Legacy switch MIMO\n");
+
+                       /* Set up search table to try MIMO */
                        memcpy(search_tbl, tbl, sz);
                        search_tbl->lq_type = LQ_MIMO;
                        search_tbl->is_SGI = 0;
@@ -1083,6 +1258,9 @@ static int rs_move_legacy_other(struct iwl4965_priv *priv,
 
 }
 
+/*
+ * Try to switch to new modulation mode from SISO
+ */
 static int rs_move_siso_to_other(struct iwl4965_priv *priv,
                                 struct iwl4965_rate_scale_priv *lq_data,
                                 int index)
@@ -1173,6 +1351,9 @@ static int rs_move_siso_to_other(struct iwl4965_priv *priv,
        return 0;
 }
 
+/*
+ * Try to switch to new modulation mode from MIMO
+ */
 static int rs_move_mimo_to_other(struct iwl4965_priv *priv,
                                 struct iwl4965_rate_scale_priv *lq_data,
                                 int index)
@@ -1193,6 +1374,8 @@ static int rs_move_mimo_to_other(struct iwl4965_priv *priv,
                case IWL_MIMO_SWITCH_ANTENNA_A:
                case IWL_MIMO_SWITCH_ANTENNA_B:
                        IWL_DEBUG_HT("LQ: MIMO SWITCH TO SISO\n");
+
+                       /* Set up new search table for SISO */
                        memcpy(search_tbl, tbl, sz);
                        search_tbl->lq_type = LQ_SISO;
                        search_tbl->is_SGI = 0;
@@ -1212,6 +1395,8 @@ static int rs_move_mimo_to_other(struct iwl4965_priv *priv,
 
                case IWL_MIMO_SWITCH_GI:
                        IWL_DEBUG_HT("LQ: MIMO SWITCH TO GI\n");
+
+                       /* Set up new search table for MIMO */
                        memcpy(search_tbl, tbl, sz);
                        search_tbl->lq_type = LQ_MIMO;
                        search_tbl->antenna_type = ANT_BOTH;
@@ -1221,6 +1406,13 @@ static int rs_move_mimo_to_other(struct iwl4965_priv *priv,
                        else
                                search_tbl->is_SGI = 1;
                        lq_data->search_better_tbl = 1;
+
+                       /*
+                        * If active table already uses the fastest possible
+                        * modulation (dual stream with short guard interval),
+                        * and it's working well, there's no need to look
+                        * for a better type of modulation!
+                        */
                        if ((tbl->lq_type == LQ_MIMO) &&
                            (tbl->is_SGI)) {
                                s32 tpt = lq_data->last_tpt / 100;
@@ -1253,6 +1445,13 @@ static int rs_move_mimo_to_other(struct iwl4965_priv *priv,
 
 }
 
+/*
+ * Check whether we should continue using same modulation mode, or
+ * begin search for a new mode, based on:
+ * 1) # tx successes or failures while using this mode
+ * 2) # times calling this function
+ * 3) elapsed time in this mode (not used, for now)
+ */
 static void rs_stay_in_table(struct iwl4965_rate_scale_priv *lq_data)
 {
        struct iwl4965_scale_tbl_info *tbl;
@@ -1264,15 +1463,27 @@ static void rs_stay_in_table(struct iwl4965_rate_scale_priv *lq_data)
 
        tbl = &(lq_data->lq_info[active_tbl]);
 
+       /* If we've been disallowing search, see if we should now allow it */
        if (lq_data->stay_in_tbl) {
 
+               /* Elapsed time using current modulation mode */
                if (lq_data->flush_timer)
                        flush_interval_passed =
                            time_after(jiffies,
                                       (unsigned long)(lq_data->flush_timer +
                                        IWL_RATE_SCALE_FLUSH_INTVL));
 
+               /* For now, disable the elapsed time criterion */
                flush_interval_passed = 0;
+
+               /*
+                * Check if we should allow search for new modulation mode.
+                * If many frames have failed or succeeded, or we've used
+                * this same modulation for a long time, allow search, and
+                * reset history stats that keep track of whether we should
+                * allow a new search.  Also (below) reset all bitmaps and
+                * stats in active history.
+                */
                if ((lq_data->total_failed > lq_data->max_failure_limit) ||
                    (lq_data->total_success > lq_data->max_success_limit) ||
                    ((!lq_data->search_better_tbl) && (lq_data->flush_timer)
@@ -1281,10 +1492,19 @@ static void rs_stay_in_table(struct iwl4965_rate_scale_priv *lq_data)
                                     lq_data->total_failed,
                                     lq_data->total_success,
                                     flush_interval_passed);
-                       lq_data->stay_in_tbl = 0;
+
+                       /* Allow search for new mode */
+                       lq_data->stay_in_tbl = 0;       /* only place reset */
                        lq_data->total_failed = 0;
                        lq_data->total_success = 0;
                        lq_data->flush_timer = 0;
+
+               /*
+                * Else if we've used this modulation mode enough repetitions
+                * (regardless of elapsed time or success/failure), reset
+                * history bitmaps and rate-specific stats for all rates in
+                * active table.
+                */
                } else {
                        lq_data->table_count++;
                        if (lq_data->table_count >=
@@ -1298,6 +1518,9 @@ static void rs_stay_in_table(struct iwl4965_rate_scale_priv *lq_data)
                        }
                }
 
+               /* If transitioning to allow "search", reset all history
+                * bitmaps and stats in active table (this will become the new
+                * "search" table). */
                if (!lq_data->stay_in_tbl) {
                        for (i = 0; i < IWL_RATE_COUNT; i++)
                                rs_rate_scale_clear_window(&(tbl->win[i]));
@@ -1305,6 +1528,9 @@ static void rs_stay_in_table(struct iwl4965_rate_scale_priv *lq_data)
        }
 }
 
+/*
+ * Do rate scaling and search for new modulation mode.
+ */
 static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                                  struct net_device *dev,
                                  struct ieee80211_hdr *hdr,
@@ -1350,6 +1576,11 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
        }
        lq_data = (struct iwl4965_rate_scale_priv *)sta->rate_ctrl_priv;
 
+       /*
+        * Select rate-scale / modulation-mode table to work with in
+        * the rest of this function:  "search" if searching for better
+        * modulation mode, or "active" if doing rate scaling within a mode.
+        */
        if (!lq_data->search_better_tbl)
                active_tbl = lq_data->active_tbl;
        else
@@ -1358,11 +1589,13 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
        tbl = &(lq_data->lq_info[active_tbl]);
        is_green = lq_data->is_green;
 
+       /* current tx rate */
        index = sta->last_txrate;
 
        IWL_DEBUG_RATE("Rate scale index %d for type %d\n", index,
                       tbl->lq_type);
 
+       /* rates available for this association, and for modulation mode */
        rs_get_supported_rates(lq_data, hdr, tbl->lq_type,
                                &rate_mask);
 
@@ -1371,6 +1604,7 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
        /* mask with station rate restriction */
        if (is_legacy(tbl->lq_type)) {
                if (lq_data->phymode == (u8) MODE_IEEE80211A)
+                       /* supp_rates has no CCK bits in A mode */
                        rate_scale_index_msk = (u16) (rate_mask &
                                (lq_data->supp_rates << IWL_FIRST_OFDM_RATE));
                else
@@ -1383,11 +1617,13 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
        if (!rate_scale_index_msk)
                rate_scale_index_msk = rate_mask;
 
+       /* If current rate is no longer supported on current association,
+        * or user changed preferences for rates, find a new supported rate. */
        if (index < 0 || !((1 << index) & rate_scale_index_msk)) {
                index = IWL_INVALID_VALUE;
                update_lq = 1;
 
-               /* get the lowest available rate */
+               /* get the highest available rate */
                for (i = 0; i <= IWL_RATE_COUNT; i++) {
                        if ((1 << i) & rate_scale_index_msk)
                                index = i;
@@ -1399,11 +1635,19 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                }
        }
 
+       /* Get expected throughput table and history window for current rate */
        if (!tbl->expected_tpt)
                rs_get_expected_tpt_table(lq_data, tbl);
 
        window = &(tbl->win[index]);
 
+       /*
+        * If there is not enough history to calculate actual average
+        * throughput, keep analyzing results of more tx frames, without
+        * changing rate or mode (bypass most of the rest of this function).
+        * Set up new rate table in uCode only if old rate is not supported
+        * in current association (use new rate found above).
+        */
        fail_count = window->counter - window->success_counter;
        if (((fail_count < IWL_RATE_MIN_FAILURE_TH) &&
             (window->success_counter < IWL_RATE_MIN_SUCCESS_TH))
@@ -1411,8 +1655,15 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                IWL_DEBUG_RATE("LQ: still below TH succ %d total %d "
                               "for index %d\n",
                               window->success_counter, window->counter, index);
+
+               /* Can't calculate this yet; not enough history */
                window->average_tpt = IWL_INVALID_VALUE;
+
+               /* Should we stay with this modulation mode,
+                * or search for a new one? */
                rs_stay_in_table(lq_data);
+
+               /* Set up new rate table in uCode, if needed */
                if (update_lq) {
                        rs_mcs_from_tbl(&mcs_rate, tbl, index, is_green);
                        rs_fill_link_cmd(lq_data, &mcs_rate, &lq_data->lq);
@@ -1420,13 +1671,19 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                }
                goto out;
 
+       /* Else we have enough samples; calculate estimate of
+        * actual average throughput */
        } else
                window->average_tpt = ((window->success_ratio *
                                        tbl->expected_tpt[index] + 64) / 128);
 
+       /* If we are searching for better modulation mode, check success. */
        if (lq_data->search_better_tbl) {
                int success_limit = IWL_RATE_SCALE_SWITCH;
 
+               /* If good success, continue using the "search" mode;
+                * no need to send new link quality command, since we're
+                * continuing to use the setup that we've been trying. */
                if ((window->success_ratio > success_limit) ||
                    (window->average_tpt > lq_data->last_tpt)) {
                        if (!is_legacy(tbl->lq_type)) {
@@ -1438,55 +1695,78 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                                             lq_data->last_tpt);
                                lq_data->enable_counter = 1;
                        }
+                       /* Swap tables; "search" becomes "active" */
                        lq_data->active_tbl = active_tbl;
                        current_tpt = window->average_tpt;
+
+               /* Else poor success; go back to mode in "active" table */
                } else {
+                       /* Nullify "search" table */
                        tbl->lq_type = LQ_NONE;
+
+                       /* Revert to "active" table */
                        active_tbl = lq_data->active_tbl;
                        tbl = &(lq_data->lq_info[active_tbl]);
 
+                       /* Revert to "active" rate and throughput info */
                        index = iwl4965_rate_index_from_plcp(
                                tbl->current_rate.rate_n_flags);
+                       current_tpt = lq_data->last_tpt;
 
+                       /* Need to set up a new rate table in uCode */
                        update_lq = 1;
-                       current_tpt = lq_data->last_tpt;
                        IWL_DEBUG_HT("XXY GO BACK TO OLD TABLE\n");
                }
+
+               /* Either way, we've made a decision; modulation mode
+                * search is done, allow rate adjustment next time. */
                lq_data->search_better_tbl = 0;
-               done_search = 1;
+               done_search = 1;        /* Don't switch modes below! */
                goto lq_update;
        }
 
+       /* (Else) not in search of better modulation mode, try for better
+        * starting rate, while staying in this mode. */
        high_low = rs_get_adjacent_rate(index, rate_scale_index_msk,
                                        tbl->lq_type);
        low = high_low & 0xff;
        high = (high_low >> 8) & 0xff;
 
+       /* Collect measured throughputs for current and adjacent rates */
        current_tpt = window->average_tpt;
-
        if (low != IWL_RATE_INVALID)
                low_tpt = tbl->win[low].average_tpt;
-
        if (high != IWL_RATE_INVALID)
                high_tpt = tbl->win[high].average_tpt;
 
-
+       /* Assume rate increase */
        scale_action = 1;
 
+       /* Too many failures, decrease rate */
        if ((window->success_ratio <= IWL_RATE_DECREASE_TH) ||
            (current_tpt == 0)) {
                IWL_DEBUG_RATE("decrease rate because of low success_ratio\n");
                scale_action = -1;
+
+       /* No throughput measured yet for adjacent rates; try increase. */
        } else if ((low_tpt == IWL_INVALID_VALUE) &&
                   (high_tpt == IWL_INVALID_VALUE))
                scale_action = 1;
+
+       /* Both adjacent throughputs are measured, but neither one has better
+        * throughput; we're using the best rate, don't change it! */
        else if ((low_tpt != IWL_INVALID_VALUE) &&
                 (high_tpt != IWL_INVALID_VALUE) &&
                 (low_tpt < current_tpt) &&
                 (high_tpt < current_tpt))
                scale_action = 0;
+
+       /* At least one adjacent rate's throughput is measured,
+        * and may have better performance. */
        else {
+               /* Higher adjacent rate's throughput is measured */
                if (high_tpt != IWL_INVALID_VALUE) {
+                       /* Higher rate has better throughput */
                        if (high_tpt > current_tpt)
                                scale_action = 1;
                        else {
@@ -1494,7 +1774,10 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                                    ("decrease rate because of high tpt\n");
                                scale_action = -1;
                        }
+
+               /* Lower adjacent rate's throughput is measured */
                } else if (low_tpt != IWL_INVALID_VALUE) {
+                       /* Lower rate has better throughput */
                        if (low_tpt > current_tpt) {
                                IWL_DEBUG_RATE
                                    ("decrease rate because of low tpt\n");
@@ -1504,23 +1787,30 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                }
        }
 
+       /* Sanity check; asked for decrease, but success rate or throughput
+        * has been good at old rate.  Don't change it. */
        if (scale_action == -1) {
                if ((low != IWL_RATE_INVALID) &&
                    ((window->success_ratio > IWL_RATE_HIGH_TH) ||
                     (current_tpt > (100 * tbl->expected_tpt[low]))))
                        scale_action = 0;
+
+       /* Sanity check; asked for increase, but success rate has not been great
+        * even at old rate, higher rate will be worse.  Don't change it. */
        } else if ((scale_action == 1) &&
                   (window->success_ratio < IWL_RATE_INCREASE_TH))
                scale_action = 0;
 
        switch (scale_action) {
        case -1:
+               /* Decrease starting rate, update uCode's rate table */
                if (low != IWL_RATE_INVALID) {
                        update_lq = 1;
                        index = low;
                }
                break;
        case 1:
+               /* Increase starting rate, update uCode's rate table */
                if (high != IWL_RATE_INVALID) {
                        update_lq = 1;
                        index = high;
@@ -1528,6 +1818,7 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
 
                break;
        case 0:
+               /* No change */
        default:
                break;
        }
@@ -1537,16 +1828,28 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                     index, scale_action, low, high, tbl->lq_type);
 
  lq_update:
+       /* Replace uCode's rate table for the destination station. */
        if (update_lq) {
                rs_mcs_from_tbl(&mcs_rate, tbl, index, is_green);
                rs_fill_link_cmd(lq_data, &mcs_rate, &lq_data->lq);
                rs_send_lq_cmd(priv, &lq_data->lq, CMD_ASYNC);
        }
+
+       /* Should we stay with this modulation mode, or search for a new one? */
        rs_stay_in_table(lq_data);
 
+       /*
+        * Search for new modulation mode if we're:
+        * 1)  Not changing rates right now
+        * 2)  Not just finishing up a search
+        * 3)  Allowing a new search
+        */
        if (!update_lq && !done_search && !lq_data->stay_in_tbl) {
+               /* Save current throughput to compare with "search" throughput*/
                lq_data->last_tpt = current_tpt;
 
+               /* Select a new "search" modulation mode to try.
+                * If one is found, set up the new "search" table. */
                if (is_legacy(tbl->lq_type))
                        rs_move_legacy_other(priv, lq_data, index);
                else if (is_siso(tbl->lq_type))
@@ -1554,11 +1857,14 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                else
                        rs_move_mimo_to_other(priv, lq_data, index);
 
+               /* If new "search" mode was selected, set up in uCode table */
                if (lq_data->search_better_tbl) {
+                       /* Access the "search" table, clear its history. */
                        tbl = &(lq_data->lq_info[(1 - lq_data->active_tbl)]);
                        for (i = 0; i < IWL_RATE_COUNT; i++)
                                rs_rate_scale_clear_window(&(tbl->win[i]));
 
+                       /* Use new "search" start rate */
                        index = iwl4965_rate_index_from_plcp(
                                        tbl->current_rate.rate_n_flags);
 
@@ -1568,8 +1874,13 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                                         &lq_data->lq);
                        rs_send_lq_cmd(priv, &lq_data->lq, CMD_ASYNC);
                }
-               tbl1 = &(lq_data->lq_info[lq_data->active_tbl]);
 
+               /* If the "active" (non-search) mode was legacy,
+                * and we've tried switching antennas,
+                * but we haven't been able to try HT modes (not available),
+                * stay with best antenna legacy modulation for a while
+                * before next round of mode comparisons. */
+               tbl1 = &(lq_data->lq_info[lq_data->active_tbl]);
                if (is_legacy(tbl1->lq_type) &&
 #ifdef CONFIG_IWL4965_HT
                    !priv->current_assoc_ht.is_ht &&
@@ -1580,9 +1891,13 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                        rs_set_stay_in_table(1, lq_data);
                }
 
+               /* If we're in an HT mode, and all 3 mode switch actions
+                * have been tried and compared, stay in this best modulation
+                * mode for a while before next round of mode comparisons. */
                if (lq_data->enable_counter &&
                    (lq_data->action_counter >= IWL_ACTION_LIMIT)) {
 #ifdef CONFIG_IWL4965_HT_AGG
+                       /* If appropriate, set up aggregation! */
                        if ((lq_data->last_tpt > TID_AGG_TPT_THREHOLD) &&
                            (priv->lq_mngr.agg_ctrl.auto_agg)) {
                                priv->lq_mngr.agg_ctrl.tid_retry =
@@ -1593,6 +1908,14 @@ static void rs_rate_scale_perform(struct iwl4965_priv *priv,
                        lq_data->action_counter = 0;
                        rs_set_stay_in_table(0, lq_data);
                }
+
+       /*
+        * Else, don't search for a new modulation mode.
+        * Put new timestamp in stay-in-modulation-mode flush timer if:
+        * 1)  Not changing rates right now
+        * 2)  Not just finishing up a search
+        * 3)  flush timer is empty
+        */
        } else {
                if ((!update_lq) && (!done_search) && (!lq_data->flush_timer))
                        lq_data->flush_timer = jiffies;
@@ -1789,15 +2112,14 @@ static void rs_rate_init(void *priv_rate, void *priv_sta,
                priv->assoc_station_added = 1;
        }
 
+       /* Find highest tx rate supported by hardware and destination station */
        for (i = 0; i < mode->num_rates; i++) {
                if ((sta->supp_rates & BIT(i)) &&
                    (mode->rates[i].flags & IEEE80211_RATE_SUPPORTED))
                        sta->txrate = i;
        }
        sta->last_txrate = sta->txrate;
-       /* For MODE_IEEE80211A mode cck rate are at end
-        * rate table
-        */
+       /* For MODE_IEEE80211A, cck rates are at end of rate table */
        if (local->hw.conf.phymode == MODE_IEEE80211A)
                sta->last_txrate += IWL_FIRST_OFDM_RATE;
 
@@ -1810,11 +2132,16 @@ static void rs_rate_init(void *priv_rate, void *priv_sta,
        crl->active_rate_basic = priv->active_rate_basic;
        crl->phymode = priv->phymode;
 #ifdef CONFIG_IWL4965_HT
+       /*
+        * active_siso_rate mask includes 9 MBits (bit 5), and CCK (bits 0-3),
+        * supp_rates[] does not; shift to convert format, force 9 MBits off.
+        */
        crl->active_siso_rate = (priv->current_assoc_ht.supp_rates[0] << 1);
        crl->active_siso_rate |= (priv->current_assoc_ht.supp_rates[0] & 0x1);
        crl->active_siso_rate &= ~((u16)0x2);
        crl->active_siso_rate = crl->active_siso_rate << IWL_FIRST_OFDM_RATE;
 
+       /* Same here */
        crl->active_mimo_rate = (priv->current_assoc_ht.supp_rates[1] << 1);
        crl->active_mimo_rate |= (priv->current_assoc_ht.supp_rates[1] & 0x1);
        crl->active_mimo_rate &= ~((u16)0x2);
@@ -1844,11 +2171,14 @@ static void rs_fill_link_cmd(struct iwl4965_rate_scale_priv *lq_data,
        struct iwl4965_rate new_rate;
        struct iwl4965_scale_tbl_info tbl_type = { 0 };
 
+       /* Override starting rate (index 0) if needed for debug purposes */
        rs_dbgfs_set_mcs(lq_data, tx_mcs, index);
 
+       /* Interpret rate_n_flags */
        rs_get_tbl_info_from_mcs(tx_mcs, lq_data->phymode,
                                  &tbl_type, &rate_idx);
 
+       /* How many times should we repeat the initial rate? */
        if (is_legacy(tbl_type.lq_type)) {
                ant_toggle_count = 1;
                repeat_rate = IWL_NUMBER_TRY;
@@ -1857,19 +2187,27 @@ static void rs_fill_link_cmd(struct iwl4965_rate_scale_priv *lq_data,
 
        lq_cmd->general_params.mimo_delimiter =
                        is_mimo(tbl_type.lq_type) ? 1 : 0;
+
+       /* Fill 1st table entry (index 0) */
        lq_cmd->rs_table[index].rate_n_flags =
                        cpu_to_le32(tx_mcs->rate_n_flags);
        new_rate.rate_n_flags = tx_mcs->rate_n_flags;
 
        if (is_mimo(tbl_type.lq_type) || (tbl_type.antenna_type == ANT_MAIN))
-               lq_cmd->general_params.single_stream_ant_msk = 1;
+               lq_cmd->general_params.single_stream_ant_msk
+                       = LINK_QUAL_ANT_A_MSK;
        else
-               lq_cmd->general_params.single_stream_ant_msk = 2;
+               lq_cmd->general_params.single_stream_ant_msk
+                       = LINK_QUAL_ANT_B_MSK;
 
        index++;
        repeat_rate--;
 
+       /* Fill rest of rate table */
        while (index < LINK_QUAL_MAX_RETRY_NUM) {
+               /* Repeat initial/next rate.
+                * For legacy IWL_NUMBER_TRY == 1, this loop will not execute.
+                * For HT IWL_HT_NUMBER_TRY == 3, this executes twice. */
                while (repeat_rate > 0 && (index < LINK_QUAL_MAX_RETRY_NUM)) {
                        if (is_legacy(tbl_type.lq_type)) {
                                if (ant_toggle_count <
@@ -1881,7 +2219,10 @@ static void rs_fill_link_cmd(struct iwl4965_rate_scale_priv *lq_data,
                                }
                        }
 
+                       /* Override next rate if needed for debug purposes */
                        rs_dbgfs_set_mcs(lq_data, &new_rate, index);
+
+                       /* Fill next table entry */
                        lq_cmd->rs_table[index].rate_n_flags =
                                        cpu_to_le32(new_rate.rate_n_flags);
                        repeat_rate--;
@@ -1891,12 +2232,17 @@ static void rs_fill_link_cmd(struct iwl4965_rate_scale_priv *lq_data,
                rs_get_tbl_info_from_mcs(&new_rate, lq_data->phymode, &tbl_type,
                                                &rate_idx);
 
+               /* Indicate to uCode which entries might be MIMO.
+                * If initial rate was MIMO, this will finally end up
+                * as (IWL_HT_NUMBER_TRY * 2), after 2nd pass, otherwise 0. */
                if (is_mimo(tbl_type.lq_type))
                        lq_cmd->general_params.mimo_delimiter = index;
 
+               /* Get next rate */
                rs_get_lower_rate(lq_data, &tbl_type, rate_idx,
                                  use_ht_possible, &new_rate);
 
+               /* How many times should we repeat the next rate? */
                if (is_legacy(tbl_type.lq_type)) {
                        if (ant_toggle_count < NUM_TRY_BEFORE_ANTENNA_TOGGLE)
                                ant_toggle_count++;
@@ -1908,9 +2254,14 @@ static void rs_fill_link_cmd(struct iwl4965_rate_scale_priv *lq_data,
                } else
                        repeat_rate = IWL_HT_NUMBER_TRY;
 
+               /* Don't allow HT rates after next pass.
+                * rs_get_lower_rate() will change type to LQ_A or LQ_G. */
                use_ht_possible = 0;
 
+               /* Override next rate if needed for debug purposes */
                rs_dbgfs_set_mcs(lq_data, &new_rate, index);
+
+               /* Fill next table entry */
                lq_cmd->rs_table[index].rate_n_flags =
                                cpu_to_le32(new_rate.rate_n_flags);
 
@@ -2006,9 +2357,9 @@ static ssize_t rs_sta_dbgfs_scale_table_write(struct file *file,
        else
                rs_priv->dbg_fixed.rate_n_flags = 0;
 
-       rs_priv->active_rate = 0x0FFF;
-       rs_priv->active_siso_rate = 0x1FD0;
-       rs_priv->active_mimo_rate = 0x1FD0;
+       rs_priv->active_rate = 0x0FFF;          /* 1 - 54 MBits, includes CCK */
+       rs_priv->active_siso_rate = 0x1FD0;     /* 6 - 60 MBits, no 9, no CCK */
+       rs_priv->active_mimo_rate = 0x1FD0;     /* 6 - 60 MBits, no 9, no CCK */
 
        IWL_DEBUG_RATE("sta_id %d rate 0x%X\n",
                rs_priv->lq.sta_id, rs_priv->dbg_fixed.rate_n_flags);
@@ -2209,7 +2560,7 @@ int iwl4965_fill_rs_info(struct ieee80211_hw *hw, char *buf, u8 sta_id)
 
        /* Display the average rate of all samples taken.
         *
-        * NOTE:  We multiple # of samples by 2 since the IEEE measurement
+        * NOTE:  We multiply # of samples by 2 since the IEEE measurement
         * added from iwl4965_rates is actually 2X the rate */
        if (samples)
                count += sprintf(&buf[count],
index 4259099eae71d4fcd45734a14ec227cdca4abd86..86f62d8090589cdd1dc50a00b64abac860c8ad39 100644 (file)
 #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,
index 5944b4b9828bfd30dddca990ffd608ea79f06066..d0abbb3a5ac70e1ac1a7b9a0d7a7699012a31983 100644 (file)
@@ -489,7 +489,7 @@ struct sta_ht_info {
        u8 supported_chan_width;
        u8 extension_chan_offset;
        u8 is_green_field;
-       u8 sgf;
+       u8 sgf;                 /* HT_SHORT_GI_* short guard interval */
        u8 supp_rates[16];
        u8 tx_chan_width;
        u8 chan_width_cap;
index 11ef1c0c5d0de6de58020aa1fd781ca0c65f745d..33eace7574355e828b4f026052981f4cf34beb79 100644 (file)
@@ -1488,6 +1488,7 @@ int iwl4965_rate_index_from_plcp(int plcp)
 {
        int i = 0;
 
+       /* 4965 HT rate format */
        if (plcp & RATE_MCS_HT_MSK) {
                i = (plcp & 0xff);
 
@@ -1501,6 +1502,8 @@ int iwl4965_rate_index_from_plcp(int plcp)
                if ((i >= IWL_FIRST_OFDM_RATE) &&
                    (i <= IWL_LAST_OFDM_RATE))
                        return i;
+
+       /* 4965 legacy rate format, search for match in table */
        } else {
                for (i = 0; i < ARRAY_SIZE(iwl4965_rates); i++)
                        if (iwl4965_rates[i].plcp == (plcp &0xFF))