if_athrate.h revision 144546 
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: head/sys/dev/ath/if_athrate.h 144546 2005-04-02 18:54:30Z sam $
38 */
39#ifndef _ATH_RATECTRL_H_
40#define _ATH_RATECTRL_H_
41
42/*
43 * Interface definitions for transmit rate control modules for the
44 * Atheros driver.
45 *
46 * A rate control module is responsible for choosing the transmit rate
47 * for each data frame.  Management+control frames are always sent at
48 * a fixed rate.
49 *
50 * Only one module may be present at a time; the driver references
51 * rate control interfaces by symbol name.  If multiple modules are
52 * to be supported we'll need to switch to a registration-based scheme
53 * as is currently done, for example, for authentication modules.
54 *
55 * An instance of the rate control module is attached to each device
56 * at attach time and detached when the device is destroyed.  The module
57 * may associate data with each device and each node (station).  Both
58 * sets of storage are opaque except for the size of the per-node storage
59 * which must be provided when the module is attached.
60 *
61 * The rate control module is notified for each state transition and
62 * station association/reassociation.  Otherwise it is queried for a
63 * rate for each outgoing frame and provided status from each transmitted
64 * frame.  Any ancillary processing is the responsibility of the module
65 * (e.g. if periodic processing is required then the module should setup
66 * it's own timer).
67 *
68 * In addition to the transmit rate for each frame the module must also
69 * indicate the number of attempts to make at the specified rate.  If this
70 * number is != ATH_TXMAXTRY then an additional callback is made to setup
71 * additional transmit state.  The rate control code is assumed to write
72 * this additional data directly to the transmit descriptor.
73 */
74struct ath_softc;
75struct ath_node;
76struct ath_desc;
77
78struct ath_ratectrl {
79	size_t	arc_space;	/* space required for per-node state */
80};
81/*
82 * Attach/detach a rate control module.
83 */
84struct ath_ratectrl *ath_rate_attach(struct ath_softc *);
85void	ath_rate_detach(struct ath_ratectrl *);
86
87
88/*
89 * State storage handling.
90 */
91/*
92 * Initialize per-node state already allocated for the specified
93 * node; this space can be assumed initialized to zero.
94 */
95void	ath_rate_node_init(struct ath_softc *, struct ath_node *);
96/*
97 * Cleanup any per-node state prior to the node being reclaimed.
98 */
99void	ath_rate_node_cleanup(struct ath_softc *, struct ath_node *);
100/*
101 * Update rate control state on station associate/reassociate
102 * (when operating as an ap or for nodes discovered when operating
103 * in ibss mode).
104 */
105void	ath_rate_newassoc(struct ath_softc *, struct ath_node *,
106		int isNewAssociation);
107/*
108 * Update/reset rate control state for 802.11 state transitions.
109 * Important mostly as the analog to ath_rate_newassoc when operating
110 * in station mode.
111 */
112void	ath_rate_newstate(struct ath_softc *, enum ieee80211_state);
113
114/*
115 * Transmit handling.
116 */
117/*
118 * Return the transmit info for a data packet.  If multi-rate state
119 * is to be setup then try0 should contain a value other than ATH_TXMATRY
120 * and ath_rate_setupxtxdesc will be called after deciding if the frame
121 * can be transmitted with multi-rate retry.
122 */
123void	ath_rate_findrate(struct ath_softc *, struct ath_node *,
124		int shortPreamble, size_t frameLen,
125		u_int8_t *rix, int *try0, u_int8_t *txrate);
126/*
127 * Setup any extended (multi-rate) descriptor state for a data packet.
128 * The rate index returned by ath_rate_findrate is passed back in.
129 */
130void	ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *,
131		struct ath_desc *, int shortPreamble, u_int8_t rix);
132/*
133 * Update rate control state for a packet associated with the
134 * supplied transmit descriptor.  The routine is invoked both
135 * for packets that were successfully sent and for those that
136 * failed (consult the descriptor for details).
137 */
138void	ath_rate_tx_complete(struct ath_softc *, struct ath_node *,
139		const struct ath_desc *last, const struct ath_desc *first);
140#endif /* _ATH_RATECTRL_H_ */
141