xref: /openbmc/qemu/include/qemu/throttle.h (revision e76f201f)
1 /*
2  * QEMU throttling infrastructure
3  *
4  * Copyright (C) Nodalink, EURL. 2013-2014
5  * Copyright (C) Igalia, S.L. 2015-2016
6  *
7  * Authors:
8  *   Benoît Canet <benoit.canet@nodalink.com>
9  *   Alberto Garcia <berto@igalia.com>
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License as
13  * published by the Free Software Foundation; either version 2 or
14  * (at your option) version 3 of the License.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, see <http://www.gnu.org/licenses/>.
23  */
24 
25 #ifndef THROTTLE_H
26 #define THROTTLE_H
27 
28 #include "qapi/qapi-types-block-core.h"
29 #include "qemu/timer.h"
30 
31 #define THROTTLE_VALUE_MAX 1000000000000000LL
32 
33 typedef enum {
34     THROTTLE_BPS_TOTAL,
35     THROTTLE_BPS_READ,
36     THROTTLE_BPS_WRITE,
37     THROTTLE_OPS_TOTAL,
38     THROTTLE_OPS_READ,
39     THROTTLE_OPS_WRITE,
40     BUCKETS_COUNT,
41 } BucketType;
42 
43 /*
44  * This module implements I/O limits using the leaky bucket
45  * algorithm. The code is independent of the I/O units, but it is
46  * currently used for bytes per second and operations per second.
47  *
48  * Three parameters can be set by the user:
49  *
50  * - avg: the desired I/O limits in units per second.
51  * - max: the limit during bursts, also in units per second.
52  * - burst_length: the maximum length of the burst period, in seconds.
53  *
54  * Here's how it works:
55  *
56  * - The bucket level (number of performed I/O units) is kept in
57  *   bkt.level and leaks at a rate of bkt.avg units per second.
58  *
59  * - The size of the bucket is bkt.max * bkt.burst_length. Once the
60  *   bucket is full no more I/O is performed until the bucket leaks
61  *   again. This is what makes the I/O rate bkt.avg.
62  *
63  * - The bkt.avg rate does not apply until the bucket is full,
64  *   allowing the user to do bursts until then. The I/O limit during
65  *   bursts is bkt.max. To enforce this limit we keep an additional
66  *   bucket in bkt.burst_level that leaks at a rate of bkt.max units
67  *   per second.
68  *
69  * - Because of all of the above, the user can perform I/O at a
70  *   maximum of bkt.max units per second for at most bkt.burst_length
71  *   seconds in a row. After that the bucket will be full and the I/O
72  *   rate will go down to bkt.avg.
73  *
74  * - Since the bucket always leaks at a rate of bkt.avg, this also
75  *   determines how much the user needs to wait before being able to
76  *   do bursts again.
77  */
78 
79 typedef struct LeakyBucket {
80     uint64_t avg;             /* average goal in units per second */
81     uint64_t max;             /* leaky bucket max burst in units */
82     double  level;            /* bucket level in units */
83     double  burst_level;      /* bucket level in units (for computing bursts) */
84     uint64_t burst_length;    /* max length of the burst period, in seconds */
85 } LeakyBucket;
86 
87 /* The following structure is used to configure a ThrottleState
88  * It contains a bit of state: the bucket field of the LeakyBucket structure.
89  * However it allows to keep the code clean and the bucket field is reset to
90  * zero at the right time.
91  */
92 typedef struct ThrottleConfig {
93     LeakyBucket buckets[BUCKETS_COUNT]; /* leaky buckets */
94     uint64_t op_size;         /* size of an operation in bytes */
95 } ThrottleConfig;
96 
97 typedef struct ThrottleState {
98     ThrottleConfig cfg;       /* configuration */
99     int64_t previous_leak;    /* timestamp of the last leak done */
100 } ThrottleState;
101 
102 typedef enum {
103     THROTTLE_READ = 0,
104     THROTTLE_WRITE,
105     THROTTLE_MAX
106 } ThrottleDirection;
107 
108 typedef struct ThrottleTimers {
109     QEMUTimer *timers[THROTTLE_MAX];    /* timers used to do the throttling */
110     QEMUClockType clock_type; /* the clock used */
111 
112     /* Callbacks */
113     QEMUTimerCB *timer_cb[THROTTLE_MAX];
114     void *timer_opaque;
115 } ThrottleTimers;
116 
117 /* operations on single leaky buckets */
118 void throttle_leak_bucket(LeakyBucket *bkt, int64_t delta);
119 
120 int64_t throttle_compute_wait(LeakyBucket *bkt);
121 
122 /* init/destroy cycle */
123 void throttle_init(ThrottleState *ts);
124 
125 void throttle_timers_init(ThrottleTimers *tt,
126                           AioContext *aio_context,
127                           QEMUClockType clock_type,
128                           QEMUTimerCB *read_timer_cb,
129                           QEMUTimerCB *write_timer_cb,
130                           void *timer_opaque);
131 
132 void throttle_timers_destroy(ThrottleTimers *tt);
133 
134 void throttle_timers_detach_aio_context(ThrottleTimers *tt);
135 
136 void throttle_timers_attach_aio_context(ThrottleTimers *tt,
137                                         AioContext *new_context);
138 
139 bool throttle_timers_are_initialized(ThrottleTimers *tt);
140 
141 /* configuration */
142 bool throttle_enabled(ThrottleConfig *cfg);
143 
144 bool throttle_is_valid(ThrottleConfig *cfg, Error **errp);
145 
146 void throttle_config(ThrottleState *ts,
147                      QEMUClockType clock_type,
148                      ThrottleConfig *cfg);
149 
150 void throttle_get_config(ThrottleState *ts, ThrottleConfig *cfg);
151 
152 void throttle_config_init(ThrottleConfig *cfg);
153 
154 /* usage */
155 bool throttle_schedule_timer(ThrottleState *ts,
156                              ThrottleTimers *tt,
157                              ThrottleDirection direction);
158 
159 void throttle_account(ThrottleState *ts, ThrottleDirection direction,
160                       uint64_t size);
161 void throttle_limits_to_config(ThrottleLimits *arg, ThrottleConfig *cfg,
162                                Error **errp);
163 void throttle_config_to_limits(ThrottleConfig *cfg, ThrottleLimits *var);
164 
165 #endif
166