Merge remote-tracking branch 'remotes/dagrh/tags/pull-virtiofs-20211026' into staging
[qemu.git] / include / hw / clock.h
1 /*
2 * Hardware Clocks
3 *
4 * Copyright GreenSocs 2016-2020
5 *
6 * Authors:
7 * Frederic Konrad
8 * Damien Hedde
9 *
10 * This work is licensed under the terms of the GNU GPL, version 2 or later.
11 * See the COPYING file in the top-level directory.
12 */
13
14 #ifndef QEMU_HW_CLOCK_H
15 #define QEMU_HW_CLOCK_H
16
17 #include "qom/object.h"
18 #include "qemu/queue.h"
19 #include "qemu/host-utils.h"
20 #include "qemu/bitops.h"
21
22 #define TYPE_CLOCK "clock"
23 OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK)
24
25 /*
26 * Argument to ClockCallback functions indicating why the callback
27 * has been called. A mask of these values logically ORed together
28 * is used to specify which events are interesting when the callback
29 * is registered, so these values must all be different bit values.
30 */
31 typedef enum ClockEvent {
32 ClockUpdate = 1, /* Clock period has just updated */
33 ClockPreUpdate = 2, /* Clock period is about to update */
34 } ClockEvent;
35
36 typedef void ClockCallback(void *opaque, ClockEvent event);
37
38 /*
39 * clock store a value representing the clock's period in 2^-32ns unit.
40 * It can represent:
41 * + periods from 2^-32ns up to 4seconds
42 * + frequency from ~0.25Hz 2e10Ghz
43 * Resolution of frequency representation decreases with frequency:
44 * + at 100MHz, resolution is ~2mHz
45 * + at 1Ghz, resolution is ~0.2Hz
46 * + at 10Ghz, resolution is ~20Hz
47 */
48 #define CLOCK_PERIOD_1SEC (1000000000llu << 32)
49
50 /*
51 * macro helpers to convert to hertz / nanosecond
52 */
53 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu))
54 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u)
55 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
56
57 /**
58 * Clock:
59 * @parent_obj: parent class
60 * @period: unsigned integer representing the period of the clock
61 * @canonical_path: clock path string cache (used for trace purpose)
62 * @callback: called when clock changes
63 * @callback_opaque: argument for @callback
64 * @callback_events: mask of events when callback should be called
65 * @source: source (or parent in clock tree) of the clock
66 * @children: list of clocks connected to this one (it is their source)
67 * @sibling: structure used to form a clock list
68 */
69
70
71 struct Clock {
72 /*< private >*/
73 Object parent_obj;
74
75 /* all fields are private and should not be modified directly */
76
77 /* fields */
78 uint64_t period;
79 char *canonical_path;
80 ClockCallback *callback;
81 void *callback_opaque;
82 unsigned int callback_events;
83
84 /* Ratio of the parent clock to run the child clocks at */
85 uint32_t multiplier;
86 uint32_t divider;
87
88 /* Clocks are organized in a clock tree */
89 Clock *source;
90 QLIST_HEAD(, Clock) children;
91 QLIST_ENTRY(Clock) sibling;
92 };
93
94 /*
95 * vmstate description entry to be added in device vmsd.
96 */
97 extern const VMStateDescription vmstate_clock;
98 #define VMSTATE_CLOCK(field, state) \
99 VMSTATE_CLOCK_V(field, state, 0)
100 #define VMSTATE_CLOCK_V(field, state, version) \
101 VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
102 #define VMSTATE_ARRAY_CLOCK(field, state, num) \
103 VMSTATE_ARRAY_CLOCK_V(field, state, num, 0)
104 #define VMSTATE_ARRAY_CLOCK_V(field, state, num, version) \
105 VMSTATE_ARRAY_OF_POINTER_TO_STRUCT(field, state, num, version, \
106 vmstate_clock, Clock)
107
108 /**
109 * clock_setup_canonical_path:
110 * @clk: clock
111 *
112 * compute the canonical path of the clock (used by log messages)
113 */
114 void clock_setup_canonical_path(Clock *clk);
115
116 /**
117 * clock_new:
118 * @parent: the clock parent
119 * @name: the clock object name
120 *
121 * Helper function to create a new clock and parent it to @parent. There is no
122 * need to call clock_setup_canonical_path on the returned clock as it is done
123 * by this function.
124 *
125 * @return the newly created clock
126 */
127 Clock *clock_new(Object *parent, const char *name);
128
129 /**
130 * clock_set_callback:
131 * @clk: the clock to register the callback into
132 * @cb: the callback function
133 * @opaque: the argument to the callback
134 * @events: the events the callback should be called for
135 * (logical OR of ClockEvent enum values)
136 *
137 * Register a callback called on every clock update.
138 * Note that a clock has only one callback: you cannot register
139 * different callback functions for different events.
140 */
141 void clock_set_callback(Clock *clk, ClockCallback *cb,
142 void *opaque, unsigned int events);
143
144 /**
145 * clock_clear_callback:
146 * @clk: the clock to delete the callback from
147 *
148 * Unregister the callback registered with clock_set_callback.
149 */
150 void clock_clear_callback(Clock *clk);
151
152 /**
153 * clock_set_source:
154 * @clk: the clock.
155 * @src: the source clock
156 *
157 * Setup @src as the clock source of @clk. The current @src period
158 * value is also copied to @clk and its subtree but no callback is
159 * called.
160 * Further @src update will be propagated to @clk and its subtree.
161 */
162 void clock_set_source(Clock *clk, Clock *src);
163
164 /**
165 * clock_has_source:
166 * @clk: the clock
167 *
168 * Returns true if the clock has a source clock connected to it.
169 * This is useful for devices which have input clocks which must
170 * be connected by the board/SoC code which creates them. The
171 * device code can use this to check in its realize method that
172 * the clock has been connected.
173 */
174 static inline bool clock_has_source(const Clock *clk)
175 {
176 return clk->source != NULL;
177 }
178
179 /**
180 * clock_set:
181 * @clk: the clock to initialize.
182 * @value: the clock's value, 0 means unclocked
183 *
184 * Set the local cached period value of @clk to @value.
185 *
186 * @return: true if the clock is changed.
187 */
188 bool clock_set(Clock *clk, uint64_t value);
189
190 static inline bool clock_set_hz(Clock *clk, unsigned hz)
191 {
192 return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
193 }
194
195 static inline bool clock_set_ns(Clock *clk, unsigned ns)
196 {
197 return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
198 }
199
200 /**
201 * clock_propagate:
202 * @clk: the clock
203 *
204 * Propagate the clock period that has been previously configured using
205 * @clock_set(). This will update recursively all connected clocks.
206 * It is an error to call this function on a clock which has a source.
207 * Note: this function must not be called during device inititialization
208 * or migration.
209 */
210 void clock_propagate(Clock *clk);
211
212 /**
213 * clock_update:
214 * @clk: the clock to update.
215 * @value: the new clock's value, 0 means unclocked
216 *
217 * Update the @clk to the new @value. All connected clocks will be informed
218 * of this update. This is equivalent to call @clock_set() then
219 * @clock_propagate().
220 */
221 static inline void clock_update(Clock *clk, uint64_t value)
222 {
223 if (clock_set(clk, value)) {
224 clock_propagate(clk);
225 }
226 }
227
228 static inline void clock_update_hz(Clock *clk, unsigned hz)
229 {
230 clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
231 }
232
233 static inline void clock_update_ns(Clock *clk, unsigned ns)
234 {
235 clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
236 }
237
238 /**
239 * clock_get:
240 * @clk: the clk to fetch the clock
241 *
242 * @return: the current period.
243 */
244 static inline uint64_t clock_get(const Clock *clk)
245 {
246 return clk->period;
247 }
248
249 static inline unsigned clock_get_hz(Clock *clk)
250 {
251 return CLOCK_PERIOD_TO_HZ(clock_get(clk));
252 }
253
254 /**
255 * clock_ticks_to_ns:
256 * @clk: the clock to query
257 * @ticks: number of ticks
258 *
259 * Returns the length of time in nanoseconds for this clock
260 * to tick @ticks times. Because a clock can have a period
261 * which is not a whole number of nanoseconds, it is important
262 * to use this function when calculating things like timer
263 * expiry deadlines, rather than attempting to obtain a "period
264 * in nanoseconds" value and then multiplying that by a number
265 * of ticks.
266 *
267 * The result could in theory be too large to fit in a 64-bit
268 * value if the number of ticks and the clock period are both
269 * large; to avoid overflow the result will be saturated to INT64_MAX
270 * (because this is the largest valid input to the QEMUTimer APIs).
271 * Since INT64_MAX nanoseconds is almost 300 years, anything with
272 * an expiry later than that is in the "will never happen" category
273 * and callers can reasonably not special-case the saturated result.
274 */
275 static inline uint64_t clock_ticks_to_ns(const Clock *clk, uint64_t ticks)
276 {
277 uint64_t ns_low, ns_high;
278
279 /*
280 * clk->period is the period in units of 2^-32 ns, so
281 * (clk->period * ticks) is the required length of time in those
282 * units, and we can convert to nanoseconds by multiplying by
283 * 2^32, which is the same as shifting the 128-bit multiplication
284 * result right by 32.
285 */
286 mulu64(&ns_low, &ns_high, clk->period, ticks);
287 if (ns_high & MAKE_64BIT_MASK(31, 33)) {
288 return INT64_MAX;
289 }
290 return ns_low >> 32 | ns_high << 32;
291 }
292
293 /**
294 * clock_ns_to_ticks:
295 * @clk: the clock to query
296 * @ns: duration in nanoseconds
297 *
298 * Returns the number of ticks this clock would make in the given
299 * number of nanoseconds. Because a clock can have a period which
300 * is not a whole number of nanoseconds, it is important to use this
301 * function rather than attempting to obtain a "period in nanoseconds"
302 * value and then dividing the duration by that value.
303 *
304 * If the clock is stopped (ie it has period zero), returns 0.
305 *
306 * For some inputs the result could overflow a 64-bit value (because
307 * the clock's period is short and the duration is long). In these
308 * cases we truncate the result to a 64-bit value. This is on the
309 * assumption that generally the result is going to be used to report
310 * a 32-bit or 64-bit guest register value, so wrapping either cannot
311 * happen or is the desired behaviour.
312 */
313 static inline uint64_t clock_ns_to_ticks(const Clock *clk, uint64_t ns)
314 {
315 /*
316 * ticks = duration_in_ns / period_in_ns
317 * = ns / (period / 2^32)
318 * = (ns * 2^32) / period
319 * The hi, lo inputs to divu128() are (ns << 32) as a 128 bit value.
320 */
321 uint64_t lo = ns << 32;
322 uint64_t hi = ns >> 32;
323 if (clk->period == 0) {
324 return 0;
325 }
326 /*
327 * Ignore divu128() return value as we've caught div-by-zero and don't
328 * need different behaviour for overflow.
329 */
330 divu128(&lo, &hi, clk->period);
331 return lo;
332 }
333
334 /**
335 * clock_is_enabled:
336 * @clk: a clock
337 *
338 * @return: true if the clock is running.
339 */
340 static inline bool clock_is_enabled(const Clock *clk)
341 {
342 return clock_get(clk) != 0;
343 }
344
345 /**
346 * clock_display_freq: return human-readable representation of clock frequency
347 * @clk: clock
348 *
349 * Return a string which has a human-readable representation of the
350 * clock's frequency, e.g. "33.3 MHz". This is intended for debug
351 * and display purposes.
352 *
353 * The caller is responsible for freeing the string with g_free().
354 */
355 char *clock_display_freq(Clock *clk);
356
357 /**
358 * clock_set_mul_div: set multiplier/divider for child clocks
359 * @clk: clock
360 * @multiplier: multiplier value
361 * @divider: divider value
362 *
363 * By default, a Clock's children will all run with the same period
364 * as their parent. This function allows you to adjust the multiplier
365 * and divider used to derive the child clock frequency.
366 * For example, setting a multiplier of 2 and a divider of 3
367 * will run child clocks with a period 2/3 of the parent clock,
368 * so if the parent clock is an 8MHz clock the children will
369 * be 12MHz.
370 *
371 * Setting the multiplier to 0 will stop the child clocks.
372 * Setting the divider to 0 is a programming error (diagnosed with
373 * an assertion failure).
374 * Setting a multiplier value that results in the child period
375 * overflowing is not diagnosed.
376 *
377 * Note that this function does not call clock_propagate(); the
378 * caller should do that if necessary.
379 */
380 void clock_set_mul_div(Clock *clk, uint32_t multiplier, uint32_t divider);
381
382 #endif /* QEMU_HW_CLOCK_H */