xref: /openbmc/qemu/include/hw/clock.h (revision 8fa3b702)
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 
20 #define TYPE_CLOCK "clock"
21 typedef struct Clock Clock;
22 DECLARE_INSTANCE_CHECKER(Clock, CLOCK,
23                          TYPE_CLOCK)
24 
25 typedef void ClockCallback(void *opaque);
26 
27 /*
28  * clock store a value representing the clock's period in 2^-32ns unit.
29  * It can represent:
30  *  + periods from 2^-32ns up to 4seconds
31  *  + frequency from ~0.25Hz 2e10Ghz
32  * Resolution of frequency representation decreases with frequency:
33  * + at 100MHz, resolution is ~2mHz
34  * + at 1Ghz,   resolution is ~0.2Hz
35  * + at 10Ghz,  resolution is ~20Hz
36  */
37 #define CLOCK_PERIOD_1SEC (1000000000llu << 32)
38 
39 /*
40  * macro helpers to convert to hertz / nanosecond
41  */
42 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu))
43 #define CLOCK_PERIOD_TO_NS(per) ((per) / (CLOCK_PERIOD_1SEC / 1000000000llu))
44 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u)
45 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
46 
47 /**
48  * Clock:
49  * @parent_obj: parent class
50  * @period: unsigned integer representing the period of the clock
51  * @canonical_path: clock path string cache (used for trace purpose)
52  * @callback: called when clock changes
53  * @callback_opaque: argument for @callback
54  * @source: source (or parent in clock tree) of the clock
55  * @children: list of clocks connected to this one (it is their source)
56  * @sibling: structure used to form a clock list
57  */
58 
59 
60 struct Clock {
61     /*< private >*/
62     Object parent_obj;
63 
64     /* all fields are private and should not be modified directly */
65 
66     /* fields */
67     uint64_t period;
68     char *canonical_path;
69     ClockCallback *callback;
70     void *callback_opaque;
71 
72     /* Clocks are organized in a clock tree */
73     Clock *source;
74     QLIST_HEAD(, Clock) children;
75     QLIST_ENTRY(Clock) sibling;
76 };
77 
78 /*
79  * vmstate description entry to be added in device vmsd.
80  */
81 extern const VMStateDescription vmstate_clock;
82 #define VMSTATE_CLOCK(field, state) \
83     VMSTATE_CLOCK_V(field, state, 0)
84 #define VMSTATE_CLOCK_V(field, state, version) \
85     VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
86 
87 /**
88  * clock_setup_canonical_path:
89  * @clk: clock
90  *
91  * compute the canonical path of the clock (used by log messages)
92  */
93 void clock_setup_canonical_path(Clock *clk);
94 
95 /**
96  * clock_set_callback:
97  * @clk: the clock to register the callback into
98  * @cb: the callback function
99  * @opaque: the argument to the callback
100  *
101  * Register a callback called on every clock update.
102  */
103 void clock_set_callback(Clock *clk, ClockCallback *cb, void *opaque);
104 
105 /**
106  * clock_clear_callback:
107  * @clk: the clock to delete the callback from
108  *
109  * Unregister the callback registered with clock_set_callback.
110  */
111 void clock_clear_callback(Clock *clk);
112 
113 /**
114  * clock_set_source:
115  * @clk: the clock.
116  * @src: the source clock
117  *
118  * Setup @src as the clock source of @clk. The current @src period
119  * value is also copied to @clk and its subtree but no callback is
120  * called.
121  * Further @src update will be propagated to @clk and its subtree.
122  */
123 void clock_set_source(Clock *clk, Clock *src);
124 
125 /**
126  * clock_set:
127  * @clk: the clock to initialize.
128  * @value: the clock's value, 0 means unclocked
129  *
130  * Set the local cached period value of @clk to @value.
131  *
132  * @return: true if the clock is changed.
133  */
134 bool clock_set(Clock *clk, uint64_t value);
135 
136 static inline bool clock_set_hz(Clock *clk, unsigned hz)
137 {
138     return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
139 }
140 
141 static inline bool clock_set_ns(Clock *clk, unsigned ns)
142 {
143     return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
144 }
145 
146 /**
147  * clock_propagate:
148  * @clk: the clock
149  *
150  * Propagate the clock period that has been previously configured using
151  * @clock_set(). This will update recursively all connected clocks.
152  * It is an error to call this function on a clock which has a source.
153  * Note: this function must not be called during device inititialization
154  * or migration.
155  */
156 void clock_propagate(Clock *clk);
157 
158 /**
159  * clock_update:
160  * @clk: the clock to update.
161  * @value: the new clock's value, 0 means unclocked
162  *
163  * Update the @clk to the new @value. All connected clocks will be informed
164  * of this update. This is equivalent to call @clock_set() then
165  * @clock_propagate().
166  */
167 static inline void clock_update(Clock *clk, uint64_t value)
168 {
169     if (clock_set(clk, value)) {
170         clock_propagate(clk);
171     }
172 }
173 
174 static inline void clock_update_hz(Clock *clk, unsigned hz)
175 {
176     clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
177 }
178 
179 static inline void clock_update_ns(Clock *clk, unsigned ns)
180 {
181     clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
182 }
183 
184 /**
185  * clock_get:
186  * @clk: the clk to fetch the clock
187  *
188  * @return: the current period.
189  */
190 static inline uint64_t clock_get(const Clock *clk)
191 {
192     return clk->period;
193 }
194 
195 static inline unsigned clock_get_hz(Clock *clk)
196 {
197     return CLOCK_PERIOD_TO_HZ(clock_get(clk));
198 }
199 
200 static inline unsigned clock_get_ns(Clock *clk)
201 {
202     return CLOCK_PERIOD_TO_NS(clock_get(clk));
203 }
204 
205 /**
206  * clock_is_enabled:
207  * @clk: a clock
208  *
209  * @return: true if the clock is running.
210  */
211 static inline bool clock_is_enabled(const Clock *clk)
212 {
213     return clock_get(clk) != 0;
214 }
215 
216 #endif /* QEMU_HW_CLOCK_H */
217