sys/dev/ath/if_athrate.h

   1 /*-
   2  * Copyright (c) 2004-2008 Sam Leffler, Errno Consulting
   3  * Copyright (c) 2004 Video54 Technologies, Inc.
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer,
  11  *    without modification.
  12  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  13  *    similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any
  14  *    redistribution must be conditioned upon including a substantially
  15  *    similar Disclaimer requirement for further binary redistribution.
  16  *
  17  * NO WARRANTY
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY
  21  * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  22  * THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY,
  23  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  26  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  28  * THE POSSIBILITY OF SUCH DAMAGES.
  29  *
  30  * $FreeBSD$
  31  */
  32 #ifndef _ATH_RATECTRL_H_
  33 #define _ATH_RATECTRL_H_
  34
  35 /*
  36  * Interface definitions for transmit rate control modules for the
  37  * Atheros driver.
  38  *
  39  * A rate control module is responsible for choosing the transmit rate
  40  * for each data frame.  Management+control frames are always sent at
  41  * a fixed rate.
  42  *
  43  * Only one module may be present at a time; the driver references
  44  * rate control interfaces by symbol name.  If multiple modules are
  45  * to be supported we'll need to switch to a registration-based scheme
  46  * as is currently done, for example, for authentication modules.
  47  *
  48  * An instance of the rate control module is attached to each device
  49  * at attach time and detached when the device is destroyed.  The module
  50  * may associate data with each device and each node (station).  Both
  51  * sets of storage are opaque except for the size of the per-node storage
  52  * which must be provided when the module is attached.
  53  *
  54  * The rate control module is notified for each state transition and
  55  * station association/reassociation.  Otherwise it is queried for a
  56  * rate for each outgoing frame and provided status from each transmitted
  57  * frame.  Any ancillary processing is the responsibility of the module
  58  * (e.g. if periodic processing is required then the module should setup
  59  * it's own timer).
  60  *
  61  * In addition to the transmit rate for each frame the module must also
  62  * indicate the number of attempts to make at the specified rate.  If this
  63  * number is != ATH_TXMAXTRY then an additional callback is made to setup
  64  * additional transmit state.  The rate control code is assumed to write
  65  * this additional data directly to the transmit descriptor.
  66  */
  67 struct ath_softc;
  68 struct ath_node;
  69 struct ath_desc;
  70
  71 struct ath_ratectrl {
  72         size_t  arc_space;      /* space required for per-node state */
  73 };
  74 /*
  75  * Attach/detach a rate control module.
  76  */
  77 struct ath_ratectrl *ath_rate_attach(struct ath_softc *);
  78 void    ath_rate_detach(struct ath_ratectrl *);
  79
  80 #define ATH_RC_NUM              4
  81
  82 #define ATH_RC_DS_FLAG          0x01    /* dual-stream rate */
  83 #define ATH_RC_CW40_FLAG        0x02    /* use HT40 */
  84 #define ATH_RC_SGI_FLAG         0x04    /* use short-GI */
  85 #define ATH_RC_HT_FLAG          0x08    /* use HT */
  86 #define ATH_RC_RTSCTS_FLAG      0x10    /* enable RTS/CTS protection */
  87 #define ATH_RC_STBC_FLAG        0x20    /* enable STBC */
  88 #define ATH_RC_TS_FLAG          0x40    /* triple-stream rate */
  89
  90 struct ath_rc_series {
  91         uint8_t rix;            /* ratetable index, not rate code */
  92         uint8_t ratecode;       /* hardware rate code */
  93         uint8_t tries;
  94         uint8_t tx_power_cap;
  95         uint16_t flags;
  96         uint16_t max4msframelen;
  97 };
  98
  99 /*
 100  * State storage handling.
 101  */
 102 /*
 103  * Initialize per-node state already allocated for the specified
 104  * node; this space can be assumed initialized to zero.
 105  */
 106 void    ath_rate_node_init(struct ath_softc *, struct ath_node *);
 107 /*
 108  * Cleanup any per-node state prior to the node being reclaimed.
 109  */
 110 void    ath_rate_node_cleanup(struct ath_softc *, struct ath_node *);
 111 /*
 112  * Update rate control state on station associate/reassociate
 113  * (when operating as an ap or for nodes discovered when operating
 114  * in ibss mode).
 115  */
 116 void    ath_rate_newassoc(struct ath_softc *, struct ath_node *,
 117                 int isNewAssociation);
 118
 119 /*
 120  * Transmit handling.
 121  */
 122 /*
 123  * Return the four TX rate index and try counts for the current data packet.
 124  */
 125 void    ath_rate_getxtxrates(struct ath_softc *sc, struct ath_node *an,
 126                 uint8_t rix0, struct ath_rc_series *rc);
 127
 128 /*
 129  * Return the transmit info for a data packet.  If multi-rate state
 130  * is to be setup then try0 should contain a value other than ATH_TXMATRY
 131  * and ath_rate_setupxtxdesc will be called after deciding if the frame
 132  * can be transmitted with multi-rate retry.
 133  */
 134 void    ath_rate_findrate(struct ath_softc *, struct ath_node *,
 135                 int shortPreamble, size_t frameLen,
 136                 u_int8_t *rix, int *try0, u_int8_t *txrate);
 137 /*
 138  * Setup any extended (multi-rate) descriptor state for a data packet.
 139  * The rate index returned by ath_rate_findrate is passed back in.
 140  */
 141 void    ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *,
 142                 struct ath_desc *, int shortPreamble, u_int8_t rix);
 143 /*
 144  * Update rate control state for a packet associated with the
 145  * supplied transmit descriptor.  The routine is invoked both
 146  * for packets that were successfully sent and for those that
 147  * failed (consult the descriptor for details).
 148  *
 149  * For A-MPDU frames, nframes and nbad indicate how many frames
 150  * were in the aggregate, and how many failed.
 151  */
 152 struct ath_buf;
 153 void    ath_rate_tx_complete(struct ath_softc *, struct ath_node *,
 154                 const struct ath_rc_series *, const struct ath_tx_status *,
 155                 int pktlen, int nframes, int nbad);
 156
 157 /*
 158  * Fetch the global rate control statistics.
 159  */
 160 int     ath_rate_fetch_stats(struct ath_softc *sc, struct ath_rateioctl *rs);
 161
 162 /*
 163  * Fetch the per-node statistics.
 164  */
 165 int     ath_rate_fetch_node_stats(struct ath_softc *sc, struct ath_node *an,
 166                 struct ath_rateioctl *rs);
 167
 168 #endif /* _ATH_RATECTRL_H_ */