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 88 struct ath_rc_series { 89 uint8_t rix; /* ratetable index, not rate code */ 90 uint8_t ratecode; /* hardware rate code */ 91 uint8_t tries; 92 uint8_t flags; 93 uint32_t max4msframelen; 94 }; 95 96 /* 97 * State storage handling. 98 */ 99 /* 100 * Initialize per-node state already allocated for the specified 101 * node; this space can be assumed initialized to zero. 102 */ 103 void ath_rate_node_init(struct ath_softc *, struct ath_node *); 104 /* 105 * Cleanup any per-node state prior to the node being reclaimed. 106 */ 107 void ath_rate_node_cleanup(struct ath_softc *, struct ath_node *); 108 /* 109 * Update rate control state on station associate/reassociate 110 * (when operating as an ap or for nodes discovered when operating 111 * in ibss mode). 112 */ 113 void ath_rate_newassoc(struct ath_softc *, struct ath_node *, 114 int isNewAssociation); 115 116 /* 117 * Transmit handling. 118 */ 119 /* 120 * Return the four TX rate index and try counts for the current data packet. 121 */ 122 void ath_rate_getxtxrates(struct ath_softc *sc, struct ath_node *an, 123 uint8_t rix0, struct ath_rc_series *rc); 124 125 /* 126 * Return the transmit info for a data packet. If multi-rate state 127 * is to be setup then try0 should contain a value other than ATH_TXMATRY 128 * and ath_rate_setupxtxdesc will be called after deciding if the frame 129 * can be transmitted with multi-rate retry. 130 */ 131 void ath_rate_findrate(struct ath_softc *, struct ath_node *, 132 int shortPreamble, size_t frameLen, 133 u_int8_t *rix, int *try0, u_int8_t *txrate); 134 /* 135 * Setup any extended (multi-rate) descriptor state for a data packet. 136 * The rate index returned by ath_rate_findrate is passed back in. 137 */ 138 void ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *, 139 struct ath_desc *, int shortPreamble, u_int8_t rix); 140 /* 141 * Update rate control state for a packet associated with the 142 * supplied transmit descriptor. The routine is invoked both 143 * for packets that were successfully sent and for those that 144 * failed (consult the descriptor for details). 145 * 146 * For A-MPDU frames, nframes and nbad indicate how many frames 147 * were in the aggregate, and how many failed. 148 */ 149 struct ath_buf; 150 void ath_rate_tx_complete(struct ath_softc *, struct ath_node *, 151 const struct ath_rc_series *, const struct ath_tx_status *, 152 int pktlen, int nframes, int nbad); 153 154 /* 155 * Fetch the global rate control statistics. 156 */ 157 int ath_rate_fetch_stats(struct ath_softc *sc, struct ath_rateioctl *rs); 158 159 /* 160 * Fetch the per-node statistics. 161 */ 162 int ath_rate_fetch_node_stats(struct ath_softc *sc, struct ath_node *an, 163 struct ath_rateioctl *rs); 164 165 #endif /* _ATH_RATECTRL_H_ */ 166