docs/devel/clocks.rst

1 Modelling a clock tree in QEMU
8 distribution of clocks in QEMU.
11 configuration errors in the clock tree such as badly configured PLL, clock
14 The object is *Clock* and its QOM name is ``clock`` (in C code, the macro
18 and outputs. They are created in a similar way to GPIOs. Inputs and outputs
32     +---------+   |  | | (in)  |  | (out) | |   | | (in)  |    |
40                   |  |            | (out) | |   | | (in)  |    |
45                                                 | | (in)  |    |
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``
57 representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to
65 clocks in the tree.
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
85 called (this will be explained in a following section).
91 Both functions return the created Clock pointer, which should be saved in the
99 ``qdev_init_clock_in/out()`` for each clock in the array. To ease the array
100 construction, some macros are defined in ``include/hw/qdev-clock.h``.
121      * + a clock input named "clk_in", whose pointer is stored in
124      * + a clock output named "clk_out" whose pointer is stored in
138         /* create and fill the pointer fields in the MyDeviceState */
160 You can give a clock a callback function in several ways:
179 that you are interested in. The callback will only be called for those
195 callback which listens for all of the events you are interested in,
244   |  | (out) | |  | | (in)  |  |  | | (in)  | | (out) | |  | (out) | |
252                   |               | | (in)  |    |                   |
268 The Clock API supports a built-in period multiplier/divider
302     clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
308 call ``clock_has_source()`` in your device's realize method:
319 or has not yet been configured, in which case the period will be
329 ``clock_get()`` returns the period of the clock in its fully precise
330 internal representation, as an unsigned 64-bit integer in units of
336 so be cautious about using it in calculations.
356 If you are only interested in the frequency for displaying it to
357 humans (for instance in debugging), use ``clock_display_freq()``,
374 of time in nanoseconds required for the clock to tick that many times.
377 shortcut like multiplying a "period of clock in nanoseconds" value
379 whole number of nanoseconds, and the accumulated error in the
383 the result of this function could in theory be too large to fit in
384 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
387 300 years, anything with an expiry later than that is in the "will
394 in those calculations, of course.)
399 For calculations where you need to know the number of ticks in
416 have a pointer to it in the device state because we did the following
417 in init phase:
438 * and in the enter phase of reset.
444 to factorize code to handle reset and migration in devices.
487     |  (in)   | |  (in) |    | |
531 suitable ``needed`` function, and use ``clock_set()`` in a
533 the source virtual machine in the migration does not send the clock
538 will trigger side effects to other devices in an unknown state.