if_athrate.h revision 247508
1138570Ssam/*-
2178354Ssam * Copyright (c) 2004-2008 Sam Leffler, Errno Consulting
3138570Ssam * Copyright (c) 2004 Video54 Technologies, Inc.
4138570Ssam * All rights reserved.
5138570Ssam *
6138570Ssam * Redistribution and use in source and binary forms, with or without
7138570Ssam * modification, are permitted provided that the following conditions
8138570Ssam * are met:
9138570Ssam * 1. Redistributions of source code must retain the above copyright
10138570Ssam *    notice, this list of conditions and the following disclaimer,
11170375Ssam *    without modification.
12138570Ssam * 2. Redistributions in binary form must reproduce at minimum a disclaimer
13138570Ssam *    similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any
14138570Ssam *    redistribution must be conditioned upon including a substantially
15138570Ssam *    similar Disclaimer requirement for further binary redistribution.
16138570Ssam *
17138570Ssam * NO WARRANTY
18138570Ssam * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19138570Ssam * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20138570Ssam * LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY
21138570Ssam * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
22138570Ssam * THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY,
23138570Ssam * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24138570Ssam * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25138570Ssam * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
26138570Ssam * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27138570Ssam * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
28138570Ssam * THE POSSIBILITY OF SUCH DAMAGES.
29138570Ssam *
30138570Ssam * $FreeBSD: head/sys/dev/ath/if_athrate.h 247508 2013-02-28 23:39:38Z adrian $
31138570Ssam */
32138570Ssam#ifndef _ATH_RATECTRL_H_
33138570Ssam#define _ATH_RATECTRL_H_
34138570Ssam
35138570Ssam/*
36138570Ssam * Interface definitions for transmit rate control modules for the
37138570Ssam * Atheros driver.
38138570Ssam *
39138570Ssam * A rate control module is responsible for choosing the transmit rate
40138570Ssam * for each data frame.  Management+control frames are always sent at
41138570Ssam * a fixed rate.
42138570Ssam *
43138570Ssam * Only one module may be present at a time; the driver references
44138570Ssam * rate control interfaces by symbol name.  If multiple modules are
45138570Ssam * to be supported we'll need to switch to a registration-based scheme
46138570Ssam * as is currently done, for example, for authentication modules.
47138570Ssam *
48138570Ssam * An instance of the rate control module is attached to each device
49138570Ssam * at attach time and detached when the device is destroyed.  The module
50138570Ssam * may associate data with each device and each node (station).  Both
51138570Ssam * sets of storage are opaque except for the size of the per-node storage
52138570Ssam * which must be provided when the module is attached.
53138570Ssam *
54138570Ssam * The rate control module is notified for each state transition and
55138570Ssam * station association/reassociation.  Otherwise it is queried for a
56138570Ssam * rate for each outgoing frame and provided status from each transmitted
57138570Ssam * frame.  Any ancillary processing is the responsibility of the module
58138570Ssam * (e.g. if periodic processing is required then the module should setup
59138570Ssam * it's own timer).
60138570Ssam *
61138570Ssam * In addition to the transmit rate for each frame the module must also
62138570Ssam * indicate the number of attempts to make at the specified rate.  If this
63138570Ssam * number is != ATH_TXMAXTRY then an additional callback is made to setup
64138570Ssam * additional transmit state.  The rate control code is assumed to write
65138570Ssam * this additional data directly to the transmit descriptor.
66138570Ssam */
67138570Ssamstruct ath_softc;
68138570Ssamstruct ath_node;
69138570Ssamstruct ath_desc;
70138570Ssam
71138570Ssamstruct ath_ratectrl {
72138570Ssam	size_t	arc_space;	/* space required for per-node state */
73138570Ssam};
74138570Ssam/*
75138570Ssam * Attach/detach a rate control module.
76138570Ssam */
77138570Ssamstruct ath_ratectrl *ath_rate_attach(struct ath_softc *);
78138570Ssamvoid	ath_rate_detach(struct ath_ratectrl *);
79138570Ssam
80227326Sadrian#define	ATH_RC_NUM		4
81138570Ssam
82227326Sadrian#define	ATH_RC_DS_FLAG		0x01	/* dual-stream rate */
83227326Sadrian#define	ATH_RC_CW40_FLAG	0x02	/* use HT40 */
84227326Sadrian#define	ATH_RC_SGI_FLAG		0x04	/* use short-GI */
85227326Sadrian#define	ATH_RC_HT_FLAG		0x08	/* use HT */
86227326Sadrian#define	ATH_RC_RTSCTS_FLAG	0x10	/* enable RTS/CTS protection */
87247508Sadrian#define	ATH_RC_STBC_FLAG	0x20	/* enable STBC */
88247508Sadrian#define	ATH_RC_LDPC_FLAG	0x40	/* enable STBC */
89227326Sadrian
90227326Sadrianstruct ath_rc_series {
91227326Sadrian	uint8_t rix;		/* ratetable index, not rate code */
92227326Sadrian	uint8_t ratecode;	/* hardware rate code */
93227326Sadrian	uint8_t tries;
94227326Sadrian	uint8_t flags;
95227326Sadrian	uint32_t max4msframelen;
96227326Sadrian};
97227326Sadrian
98138570Ssam/*
99138570Ssam * State storage handling.
100138570Ssam */
101138570Ssam/*
102138570Ssam * Initialize per-node state already allocated for the specified
103138570Ssam * node; this space can be assumed initialized to zero.
104138570Ssam */
105138570Ssamvoid	ath_rate_node_init(struct ath_softc *, struct ath_node *);
106138570Ssam/*
107138570Ssam * Cleanup any per-node state prior to the node being reclaimed.
108138570Ssam */
109138570Ssamvoid	ath_rate_node_cleanup(struct ath_softc *, struct ath_node *);
110138570Ssam/*
111138570Ssam * Update rate control state on station associate/reassociate
112138570Ssam * (when operating as an ap or for nodes discovered when operating
113138570Ssam * in ibss mode).
114138570Ssam */
115138570Ssamvoid	ath_rate_newassoc(struct ath_softc *, struct ath_node *,
116138570Ssam		int isNewAssociation);
117138570Ssam
118138570Ssam/*
119138570Ssam * Transmit handling.
120138570Ssam */
121138570Ssam/*
122218160Sadrian * Return the four TX rate index and try counts for the current data packet.
123218160Sadrian */
124218160Sadrianvoid	ath_rate_getxtxrates(struct ath_softc *sc, struct ath_node *an,
125227364Sadrian		uint8_t rix0, struct ath_rc_series *rc);
126218160Sadrian
127218160Sadrian/*
128138570Ssam * Return the transmit info for a data packet.  If multi-rate state
129138570Ssam * is to be setup then try0 should contain a value other than ATH_TXMATRY
130138570Ssam * and ath_rate_setupxtxdesc will be called after deciding if the frame
131138570Ssam * can be transmitted with multi-rate retry.
132138570Ssam */
133138570Ssamvoid	ath_rate_findrate(struct ath_softc *, struct ath_node *,
134144546Ssam		int shortPreamble, size_t frameLen,
135138570Ssam		u_int8_t *rix, int *try0, u_int8_t *txrate);
136138570Ssam/*
137138570Ssam * Setup any extended (multi-rate) descriptor state for a data packet.
138138570Ssam * The rate index returned by ath_rate_findrate is passed back in.
139138570Ssam */
140138570Ssamvoid	ath_rate_setupxtxdesc(struct ath_softc *, struct ath_node *,
141144546Ssam		struct ath_desc *, int shortPreamble, u_int8_t rix);
142138570Ssam/*
143138570Ssam * Update rate control state for a packet associated with the
144138570Ssam * supplied transmit descriptor.  The routine is invoked both
145138570Ssam * for packets that were successfully sent and for those that
146138570Ssam * failed (consult the descriptor for details).
147227364Sadrian *
148227364Sadrian * For A-MPDU frames, nframes and nbad indicate how many frames
149227364Sadrian * were in the aggregate, and how many failed.
150138570Ssam */
151165185Ssamstruct ath_buf;
152138570Ssamvoid	ath_rate_tx_complete(struct ath_softc *, struct ath_node *,
153227364Sadrian		const struct ath_rc_series *, const struct ath_tx_status *,
154227364Sadrian		int pktlen, int nframes, int nbad);
155238632Sadrian
156238632Sadrian/*
157238632Sadrian * Fetch the global rate control statistics.
158238632Sadrian */
159238632Sadrianint	ath_rate_fetch_stats(struct ath_softc *sc, struct ath_rateioctl *rs);
160238632Sadrian
161238632Sadrian/*
162238632Sadrian * Fetch the per-node statistics.
163238632Sadrian */
164238632Sadrianint	ath_rate_fetch_node_stats(struct ath_softc *sc, struct ath_node *an,
165238632Sadrian		struct ath_rateioctl *rs);
166238632Sadrian
167138570Ssam#endif /* _ATH_RATECTRL_H_ */
168