sys/dev/netif/ath/ath/if_athrate.h

   1 /*
   2  * Copyright (c) 2004-2005 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  * 3. Neither the names of the above-listed copyright holders nor the names
  17  *    of any contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * Alternatively, this software may be distributed under the terms of the
  21  * GNU General Public License ("GPL") version 2 as published by the Free
  22  * Software Foundation.
  23  *
  24  * NO WARRANTY
  25  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  * LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY
  28  * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  29  * THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY,
  30  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  32  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  33  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  35  * THE POSSIBILITY OF SUCH DAMAGES.
  36  *
  37  * $FreeBSD: src/sys/dev/ath/if_athrate.h,v 1.4 2005/04/02 18:54:30 sam Exp $
  38  * $DragonFly: src/sys/dev/netif/ath/ath/if_athrate.h,v 1.2 2007/02/22 05:17:09 sephe Exp $
  39  */
  40 #ifndef _ATH_RATECTRL_H_
  41 #define _ATH_RATECTRL_H_
  42
  43 /*
  44  * Interface definitions for transmit rate control modules for the
  45  * Atheros driver.
  46  *
  47  * A rate control module is responsible for choosing the transmit rate
  48  * for each data frame.  Management+control frames are always sent at
  49  * a fixed rate.
  50  *
  51  * Only one module may be present at a time; the driver references
  52  * rate control interfaces by symbol name.  If multiple modules are
  53  * to be supported we'll need to switch to a registration-based scheme
  54  * as is currently done, for example, for authentication modules.
  55  *
  56  * An instance of the rate control module is attached to each device
  57  * at attach time and detached when the device is destroyed.  The module
  58  * may associate data with each device and each node (station).  Both
  59  * sets of storage are opaque except for the size of the per-node storage
  60  * which must be provided when the module is attached.
  61  *
  62  * The rate control module is notified for each state transition and
  63  * station association/reassociation.  Otherwise it is queried for a
  64  * rate for each outgoing frame and provided status from each transmitted
  65  * frame.  Any ancillary processing is the responsibility of the module
  66  * (e.g. if periodic processing is required then the module should setup
  67  * it's own timer).
  68  *
  69  * In addition to the transmit rate for each frame the module must also
  70  * indicate the number of attempts to make at the specified rate.  If this
  71  * number is != ATH_TXMAXTRY then an additional callback is made to setup
  72  * additional transmit state.  The rate control code is assumed to write
  73  * this additional data directly to the transmit descriptor.
  74  */
  75 struct ath_softc;
  76 struct ath_node;
  77 struct ath_desc;
  78
  79 struct ath_ratectrl {
  80         size_t  arc_space;      /* space required for per-node state */
  81 };
  82 /*
  83  * Attach/detach a rate control module.
  84  */
  85 struct ath_ratectrl *ath_rate_attach(struct ath_softc *);
  86 void    ath_rate_stop(struct ath_ratectrl *);
  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                 uint8_t *rix, int *try0, uint8_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, uint8_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 struct ath_buf;
 141 void    ath_rate_tx_complete(struct ath_softc *, struct ath_node *,
 142                 const struct ath_buf *);
 143 #endif /* _ATH_RATECTRL_H_ */