/* | |

* Copyright 2007, Mattias Nissler <mattias.nissler@gmx.de> | |

* Copyright 2007, Stefano Brivio <stefano.brivio@polimi.it> | |

* | |

* This program is free software; you can redistribute it and/or modify | |

* it under the terms of the GNU General Public License version 2 as | |

* published by the Free Software Foundation. | |

*/ | |

#ifndef RC80211_PID_H | |

#define RC80211_PID_H | |

/* Sampling period for measuring percentage of failed frames in ms. */ | |

#define RC_PID_INTERVAL 125 | |

/* Exponential averaging smoothness (used for I part of PID controller) */ | |

#define RC_PID_SMOOTHING_SHIFT 3 | |

#define RC_PID_SMOOTHING (1 << RC_PID_SMOOTHING_SHIFT) | |

/* Sharpening factor (used for D part of PID controller) */ | |

#define RC_PID_SHARPENING_FACTOR 0 | |

#define RC_PID_SHARPENING_DURATION 0 | |

/* Fixed point arithmetic shifting amount. */ | |

#define RC_PID_ARITH_SHIFT 8 | |

/* Proportional PID component coefficient. */ | |

#define RC_PID_COEFF_P 15 | |

/* Integral PID component coefficient. */ | |

#define RC_PID_COEFF_I 9 | |

/* Derivative PID component coefficient. */ | |

#define RC_PID_COEFF_D 15 | |

/* Target failed frames rate for the PID controller. NB: This effectively gives | |

* maximum failed frames percentage we're willing to accept. If the wireless | |

* link quality is good, the controller will fail to adjust failed frames | |

* percentage to the target. This is intentional. | |

*/ | |

#define RC_PID_TARGET_PF 14 | |

/* Rate behaviour normalization quantity over time. */ | |

#define RC_PID_NORM_OFFSET 3 | |

/* Push high rates right after loading. */ | |

#define RC_PID_FAST_START 0 | |

/* Arithmetic right shift for positive and negative values for ISO C. */ | |

#define RC_PID_DO_ARITH_RIGHT_SHIFT(x, y) \ | |

((x) < 0 ? -((-(x)) >> (y)) : (x) >> (y)) | |

enum rc_pid_event_type { | |

RC_PID_EVENT_TYPE_TX_STATUS, | |

RC_PID_EVENT_TYPE_RATE_CHANGE, | |

RC_PID_EVENT_TYPE_TX_RATE, | |

RC_PID_EVENT_TYPE_PF_SAMPLE, | |

}; | |

union rc_pid_event_data { | |

/* RC_PID_EVENT_TX_STATUS */ | |

struct { | |

u32 flags; | |

struct ieee80211_tx_info tx_status; | |

}; | |

/* RC_PID_EVENT_TYPE_RATE_CHANGE */ | |

/* RC_PID_EVENT_TYPE_TX_RATE */ | |

struct { | |

int index; | |

int rate; | |

}; | |

/* RC_PID_EVENT_TYPE_PF_SAMPLE */ | |

struct { | |

s32 pf_sample; | |

s32 prop_err; | |

s32 int_err; | |

s32 der_err; | |

}; | |

}; | |

struct rc_pid_event { | |

/* The time when the event occurred */ | |

unsigned long timestamp; | |

/* Event ID number */ | |

unsigned int id; | |

/* Type of event */ | |

enum rc_pid_event_type type; | |

/* type specific data */ | |

union rc_pid_event_data data; | |

}; | |

/* Size of the event ring buffer. */ | |

#define RC_PID_EVENT_RING_SIZE 32 | |

struct rc_pid_event_buffer { | |

/* Counter that generates event IDs */ | |

unsigned int ev_count; | |

/* Ring buffer of events */ | |

struct rc_pid_event ring[RC_PID_EVENT_RING_SIZE]; | |

/* Index to the entry in events_buf to be reused */ | |

unsigned int next_entry; | |

/* Lock that guards against concurrent access to this buffer struct */ | |

spinlock_t lock; | |

/* Wait queue for poll/select and blocking I/O */ | |

wait_queue_head_t waitqueue; | |

}; | |

struct rc_pid_events_file_info { | |

/* The event buffer we read */ | |

struct rc_pid_event_buffer *events; | |

/* The entry we have should read next */ | |

unsigned int next_entry; | |

}; | |

/** | |

* struct rc_pid_debugfs_entries - tunable parameters | |

* | |

* Algorithm parameters, tunable via debugfs. | |

* @target: target percentage for failed frames | |

* @sampling_period: error sampling interval in milliseconds | |

* @coeff_p: absolute value of the proportional coefficient | |

* @coeff_i: absolute value of the integral coefficient | |

* @coeff_d: absolute value of the derivative coefficient | |

* @smoothing_shift: absolute value of the integral smoothing factor (i.e. | |

* amount of smoothing introduced by the exponential moving average) | |

* @sharpen_factor: absolute value of the derivative sharpening factor (i.e. | |

* amount of emphasis given to the derivative term after low activity | |

* events) | |

* @sharpen_duration: duration of the sharpening effect after the detected low | |

* activity event, relative to sampling_period | |

* @norm_offset: amount of normalization periodically performed on the learnt | |

* rate behaviour values (lower means we should trust more what we learnt | |

* about behaviour of rates, higher means we should trust more the natural | |

* ordering of rates) | |

*/ | |

struct rc_pid_debugfs_entries { | |

struct dentry *target; | |

struct dentry *sampling_period; | |

struct dentry *coeff_p; | |

struct dentry *coeff_i; | |

struct dentry *coeff_d; | |

struct dentry *smoothing_shift; | |

struct dentry *sharpen_factor; | |

struct dentry *sharpen_duration; | |

struct dentry *norm_offset; | |

}; | |

void rate_control_pid_event_tx_status(struct rc_pid_event_buffer *buf, | |

struct ieee80211_tx_info *stat); | |

void rate_control_pid_event_rate_change(struct rc_pid_event_buffer *buf, | |

int index, int rate); | |

void rate_control_pid_event_tx_rate(struct rc_pid_event_buffer *buf, | |

int index, int rate); | |

void rate_control_pid_event_pf_sample(struct rc_pid_event_buffer *buf, | |

s32 pf_sample, s32 prop_err, | |

s32 int_err, s32 der_err); | |

void rate_control_pid_add_sta_debugfs(void *priv, void *priv_sta, | |

struct dentry *dir); | |

void rate_control_pid_remove_sta_debugfs(void *priv, void *priv_sta); | |

struct rc_pid_sta_info { | |

unsigned long last_change; | |

unsigned long last_sample; | |

u32 tx_num_failed; | |

u32 tx_num_xmit; | |

int txrate_idx; | |

/* Average failed frames percentage error (i.e. actual vs. target | |

* percentage), scaled by RC_PID_SMOOTHING. This value is computed | |

* using using an exponential weighted average technique: | |

* | |

* (RC_PID_SMOOTHING - 1) * err_avg_old + err | |

* err_avg = ------------------------------------------ | |

* RC_PID_SMOOTHING | |

* | |

* where err_avg is the new approximation, err_avg_old the previous one | |

* and err is the error w.r.t. to the current failed frames percentage | |

* sample. Note that the bigger RC_PID_SMOOTHING the more weight is | |

* given to the previous estimate, resulting in smoother behavior (i.e. | |

* corresponding to a longer integration window). | |

* | |

* For computation, we actually don't use the above formula, but this | |

* one: | |

* | |

* err_avg_scaled = err_avg_old_scaled - err_avg_old + err | |

* | |

* where: | |

* err_avg_scaled = err * RC_PID_SMOOTHING | |

* err_avg_old_scaled = err_avg_old * RC_PID_SMOOTHING | |

* | |

* This avoids floating point numbers and the per_failed_old value can | |

* easily be obtained by shifting per_failed_old_scaled right by | |

* RC_PID_SMOOTHING_SHIFT. | |

*/ | |

s32 err_avg_sc; | |

/* Last framed failes percentage sample. */ | |

u32 last_pf; | |

/* Sharpening needed. */ | |

u8 sharp_cnt; | |

#ifdef CONFIG_MAC80211_DEBUGFS | |

/* Event buffer */ | |

struct rc_pid_event_buffer events; | |

/* Events debugfs file entry */ | |

struct dentry *events_entry; | |

#endif | |

}; | |

/* Algorithm parameters. We keep them on a per-algorithm approach, so they can | |

* be tuned individually for each interface. | |

*/ | |

struct rc_pid_rateinfo { | |

/* Map sorted rates to rates in ieee80211_hw_mode. */ | |

int index; | |

/* Map rates in ieee80211_hw_mode to sorted rates. */ | |

int rev_index; | |

/* Did we do any measurement on this rate? */ | |

bool valid; | |

/* Comparison with the lowest rate. */ | |

int diff; | |

}; | |

struct rc_pid_info { | |

/* The failed frames percentage target. */ | |

unsigned int target; | |

/* Rate at which failed frames percentage is sampled in 0.001s. */ | |

unsigned int sampling_period; | |

/* P, I and D coefficients. */ | |

int coeff_p; | |

int coeff_i; | |

int coeff_d; | |

/* Exponential averaging shift. */ | |

unsigned int smoothing_shift; | |

/* Sharpening factor and duration. */ | |

unsigned int sharpen_factor; | |

unsigned int sharpen_duration; | |

/* Normalization offset. */ | |

unsigned int norm_offset; | |

/* Rates information. */ | |

struct rc_pid_rateinfo *rinfo; | |

/* Index of the last used rate. */ | |

int oldrate; | |

#ifdef CONFIG_MAC80211_DEBUGFS | |

/* Debugfs entries created for the parameters above. */ | |

struct rc_pid_debugfs_entries dentries; | |

#endif | |

}; | |

#endif /* RC80211_PID_H */ |