4  * Copyright GreenSocs 2016-2020
11  * See the COPYING file in the top-level directory.
19 #include "qemu/host-utils.h"
22 #define TYPE_CLOCK "clock"
23 OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK)
32     ClockUpdate = 1, /* Clock period has just updated */
33     ClockPreUpdate = 2, /* Clock period is about to update */
39  * clock store a value representing the clock's period in 2^-32ns unit.
41  *  + periods from 2^-32ns up to 4seconds
42  *  + frequency from ~0.25Hz 2e10Ghz
43  * Resolution of frequency representation decreases with frequency:
58  * Clock:
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
65  * @source: source (or parent in clock tree) of the clock
67  * @sibling: structure used to form a clock list
71 struct Clock {  struct
84     /* Ratio of the parent clock to run the child clocks at */
88     /* Clocks are organized in a clock tree */
89     Clock *source;  argument
90     QLIST_HEAD(, Clock) children;
91     QLIST_ENTRY(Clock) sibling;
101     VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
106                                        vmstate_clock, Clock)
110  * @clk: clock
112  * compute the canonical path of the clock (used by log messages)
114 void clock_setup_canonical_path(Clock *clk);
118  * @parent: the clock parent
119  * @name: the clock object name
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
125  * @return the newly created clock
127 Clock *clock_new(Object *parent, const char *name);
131  * @clk: the clock to register the callback into
137  * Register a callback called on every clock update.
138  * Note that a clock has only one callback: you cannot register
141 void clock_set_callback(Clock *clk, ClockCallback *cb,
146  * @clk: the clock.
147  * @src: the source clock
149  * Setup @src as the clock source of @clk. The current @src period
154 void clock_set_source(Clock *clk, Clock *src);
158  * @clk: the clock
160  * Returns true if the clock has a source clock connected to it.
164  * the clock has been connected.
166 static inline bool clock_has_source(const Clock *clk)  in clock_has_source()
168     return clk->source != NULL;  in clock_has_source()
173  * @clk: the clock to initialize.
174  * @value: the clock's value, 0 means unclocked
178  * @return: true if the clock is changed.
180 bool clock_set(Clock *clk, uint64_t value);
182 static inline bool clock_set_hz(Clock *clk, unsigned hz)  in clock_set_hz()
187 static inline bool clock_set_ns(Clock *clk, unsigned ns)  in clock_set_ns()
194  * @clk: the clock
196  * Propagate the clock period that has been previously configured using
198  * It is an error to call this function on a clock which has a source.
202 void clock_propagate(Clock *clk);
206  * @clk: the clock to update.
207  * @value: the new clock's value, 0 means unclocked
213 static inline void clock_update(Clock *clk, uint64_t value)  in clock_update()
220 static inline void clock_update_hz(Clock *clk, unsigned hz)  in clock_update_hz()
225 static inline void clock_update_ns(Clock *clk, unsigned ns)  in clock_update_ns()
232  * @clk: the clk to fetch the clock
236 static inline uint64_t clock_get(const Clock *clk)  in clock_get()
238     return clk->period;  in clock_get()
241 static inline unsigned clock_get_hz(Clock *clk)  in clock_get_hz()
248  * @clk: the clock to query
251  * Returns the length of time in nanoseconds for this clock
252  * to tick @ticks times. Because a clock can have a period
259  * The result could in theory be too large to fit in a 64-bit
260  * value if the number of ticks and the clock period are both
265  * and callers can reasonably not special-case the saturated result.
267 static inline uint64_t clock_ticks_to_ns(const Clock *clk, uint64_t ticks)  in clock_ticks_to_ns()
272      * clk->period is the period in units of 2^-32 ns, so  in clock_ticks_to_ns()
273      * (clk->period * ticks) is the required length of time in those  in clock_ticks_to_ns()
275      * 2^32, which is the same as shifting the 128-bit multiplication  in clock_ticks_to_ns()
278     mulu64(&ns_low, &ns_high, clk->period, ticks);  in clock_ticks_to_ns()
287  * @clk: the clock to query
290  * Returns the number of ticks this clock would make in the given
291  * number of nanoseconds. Because a clock can have a period which
296  * If the clock is stopped (ie it has period zero), returns 0.
298  * For some inputs the result could overflow a 64-bit value (because
299  * the clock's period is short and the duration is long). In these
300  * cases we truncate the result to a 64-bit value. This is on the
302  * a 32-bit or 64-bit guest register value, so wrapping either cannot
305 static inline uint64_t clock_ns_to_ticks(const Clock *clk, uint64_t ns)  in clock_ns_to_ticks()
315     if (clk->period == 0) {  in clock_ns_to_ticks()
319     divu128(&lo, &hi, clk->period);  in clock_ns_to_ticks()
325  * @clk: a clock
327  * @return: true if the clock is running.
329 static inline bool clock_is_enabled(const Clock *clk)  in clock_is_enabled()
335  * clock_display_freq: return human-readable representation of clock frequency
336  * @clk: clock
338  * Return a string which has a human-readable representation of the
339  * clock's frequency, e.g. "33.3 MHz". This is intended for debug
344 char *clock_display_freq(Clock *clk);
348  * @clk: clock
352  * @return: true if the clock is changed.
354  * By default, a Clock's children will all run with the same period
356  * and divider used to derive the child clock frequency.
358  * will run child clocks with a period 2/3 of the parent clock,
359  * so if the parent clock is an 8MHz clock the children will
371 bool clock_set_mul_div(Clock *clk, uint32_t multiplier, uint32_t divider);