| 1 | /* $NetBSD: athrate.h,v 1.3 2014/10/18 08:33:27 snj Exp $ */ |
| 2 | |
| 3 | /*- |
| 4 | * Copyright (c) 2004-2005 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 | * 3. Neither the names of the above-listed copyright holders nor the names |
| 19 | * of any contributors may be used to endorse or promote products derived |
| 20 | * from this software without specific prior written permission. |
| 21 | * |
| 22 | * Alternatively, this software may be distributed under the terms of the |
| 23 | * GNU General Public License ("GPL") version 2 as published by the Free |
| 24 | * Software Foundation. |
| 25 | * |
| 26 | * NO WARRANTY |
| 27 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 28 | * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 29 | * LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY |
| 30 | * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL |
| 31 | * THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, |
| 32 | * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| 33 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 34 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER |
| 35 | * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 36 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF |
| 37 | * THE POSSIBILITY OF SUCH DAMAGES. |
| 38 | * |
| 39 | * $FreeBSD: src/sys/dev/ath/if_athrate.h,v 1.4 2005/04/02 18:54:30 sam Exp $ |
| 40 | */ |
| 41 | #ifndef _ATH_RATECTRL_H_ |
| 42 | #define _ATH_RATECTRL_H_ |
| 43 | |
| 44 | /* |
| 45 | * Interface definitions for transmit rate control modules for the |
| 46 | * Atheros driver. |
| 47 | * |
| 48 | * A rate control module is responsible for choosing the transmit rate |
| 49 | * for each data frame. Management+control frames are always sent at |
| 50 | * a fixed rate. |
| 51 | * |
| 52 | * Only one module may be present at a time; the driver references |
| 53 | * rate control interfaces by symbol name. If multiple modules are |
| 54 | * to be supported we'll need to switch to a registration-based scheme |
| 55 | * as is currently done, for example, for authentication modules. |
| 56 | * |
| 57 | * An instance of the rate control module is attached to each device |
| 58 | * at attach time and detached when the device is destroyed. The module |
| 59 | * may associate data with each device and each node (station). Both |
| 60 | * sets of storage are opaque except for the size of the per-node storage |
| 61 | * which must be provided when the module is attached. |
| 62 | * |
| 63 | * The rate control module is notified for each state transition and |
| 64 | * station association/reassociation. Otherwise it is queried for a |
| 65 | * rate for each outgoing frame and provided status from each transmitted |
| 66 | * frame. Any ancillary processing is the responsibility of the module |
| 67 | * (e.g. if periodic processing is required then the module should setup |
| 68 | * its own timer). |
| 69 | * |
| 70 | * In addition to the transmit rate for each frame the module must also |
| 71 | * indicate the number of attempts to make at the specified rate. If this |
| 72 | * number is != ATH_TXMAXTRY then an additional callback is made to setup |
| 73 | * additional transmit state. The rate control code is assumed to write |
| 74 | * this additional data directly to the transmit descriptor. |
| 75 | */ |
| 76 | struct ath_softc; |
| 77 | struct ath_node; |
| 78 | struct ath_desc; |
| 79 | |
| 80 | struct ath_ratectrl { |
| 81 | size_t arc_space; /* space required for per-node state */ |
| 82 | }; |
| 83 | /* |
| 84 | * Attach/detach a rate control module. |
| 85 | */ |
| 86 | struct ath_ratectrl *ath_rate_attach(struct ath_softc *); |
| 87 | void ath_rate_detach(struct ath_ratectrl *); |
| 88 | |
| 89 | |
| 90 | /* |
| 91 | * State storage handling. |
| 92 | */ |
| 93 | /* |
| 94 | * Initialize per-node state already allocated for the specified |
| 95 | * node; this space can be assumed initialized to zero. |
| 96 | */ |
| 97 | void ath_rate_node_init(struct ath_softc *, struct ath_node *); |
| 98 | /* |
| 99 | * Cleanup any per-node state prior to the node being reclaimed. |
| 100 | */ |
| 101 | void ath_rate_node_cleanup(struct ath_softc *, struct ath_node *); |
| 102 | /* |
| 103 | * Update rate control state on station associate/reassociate |
| 104 | * (when operating as an ap or for nodes discovered when operating |
| 105 | * in ibss mode). |
| 106 | */ |
| 107 | void ath_rate_newassoc(struct ath_softc *, struct ath_node *, |
| 108 | int isNewAssociation); |
| 109 | /* |
| 110 | * Update/reset rate control state for 802.11 state transitions. |
| 111 | * Important mostly as the analog to ath_rate_newassoc when operating |
| 112 | * in station mode. |
| 113 | */ |
| 114 | void ath_rate_newstate(struct ath_softc *, enum ieee80211_state); |
| 115 | |
| 116 | /* |
| 117 | * Transmit handling. |
| 118 | */ |
| 119 | /* |
| 120 | * Return the transmit info for a data packet. If multi-rate state |
| 121 | * is to be setup then try0 should contain a value other than ATH_TXMATRY |
| 122 | * and ath_rate_setupxtxdesc will be called after deciding if the frame |
| 123 | * can be transmitted with multi-rate retry. |
| 124 | */ |
| 125 | void ath_rate_findrate(struct ath_softc *, struct ath_node *, |
| 126 | int shortPreamble, size_t frameLen, |
| 127 | u_int8_t *rix, int *try0, u_int8_t *txrate); |
| 128 | /* |
| 129 | * Setup any extended (multi-rate) descriptor state for a data packet. |
| 130 | * The rate index returned by ath_rate_findrate is passed back in. |
| 131 | */ |
| 132 | void ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *, |
| 133 | struct ath_desc *, int shortPreamble, u_int8_t rix); |
| 134 | /* |
| 135 | * Update rate control state for a packet associated with the |
| 136 | * supplied transmit descriptor. The routine is invoked both |
| 137 | * for packets that were successfully sent and for those that |
| 138 | * failed (consult the descriptor for details). |
| 139 | */ |
| 140 | void ath_rate_tx_complete(struct ath_softc *, struct ath_node *, |
| 141 | const struct ath_desc *last, const struct ath_desc *first); |
| 142 | #endif /* _ATH_RATECTRL_H_ */ |
| 143 | |