lib: Add generic exponentially weighted moving average (EWMA) function
[linux-3.10.git] / lib / average.c
1 /*
2  * lib/average.c
3  *
4  * This source code is licensed under the GNU General Public License,
5  * Version 2.  See the file COPYING for more details.
6  */
7
8 #include <linux/module.h>
9 #include <linux/average.h>
10 #include <linux/bug.h>
11
12 /**
13  * DOC: Exponentially Weighted Moving Average (EWMA)
14  *
15  * These are generic functions for calculating Exponentially Weighted Moving
16  * Averages (EWMA). We keep a structure with the EWMA parameters and a scaled
17  * up internal representation of the average value to prevent rounding errors.
18  * The factor for scaling up and the exponential weight (or decay rate) have to
19  * be specified thru the init fuction. The structure should not be accessed
20  * directly but only thru the helper functions.
21  */
22
23 /**
24  * ewma_init() - Initialize EWMA parameters
25  * @avg: Average structure
26  * @factor: Factor to use for the scaled up internal value. The maximum value
27  *      of averages can be ULONG_MAX/(factor*weight).
28  * @weight: Exponential weight, or decay rate. This defines how fast the
29  *      influence of older values decreases. Has to be bigger than 1.
30  *
31  * Initialize the EWMA parameters for a given struct ewma @avg.
32  */
33 void ewma_init(struct ewma *avg, unsigned long factor, unsigned long weight)
34 {
35         WARN_ON(weight <= 1 || factor == 0);
36         avg->internal = 0;
37         avg->weight = weight;
38         avg->factor = factor;
39 }
40 EXPORT_SYMBOL(ewma_init);
41
42 /**
43  * ewma_add() - Exponentially weighted moving average (EWMA)
44  * @avg: Average structure
45  * @val: Current value
46  *
47  * Add a sample to the average.
48  */
49 struct ewma *ewma_add(struct ewma *avg, unsigned long val)
50 {
51         avg->internal = avg->internal  ?
52                 (((avg->internal * (avg->weight - 1)) +
53                         (val * avg->factor)) / avg->weight) :
54                 (val * avg->factor);
55         return avg;
56 }
57 EXPORT_SYMBOL(ewma_add);