mac80211: move TX info into skb->cb
[linux-2.6.git] / net / mac80211 / rc80211_pid.h
1 /*
2  * Copyright 2007, Mattias Nissler <mattias.nissler@gmx.de>
3  * Copyright 2007, Stefano Brivio <stefano.brivio@polimi.it>
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License version 2 as
7  * published by the Free Software Foundation.
8  */
9
10 #ifndef RC80211_PID_H
11 #define RC80211_PID_H
12
13 /* Sampling period for measuring percentage of failed frames in ms. */
14 #define RC_PID_INTERVAL                 125
15
16 /* Exponential averaging smoothness (used for I part of PID controller) */
17 #define RC_PID_SMOOTHING_SHIFT          3
18 #define RC_PID_SMOOTHING                (1 << RC_PID_SMOOTHING_SHIFT)
19
20 /* Sharpening factor (used for D part of PID controller) */
21 #define RC_PID_SHARPENING_FACTOR        0
22 #define RC_PID_SHARPENING_DURATION      0
23
24 /* Fixed point arithmetic shifting amount. */
25 #define RC_PID_ARITH_SHIFT              8
26
27 /* Fixed point arithmetic factor. */
28 #define RC_PID_ARITH_FACTOR             (1 << RC_PID_ARITH_SHIFT)
29
30 /* Proportional PID component coefficient. */
31 #define RC_PID_COEFF_P                  15
32 /* Integral PID component coefficient. */
33 #define RC_PID_COEFF_I                  9
34 /* Derivative PID component coefficient. */
35 #define RC_PID_COEFF_D                  15
36
37 /* Target failed frames rate for the PID controller. NB: This effectively gives
38  * maximum failed frames percentage we're willing to accept. If the wireless
39  * link quality is good, the controller will fail to adjust failed frames
40  * percentage to the target. This is intentional.
41  */
42 #define RC_PID_TARGET_PF                14
43
44 /* Rate behaviour normalization quantity over time. */
45 #define RC_PID_NORM_OFFSET              3
46
47 /* Push high rates right after loading. */
48 #define RC_PID_FAST_START               0
49
50 /* Arithmetic right shift for positive and negative values for ISO C. */
51 #define RC_PID_DO_ARITH_RIGHT_SHIFT(x, y) \
52         (x) < 0 ? -((-(x)) >> (y)) : (x) >> (y)
53
54 enum rc_pid_event_type {
55         RC_PID_EVENT_TYPE_TX_STATUS,
56         RC_PID_EVENT_TYPE_RATE_CHANGE,
57         RC_PID_EVENT_TYPE_TX_RATE,
58         RC_PID_EVENT_TYPE_PF_SAMPLE,
59 };
60
61 union rc_pid_event_data {
62         /* RC_PID_EVENT_TX_STATUS */
63         struct {
64                 struct ieee80211_tx_info tx_status;
65         };
66         /* RC_PID_EVENT_TYPE_RATE_CHANGE */
67         /* RC_PID_EVENT_TYPE_TX_RATE */
68         struct {
69                 int index;
70                 int rate;
71         };
72         /* RC_PID_EVENT_TYPE_PF_SAMPLE */
73         struct {
74                 s32 pf_sample;
75                 s32 prop_err;
76                 s32 int_err;
77                 s32 der_err;
78         };
79 };
80
81 struct rc_pid_event {
82         /* The time when the event occured */
83         unsigned long timestamp;
84
85         /* Event ID number */
86         unsigned int id;
87
88         /* Type of event */
89         enum rc_pid_event_type type;
90
91         /* type specific data */
92         union rc_pid_event_data data;
93 };
94
95 /* Size of the event ring buffer. */
96 #define RC_PID_EVENT_RING_SIZE 32
97
98 struct rc_pid_event_buffer {
99         /* Counter that generates event IDs */
100         unsigned int ev_count;
101
102         /* Ring buffer of events */
103         struct rc_pid_event ring[RC_PID_EVENT_RING_SIZE];
104
105         /* Index to the entry in events_buf to be reused */
106         unsigned int next_entry;
107
108         /* Lock that guards against concurrent access to this buffer struct */
109         spinlock_t lock;
110
111         /* Wait queue for poll/select and blocking I/O */
112         wait_queue_head_t waitqueue;
113 };
114
115 struct rc_pid_events_file_info {
116         /* The event buffer we read */
117         struct rc_pid_event_buffer *events;
118
119         /* The entry we have should read next */
120         unsigned int next_entry;
121 };
122
123 /**
124  * struct rc_pid_debugfs_entries - tunable parameters
125  *
126  * Algorithm parameters, tunable via debugfs.
127  * @dir: the debugfs directory for a specific phy
128  * @target: target percentage for failed frames
129  * @sampling_period: error sampling interval in milliseconds
130  * @coeff_p: absolute value of the proportional coefficient
131  * @coeff_i: absolute value of the integral coefficient
132  * @coeff_d: absolute value of the derivative coefficient
133  * @smoothing_shift: absolute value of the integral smoothing factor (i.e.
134  *      amount of smoothing introduced by the exponential moving average)
135  * @sharpen_factor: absolute value of the derivative sharpening factor (i.e.
136  *      amount of emphasis given to the derivative term after low activity
137  *      events)
138  * @sharpen_duration: duration of the sharpening effect after the detected low
139  *      activity event, relative to sampling_period
140  * @norm_offset: amount of normalization periodically performed on the learnt
141  *      rate behaviour values (lower means we should trust more what we learnt
142  *      about behaviour of rates, higher means we should trust more the natural
143  *      ordering of rates)
144  * @fast_start: if Y, push high rates right after initialization
145  */
146 struct rc_pid_debugfs_entries {
147         struct dentry *dir;
148         struct dentry *target;
149         struct dentry *sampling_period;
150         struct dentry *coeff_p;
151         struct dentry *coeff_i;
152         struct dentry *coeff_d;
153         struct dentry *smoothing_shift;
154         struct dentry *sharpen_factor;
155         struct dentry *sharpen_duration;
156         struct dentry *norm_offset;
157         struct dentry *fast_start;
158 };
159
160 void rate_control_pid_event_tx_status(struct rc_pid_event_buffer *buf,
161                                       struct ieee80211_tx_info *stat);
162
163 void rate_control_pid_event_rate_change(struct rc_pid_event_buffer *buf,
164                                                int index, int rate);
165
166 void rate_control_pid_event_tx_rate(struct rc_pid_event_buffer *buf,
167                                            int index, int rate);
168
169 void rate_control_pid_event_pf_sample(struct rc_pid_event_buffer *buf,
170                                              s32 pf_sample, s32 prop_err,
171                                              s32 int_err, s32 der_err);
172
173 void rate_control_pid_add_sta_debugfs(void *priv, void *priv_sta,
174                                              struct dentry *dir);
175
176 void rate_control_pid_remove_sta_debugfs(void *priv, void *priv_sta);
177
178 struct rc_pid_sta_info {
179         unsigned long last_change;
180         unsigned long last_sample;
181
182         u32 tx_num_failed;
183         u32 tx_num_xmit;
184
185         /* Average failed frames percentage error (i.e. actual vs. target
186          * percentage), scaled by RC_PID_SMOOTHING. This value is computed
187          * using using an exponential weighted average technique:
188          *
189          *           (RC_PID_SMOOTHING - 1) * err_avg_old + err
190          * err_avg = ------------------------------------------
191          *                       RC_PID_SMOOTHING
192          *
193          * where err_avg is the new approximation, err_avg_old the previous one
194          * and err is the error w.r.t. to the current failed frames percentage
195          * sample. Note that the bigger RC_PID_SMOOTHING the more weight is
196          * given to the previous estimate, resulting in smoother behavior (i.e.
197          * corresponding to a longer integration window).
198          *
199          * For computation, we actually don't use the above formula, but this
200          * one:
201          *
202          * err_avg_scaled = err_avg_old_scaled - err_avg_old + err
203          *
204          * where:
205          *      err_avg_scaled = err * RC_PID_SMOOTHING
206          *      err_avg_old_scaled = err_avg_old * RC_PID_SMOOTHING
207          *
208          * This avoids floating point numbers and the per_failed_old value can
209          * easily be obtained by shifting per_failed_old_scaled right by
210          * RC_PID_SMOOTHING_SHIFT.
211          */
212         s32 err_avg_sc;
213
214         /* Last framed failes percentage sample. */
215         u32 last_pf;
216
217         /* Sharpening needed. */
218         u8 sharp_cnt;
219
220 #ifdef CONFIG_MAC80211_DEBUGFS
221         /* Event buffer */
222         struct rc_pid_event_buffer events;
223
224         /* Events debugfs file entry */
225         struct dentry *events_entry;
226 #endif
227 };
228
229 /* Algorithm parameters. We keep them on a per-algorithm approach, so they can
230  * be tuned individually for each interface.
231  */
232 struct rc_pid_rateinfo {
233
234         /* Map sorted rates to rates in ieee80211_hw_mode. */
235         int index;
236
237         /* Map rates in ieee80211_hw_mode to sorted rates. */
238         int rev_index;
239
240         /* Did we do any measurement on this rate? */
241         bool valid;
242
243         /* Comparison with the lowest rate. */
244         int diff;
245 };
246
247 struct rc_pid_info {
248
249         /* The failed frames percentage target. */
250         unsigned int target;
251
252         /* Rate at which failed frames percentage is sampled in 0.001s. */
253         unsigned int sampling_period;
254
255         /* P, I and D coefficients. */
256         int coeff_p;
257         int coeff_i;
258         int coeff_d;
259
260         /* Exponential averaging shift. */
261         unsigned int smoothing_shift;
262
263         /* Sharpening factor and duration. */
264         unsigned int sharpen_factor;
265         unsigned int sharpen_duration;
266
267         /* Normalization offset. */
268         unsigned int norm_offset;
269
270         /* Fast starst parameter. */
271         unsigned int fast_start;
272
273         /* Rates information. */
274         struct rc_pid_rateinfo *rinfo;
275
276         /* Index of the last used rate. */
277         int oldrate;
278
279 #ifdef CONFIG_MAC80211_DEBUGFS
280         /* Debugfs entries created for the parameters above. */
281         struct rc_pid_debugfs_entries dentries;
282 #endif
283 };
284
285 #endif /* RC80211_PID_H */