1 Modelling a clock tree in QEMU
2 ==============================
7 Clocks are QOM objects developed for the purpose of modelling the
8 distribution of clocks in QEMU.
10 They allow us to model the clock distribution of a platform and detect
11 configuration errors in the clock tree such as badly configured PLL, clock
12 source selection or disabled clock.
14 The object is *Clock* and its QOM name is ``clock`` (in C code, the macro
17 Clocks are typically used with devices where they are used to model inputs
18 and outputs. They are created in a similar way to GPIOs. Inputs and outputs
19 of different devices can be connected together.
21 In these cases a Clock object is a child of a Device object, but this
22 is not a requirement. Clocks can be independent of devices. For
23 example it is possible to create a clock outside of any device to
24 model the main clock source of a machine.
26 Here is an example of clocks::
28 +---------+ +----------------------+ +--------------+
29 | Clock 1 | | Device B | | Device C |
30 | | | +-------+ +-------+ | | +-------+ |
31 | |>>-+-->>|Clock 2| |Clock 3|>>--->>|Clock 6| |
32 +---------+ | | | (in) | | (out) | | | | (in) | |
33 | | +-------+ +-------+ | | +-------+ |
34 | | +-------+ | +--------------+
36 | | | (out) | | +--------------+
37 | | +-------+ | | Device D |
38 | | +-------+ | | +-------+ |
39 | | |Clock 5|>>--->>|Clock 7| |
40 | | | (out) | | | | (in) | |
41 | | +-------+ | | +-------+ |
42 | +----------------------+ | |
44 +----------------------------->>|Clock 8| |
49 Clocks are defined in the ``include/hw/clock.h`` header and device
50 related functions are defined in the ``include/hw/qdev-clock.h``
56 The state of a clock is its period; it is stored as an integer
57 representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to
58 represent the clock being inactive or gated. The clocks do not model
59 the signal itself (pin toggling) or other properties such as the duty
62 All clocks contain this state: outputs as well as inputs. This allows
63 the current period of a clock to be fetched at any time. When a clock
64 is updated, the value is immediately propagated to all connected
67 To ease interaction with clocks, helpers with a unit suffix are defined for
68 every clock state setter or getter. The suffixes are:
70 - ``_ns`` for handling periods in nanoseconds
71 - ``_hz`` for handling frequencies in hertz
73 The 0 period value is converted to 0 in hertz and vice versa. 0 always means
74 that the clock is disabled.
79 Adding clocks to a device must be done during the init method of the Device
82 To add an input clock to a device, the function ``qdev_init_clock_in()``
83 must be used. It takes the name, a callback and an opaque parameter
84 for the callback (this will be explained in a following section).
85 Output is simpler; only the name is required. Typically::
87 qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev);
88 qdev_init_clock_out(DEVICE(dev), "clk_out");
90 Both functions return the created Clock pointer, which should be saved in the
91 device's state structure for further use.
93 These objects will be automatically deleted by the QOM reference mechanism.
95 Note that it is possible to create a static array describing clock inputs and
96 outputs. The function ``qdev_init_clocks()`` must be called with the array as
97 parameter to initialize the clocks: it has the same behaviour as calling the
98 ``qdev_init_clock_in/out()`` for each clock in the array. To ease the array
99 construction, some macros are defined in ``include/hw/qdev-clock.h``.
100 As an example, the following creates 2 clocks to a device: one input and one
105 /* device structure containing pointers to the clock objects */
106 typedef struct MyDeviceState {
107 DeviceState parent_obj;
113 * callback for the input clock (see "Callback on input clock
114 * change" section below for more information).
116 static void clk_in_callback(void *opaque);
119 * static array describing clocks:
120 * + a clock input named "clk_in", whose pointer is stored in
121 * the clk_in field of a MyDeviceState structure with callback
123 * + a clock output named "clk_out" whose pointer is stored in
124 * the clk_out field of a MyDeviceState structure.
126 static const ClockPortInitArray mydev_clocks = {
127 QDEV_CLOCK_IN(MyDeviceState, clk_in, clk_in_callback),
128 QDEV_CLOCK_OUT(MyDeviceState, clk_out),
132 /* device initialization function */
133 static void mydev_init(Object *obj)
135 /* cast to MyDeviceState */
136 MyDeviceState *mydev = MYDEVICE(obj);
137 /* create and fill the pointer fields in the MyDeviceState */
138 qdev_init_clocks(mydev, mydev_clocks);
142 An alternative way to create a clock is to simply call
143 ``object_new(TYPE_CLOCK)``. In that case the clock will neither be an
144 input nor an output of a device. After the whole QOM hierarchy of the
145 clock has been set ``clock_setup_canonical_path()`` should be called.
147 At creation, the period of the clock is 0: the clock is disabled. You can
148 change it using ``clock_set_ns()`` or ``clock_set_hz()``.
150 Note that if you are creating a clock with a fixed period which will never
151 change (for example the main clock source of a board), then you'll have
152 nothing else to do. This value will be propagated to other clocks when
153 connecting the clocks together and devices will fetch the right value during
156 Retrieving clocks from a device
157 -------------------------------
159 ``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to
160 get the clock inputs or outputs of a device. For example:
164 Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in");
170 Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out");
172 Connecting two clocks together
173 ------------------------------
175 To connect two clocks together, use the ``clock_set_source()`` function.
176 Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);``
177 configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1``
178 is updated, ``clk2`` will be updated too.
180 When connecting clock between devices, prefer using the
181 ``qdev_connect_clock_in()`` function to set the source of an input
182 device clock. For example, to connect the input clock ``clk2`` of
183 ``devB`` to the output clock ``clk1`` of ``devA``, do:
187 qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1"))
189 We used ``qdev_get_clock_out()`` above, but any clock can drive an
190 input clock, even another input clock. The following diagram shows
191 some examples of connections. Note also that a clock can drive several
196 +------------+ +--------------------------------------------------+
197 | Device A | | Device B |
198 | | | +---------------------+ |
200 | +-------+ | | +-------+ | +-------+ +-------+ | +-------+ |
201 | |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
202 | | (out) | | | | (in) | | | | (in) | | (out) | | | (out) | |
203 | +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ |
204 +------------+ | | +---------------------+ |
206 | | +--------------+ |
213 +--------------------------------------------------+
215 In the above example, when *Clock 1* is updated by *Device A*, three
216 clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*.
218 It is not possible to disconnect a clock or to change the clock connection
219 after it is connected.
221 Unconnected input clocks
222 ------------------------
224 A newly created input clock is disabled (period of 0). This means the
225 clock will be considered as disabled until the period is updated. If
226 the clock remains unconnected it will always keep its initial value
227 of 0. If this is not the desired behaviour, ``clock_set()``,
228 ``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock
229 object during device instance init. For example:
233 clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
235 /* set initial value to 10ns / 100MHz */
236 clock_set_ns(clk, 10);
238 To enforce that the clock is wired up by the board code, you can
239 call ``clock_has_source()`` in your device's realize method:
243 if (!clock_has_source(s->clk)) {
244 error_setg(errp, "MyDevice: clk input must be connected");
248 Note that this only checks that the clock has been wired up; it is
249 still possible that the output clock connected to it is disabled
250 or has not yet been configured, in which case the period will be
251 zero. You should use the clock callback to find out when the clock
254 Fetching clock frequency/period
255 -------------------------------
257 To get the current state of a clock, use the functions ``clock_get()``
258 or ``clock_get_hz()``.
260 ``clock_get()`` returns the period of the clock in its fully precise
261 internal representation, as an unsigned 64-bit integer in units of
262 2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
263 be more convenient; see the section below on expiry deadlines.)
265 ``clock_get_hz()`` returns the frequency of the clock, rounded to the
266 next lowest integer. This implies some inaccuracy due to the rounding,
267 so be cautious about using it in calculations.
269 It is also possible to register a callback on clock frequency changes.
274 void clock_callback(void *opaque) {
275 MyDeviceState *s = (MyDeviceState *) opaque;
277 * 'opaque' is the argument passed to qdev_init_clock_in();
278 * usually this will be the device state pointer.
281 /* do something with the new period */
282 fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
283 clock_get(dev->my_clk_input));
286 If you are only interested in the frequency for displaying it to
287 humans (for instance in debugging), use ``clock_display_freq()``,
288 which returns a prettified string-representation, e.g. "33.3 MHz".
289 The caller must free the string with g_free() after use.
291 Calculating expiry deadlines
292 ----------------------------
294 A commonly required operation for a clock is to calculate how long
295 it will take for the clock to tick N times; this can then be used
296 to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``,
297 which takes an unsigned 64-bit count of ticks and returns the length
298 of time in nanoseconds required for the clock to tick that many times.
300 It is important not to try to calculate expiry deadlines using a
301 shortcut like multiplying a "period of clock in nanoseconds" value
302 by the tick count, because clocks can have periods which are not a
303 whole number of nanoseconds, and the accumulated error in the
304 multiplication can be significant.
306 For a clock with a very long period and a large number of ticks,
307 the result of this function could in theory be too large to fit in
308 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
309 saturates the result to INT64_MAX (because this is the largest valid
310 input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost
311 300 years, anything with an expiry later than that is in the "will
312 never happen" category. Callers of ``clock_ticks_to_ns()`` should
313 therefore generally not special-case the possibility of a saturated
314 result but just allow the timer to be set to that far-future value.
315 (If you are performing further calculations on the returned value
316 rather than simply passing it to a QEMUTimer function like
317 ``timer_mod_ns()`` then you should be careful to avoid overflow
318 in those calculations, of course.)
320 Changing a clock period
321 -----------------------
323 A device can change its outputs using the ``clock_update()``,
324 ``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger
325 updates on every connected input.
327 For example, let's say that we have an output clock *clkout* and we
328 have a pointer to it in the device state because we did the following
333 dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
335 Then at any time (apart from the cases listed below), it is possible to
336 change the clock value by doing:
340 clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
342 Because updating a clock may trigger any side effects through
343 connected clocks and their callbacks, this operation must be done
344 while holding the qemu io lock.
346 For the same reason, one can update clocks only when it is allowed to have
347 side effects on other objects. In consequence, it is forbidden:
350 * and in the enter phase of reset.
352 Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling
353 ``clock_set[_ns|_hz]()`` (with the same arguments) then
354 ``clock_propagate()`` on the clock. Thus, setting the clock value can
355 be separated from triggering the side-effects. This is often required
356 to factorize code to handle reset and migration in devices.
361 Sometimes, one needs to forward, or inherit, a clock from another
362 device. Typically, when doing device composition, a device might
363 expose a sub-device's clock without interfering with it. The function
364 ``qdev_alias_clock()`` can be used to achieve this behaviour. Note
365 that it is possible to expose the clock under a different name.
366 ``qdev_alias_clock()`` works for both input and output clocks.
368 For example, if device B is a child of device A,
369 ``device_a_instance_init()`` may do something like this:
373 void device_a_instance_init(Object *obj)
375 AState *A = DEVICE_A(obj);
377 /* create object B as child of A */
379 qdev_alias_clock(B, "clk", A, "b_clk");
381 * Now A has a clock "b_clk" which is an alias to
382 * the clock "clk" of its child B.
386 This function does not return any clock object. The new clock has the
387 same direction (input or output) as the original one. This function
388 only adds a link to the existing clock. In the above example, object B
389 remains the only object allowed to use the clock and device A must not
390 try to change the clock period or set a callback to the clock. This
391 diagram describes the example with an input clock::
393 +--------------------------+
398 >>"b_clk">>>| "clk" | | |
399 | (in) | | (in) | | |
402 +--------------------------+
407 Clock state is not migrated automatically. Every device must handle its
408 clock migration. Alias clocks must not be migrated.
410 To ensure clock states are restored correctly during migration, there
413 Clock states can be migrated by adding an entry into the device
414 vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
415 This is typically used to migrate an input clock state. For example:
420 DeviceState parent_obj;
421 [...] /* some fields */
425 VMStateDescription my_device_vmstate = {
427 .fields = (VMStateField[]) {
428 [...], /* other migrated fields */
429 VMSTATE_CLOCK(clk, MyDeviceState),
430 VMSTATE_END_OF_LIST()
434 The second solution is to restore the clock state using information already
435 at our disposal. This can be used to restore output clock states using the
436 device state. The functions ``clock_set[_ns|_hz]()`` can be used during the
437 ``post_load()`` migration callback.
439 When adding clock support to an existing device, if you care about
440 migration compatibility you will need to be careful, as simply adding
441 a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can
442 put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a
443 suitable ``needed`` function, and use ``clock_set()`` in a
444 ``pre_load()`` function to set the default value that will be used if
445 the source virtual machine in the migration does not send the clock
448 Care should be taken not to use ``clock_update[_ns|_hz]()`` or
449 ``clock_propagate()`` during the whole migration procedure because it
450 will trigger side effects to other devices in an unknown state.