This page describes the PID rate control algorithm for mac80211.

# Overview

This is an implementation of a TX rate control algorithm that uses a PID controller. Given a target failed frames rate, the controller decides about TX rate changes to meet the target failed frames rate.

The controller basically computes the following:

adj = CP * err + CI * err_avg + CD * (err - last_err) * (1 + sharpening)

where values are as described below:

- adj
- adjustment value that is used to switch TX rate (see below)
- err
- current error: target vs. current failed frames percentage
- last_err
- last error
- err_avg
- average (i.e. poor man's integral) of recent errors
- sharpening
- non-zero when fast response is needed (i.e. right after association or no frames sent for a long time), heading to zero over time
- CP
- Proportional coefficient
- CI
- Integral coefficient
- CD
- Derivative coefficient

Once we have the adj value, we map it to a rate by means of a learning algorithm. This algorithm keeps the state of the percentual failed frames difference between rates. The behaviour of the lowest available rate is kept as a reference value, and every time we switch between two rates, we compute the difference between the failed frames each rate exhibited. By doing so, we compare behaviours which different rates exhibited in adjacent timeslices, thus the comparison is minimally affected by external conditions. This difference gets propagated to the whole set of measurements, so that the reference is always the same. Periodically, we normalize this set so that recent events weigh the most. By comparing the adj value with this set, we avoid pejorative switches to lower rates and allow for switches to higher rates if they behaved well.

# Tuning

Currently, rc80211-pid is tunable via debugfs. We will need to switch to cfg80211, so that userspace tools such as iw can conveniently set rate control profiles such as tuning for better reliability, throughput or latency.

The parameters are:

- 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 learned about behaviour of rates, higher means we should trust more the natural ordering of rates)
- fast_start
- if true, push high rates right after initialization