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