blob: 04afc13ed82551c87c2e2aa292cc00012da7520d [file] [log] [blame]
Mattias Nissler12446c62007-12-19 01:27:18 +01001/*
2 * Copyright 2007, Mattias Nissler <mattias.nissler@gmx.de>
Stefano Brivioca5fbca2007-12-23 04:40:32 +01003 * Copyright 2007, Stefano Brivio <stefano.brivio@polimi.it>
Mattias Nissler12446c62007-12-19 01:27:18 +01004 *
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
Stefano Brivio1b507e72007-12-23 17:49:00 +010013/* Sampling period for measuring percentage of failed frames in ms. */
14#define RC_PID_INTERVAL 125
Mattias Nissler12446c62007-12-19 01:27:18 +010015
16/* Exponential averaging smoothness (used for I part of PID controller) */
Stefano Briviod4398102007-12-23 04:44:56 +010017#define RC_PID_SMOOTHING_SHIFT 3
18#define RC_PID_SMOOTHING (1 << RC_PID_SMOOTHING_SHIFT)
Mattias Nissler12446c62007-12-19 01:27:18 +010019
20/* Sharpening factor (used for D part of PID controller) */
Stefano Briviod4398102007-12-23 04:44:56 +010021#define RC_PID_SHARPENING_FACTOR 0
22#define RC_PID_SHARPENING_DURATION 0
Mattias Nissler12446c62007-12-19 01:27:18 +010023
24/* Fixed point arithmetic shifting amount. */
Stefano Briviod4398102007-12-23 04:44:56 +010025#define RC_PID_ARITH_SHIFT 8
Mattias Nissler12446c62007-12-19 01:27:18 +010026
27/* Fixed point arithmetic factor. */
Stefano Briviod4398102007-12-23 04:44:56 +010028#define RC_PID_ARITH_FACTOR (1 << RC_PID_ARITH_SHIFT)
Mattias Nissler12446c62007-12-19 01:27:18 +010029
30/* Proportional PID component coefficient. */
Stefano Briviod4398102007-12-23 04:44:56 +010031#define RC_PID_COEFF_P 15
Mattias Nissler12446c62007-12-19 01:27:18 +010032/* Integral PID component coefficient. */
Stefano Briviod4398102007-12-23 04:44:56 +010033#define RC_PID_COEFF_I 9
Mattias Nissler12446c62007-12-19 01:27:18 +010034/* Derivative PID component coefficient. */
Stefano Briviod4398102007-12-23 04:44:56 +010035#define RC_PID_COEFF_D 15
Mattias Nissler12446c62007-12-19 01:27:18 +010036
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 */
Stefano Briviod4398102007-12-23 04:44:56 +010042#define RC_PID_TARGET_PF 14
Mattias Nissler12446c62007-12-19 01:27:18 +010043
44/* Rate behaviour normalization quantity over time. */
Stefano Briviod4398102007-12-23 04:44:56 +010045#define RC_PID_NORM_OFFSET 3
Mattias Nissler12446c62007-12-19 01:27:18 +010046
47/* Push high rates right after loading. */
Stefano Briviod4398102007-12-23 04:44:56 +010048#define RC_PID_FAST_START 0
Mattias Nissler12446c62007-12-19 01:27:18 +010049
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
54enum 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
61union rc_pid_event_data {
62 /* RC_PID_EVENT_TX_STATUS */
63 struct {
64 struct ieee80211_tx_status 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
81struct 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
98struct 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
115struct 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
Stefano Brivioca5fbca2007-12-23 04:40:32 +0100123/**
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 */
Mattias Nissler1946b742007-12-20 13:27:26 +0100146struct 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
Mattias Nissler12446c62007-12-19 01:27:18 +0100160void rate_control_pid_event_tx_status(struct rc_pid_event_buffer *buf,
161 struct ieee80211_tx_status *stat);
162
163void rate_control_pid_event_rate_change(struct rc_pid_event_buffer *buf,
164 int index, int rate);
165
166void rate_control_pid_event_tx_rate(struct rc_pid_event_buffer *buf,
167 int index, int rate);
168
169void 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
173void rate_control_pid_add_sta_debugfs(void *priv, void *priv_sta,
174 struct dentry *dir);
175
176void rate_control_pid_remove_sta_debugfs(void *priv, void *priv_sta);
177
178struct 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 */
232struct 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
247struct 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
Mattias Nissler1946b742007-12-20 13:27:26 +0100263 /* Sharpening factor and duration. */
264 unsigned int sharpen_factor;
Mattias Nissler12446c62007-12-19 01:27:18 +0100265 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;
Mattias Nissler1946b742007-12-20 13:27:26 +0100278
279#ifdef CONFIG_MAC80211_DEBUGFS
280 /* Debugfs entries created for the parameters above. */
281 struct rc_pid_debugfs_entries dentries;
282#endif
Mattias Nissler12446c62007-12-19 01:27:18 +0100283};
284
285#endif /* RC80211_PID_H */