2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 * Copyright (c) 2004-2008 Sam Leffler, Errno Consulting
5 * Copyright (c) 2004 Video54 Technologies, Inc.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
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.
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.
34 #ifndef _ATH_RATECTRL_H_
35 #define _ATH_RATECTRL_H_
38 * Interface definitions for transmit rate control modules for the
41 * A rate control module is responsible for choosing the transmit rate
42 * for each data frame. Management+control frames are always sent at
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.
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.
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
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.
74 size_t arc_space; /* space required for per-node state */
77 * Attach/detach a rate control module.
79 struct ath_ratectrl *ath_rate_attach(struct ath_softc *);
80 void ath_rate_detach(struct ath_ratectrl *);
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 */
92 struct ath_rc_series {
93 uint8_t rix; /* ratetable index, not rate code */
94 uint8_t ratecode; /* hardware rate code */
98 uint16_t max4msframelen;
102 * State storage handling.
105 * Initialize per-node state already allocated for the specified
106 * node; this space can be assumed initialized to zero.
108 void ath_rate_node_init(struct ath_softc *, struct ath_node *);
110 * Cleanup any per-node state prior to the node being reclaimed.
112 void ath_rate_node_cleanup(struct ath_softc *, struct ath_node *);
114 * Update rate control state on station associate/reassociate
115 * (when operating as an ap or for nodes discovered when operating
118 void ath_rate_newassoc(struct ath_softc *, struct ath_node *,
119 int isNewAssociation);
125 * Return the four TX rate index and try counts for the current data packet.
127 void ath_rate_getxtxrates(struct ath_softc *sc, struct ath_node *an,
128 uint8_t rix0, struct ath_rc_series *rc);
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.
136 void ath_rate_findrate(struct ath_softc *, struct ath_node *,
137 int shortPreamble, size_t frameLen,
138 u_int8_t *rix, int *try0, u_int8_t *txrate);
140 * Setup any extended (multi-rate) descriptor state for a data packet.
141 * The rate index returned by ath_rate_findrate is passed back in.
143 void ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *,
144 struct ath_desc *, int shortPreamble, u_int8_t rix);
146 * Update rate control state for a packet associated with the
147 * supplied transmit descriptor. The routine is invoked both
148 * for packets that were successfully sent and for those that
149 * failed (consult the descriptor for details).
151 * For A-MPDU frames, nframes and nbad indicate how many frames
152 * were in the aggregate, and how many failed.
155 void ath_rate_tx_complete(struct ath_softc *, struct ath_node *,
156 const struct ath_rc_series *, const struct ath_tx_status *,
157 int pktlen, int nframes, int nbad);
160 * Update rate control with a per-packet receive RSSI value.
162 void ath_rate_update_rx_rssi(struct ath_softc *, struct ath_node *,
166 * Fetch the global rate control statistics.
168 int ath_rate_fetch_stats(struct ath_softc *sc, struct ath_rateioctl *rs);
171 * Fetch the per-node statistics.
173 int ath_rate_fetch_node_stats(struct ath_softc *sc, struct ath_node *an,
174 struct ath_rateioctl *rs);
176 #endif /* _ATH_RATECTRL_H_ */