docs/devel/clocks.rst

5 ----------------
28     +---------+      +----------------------+   +--------------+
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|    |
41                   |  |            +-------+ |   | +-------+    |
42                   |  +----------------------+   |              |
43                   |                             | +-------+    |
44                   +----------------------------->>|Clock 8|    |
46                                                 | +-------+    |
47                                                 +--------------+
50 related functions are defined in the ``include/hw/qdev-clock.h``
54 ---------------
57 representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to
70 - ``_ns`` for handling periods in nanoseconds
71 - ``_hz`` for handling frequencies in hertz
77 ------------------
96 Note that it is possible to create a static array describing clock inputs and
97 outputs. The function ``qdev_init_clocks()`` must be called with the array as
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``.
104 .. code-block:: c
120      * static array describing clocks:
158 ---------------
164    array to be passed to ``qdev_init_clocks()``
169 .. code-block:: c
199 -------------------------------
204 .. code-block:: c
210 .. code-block:: c
215 ------------------------------
227 .. code-block:: c
238   +------------+  +--------------------------------------------------+
240   |            |  |               +---------------------+            |
242   |  +-------+ |  | +-------+     | +-------+ +-------+ |  +-------+ |
243   |  |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
245   |  +-------+ |  | +-------+  |  | +-------+ +-------+ |  +-------+ |
246   +------------+  |            |  +---------------------+            |
248                   |            |  +--------------+                   |
250                   |            |  | +-------+    |                   |
251                   |            +-->>|Clock 4|    |                   |
253                   |               | +-------+    |                   |
254                   |               +--------------+                   |
255                   +--------------------------------------------------+
264 -------------------------------------
268 The Clock API supports a built-in period multiplier/divider
280 have guest-programmable frequency multipliers or dividers.
291 ------------------------
300 .. code-block:: c
302     clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
310 .. code-block:: c
312    if (!clock_has_source(s->clk)) {
324 -------------------------------
330 internal representation, as an unsigned 64-bit integer in units of
331 2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
342 .. code-block:: c
352         fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
353                         clock_get(dev->my_clk_input));
358 which returns a prettified string-representation, e.g. "33.3 MHz".
359 The caller must free the string with g_free() after use.
362 accessing QOM property ``qtest-clock-period`` using a QMP command.
363 This property is only present when the device is being run under
368 ----------------------------
373 which takes an unsigned 64-bit count of ticks and returns the length
384 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
389 therefore generally not special-case the possibility of a saturated
390 result but just allow the timer to be set to that far-future value.
397 ---------------------
401 possible non-whole-number-of-nanoseconds periods and avoids
404 overflows a 64-bit value (a very long duration for a clock with a
406 the 64-bit output wraps around.
409 -----------------------
419 .. code-block:: c
421    dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
426 .. code-block:: c
428    clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
443 be separated from triggering the side-effects. This is often required
447 ---------------
451 expose a sub-device's clock without interfering with it.  The function
459 .. code-block:: c
481     +--------------------------+
483     |         +--------------+ |
485     |         | +-------+    | |
488     |         | +-------+    | |
489     |         +--------------+ |
490     +--------------------------+
493 ---------
505 .. code-block:: c