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