Lines Matching +full:input +full:- +full:clock
1 Modelling a clock tree in QEMU
5 ----------------
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
21 In these cases a Clock object is a child of a Device object, but this
23 example it is possible to create a clock outside of any device to
24 model the main clock source of a machine.
28 +---------+ +----------------------+ +--------------+
29 | Clock 1 | | Device B | | Device C |
30 | | | +-------+ +-------+ | | +-------+ |
31 | |>>-+-->>|Clock 2| |Clock 3|>>--->>|Clock 6| |
32 +---------+ | | | (in) | | (out) | | | | (in) | |
33 | | +-------+ +-------+ | | +-------+ |
34 | | +-------+ | +--------------+
35 | | |Clock 4|>>
36 | | | (out) | | +--------------+
37 | | +-------+ | | Device D |
38 | | +-------+ | | +-------+ |
39 | | |Clock 5|>>--->>|Clock 7| |
41 | | +-------+ | | +-------+ |
42 | +----------------------+ | |
43 | | +-------+ |
44 +----------------------------->>|Clock 8| |
46 | +-------+ |
47 +--------------+
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``
53 The clock state
54 ---------------
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
63 the current period of a clock to be fetched at any time. When a clock
68 every clock state setter or getter. The suffixes are:
70 - ``_ns`` for handling periods in nanoseconds
71 - ``_hz`` for handling frequencies in hertz
74 that the clock is disabled.
76 Adding a new clock
77 ------------------
82 To add an input clock to a device, the function ``qdev_init_clock_in()``
91 Both functions return the created Clock pointer, which should be saved in the
96 Note that it is possible to create a static array describing clock inputs and
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``.
101 As an example, the following creates 2 clocks to a device: one input and one
104 .. code-block:: c
106 /* device structure containing pointers to the clock objects */
109 Clock *clk_in;
110 Clock *clk_out;
114 * callback for the input clock (see "Callback on input clock
121 * + a clock input named "clk_in", whose pointer is stored in
124 * + a clock output named "clk_out" whose pointer is stored in
143 An alternative way to create a clock is to simply call
144 ``object_new(TYPE_CLOCK)``. In that case the clock will neither be an
145 input nor an output of a device. After the whole QOM hierarchy of the
146 clock has been set ``clock_setup_canonical_path()`` should be called.
148 At creation, the period of the clock is 0: the clock is disabled. You can
151 Note that if you are creating a clock with a fixed period which will never
152 change (for example the main clock source of a board), then you'll have
157 Clock callbacks
158 ---------------
160 You can give a clock a callback function in several ways:
169 .. code-block:: c
184 * ``ClockPreUpdate`` : called when the input clock's period is about to
186 which it needs to know the old value of the clock period. During
187 this callback, Clock API functions like ``clock_get()`` or
189 * ``ClockUpdate`` : called after the input clock's period has changed.
190 During this callback, Clock API functions like ``clock_ticks_to_ns()``
193 Note that a clock only has one callback: it is not possible to register
199 -------------------------------
202 get the clock inputs or outputs of a device. For example:
204 .. code-block:: c
206 Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in");
210 .. code-block:: c
212 Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out");
215 ------------------------------
222 When connecting clock between devices, prefer using the
223 ``qdev_connect_clock_in()`` function to set the source of an input
224 device clock. For example, to connect the input clock ``clk2`` of
225 ``devB`` to the output clock ``clk1`` of ``devA``, do:
227 .. code-block:: c
231 We used ``qdev_get_clock_out()`` above, but any clock can drive an
232 input clock, even another input clock. The following diagram shows
233 some examples of connections. Note also that a clock can drive several
238 +------------+ +--------------------------------------------------+
240 | | | +---------------------+ |
242 | +-------+ | | +-------+ | +-------+ +-------+ | +-------+ |
243 | |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
245 | +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ |
246 +------------+ | | +---------------------+ |
248 | | +--------------+ |
250 | | | +-------+ | |
251 | +-->>|Clock 4| | |
253 | | +-------+ | |
254 | +--------------+ |
255 +--------------------------------------------------+
257 In the above example, when *Clock 1* is updated by *Device A*, three
258 clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*.
260 It is not possible to disconnect a clock or to change the clock connection
263 Clock multiplier and divider settings
264 -------------------------------------
267 clocks run with the same period as their source (parent) clock.
268 The Clock API supports a built-in period multiplier/divider
269 mechanism so you can configure a clock to make its children
271 ``clock_set_mul_div()`` function you can specify the clock's
272 multiplier and divider values. The children of that clock
274 For instance, if the clock has a frequency of 8MHz and you set its
278 You can change the multiplier and divider of a clock at runtime,
279 so you can use this to model clock controller devices which
280 have guest-programmable frequency multipliers or dividers.
283 the clock state was modified; that is, if the multiplier or the diviser
290 Unconnected input clocks
291 ------------------------
293 A newly created input clock is disabled (period of 0). This means the
294 clock will be considered as disabled until the period is updated. If
295 the clock remains unconnected it will always keep its initial value
297 ``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock
300 .. code-block:: c
302 clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
307 To enforce that the clock is wired up by the board code, you can
310 .. code-block:: c
312 if (!clock_has_source(s->clk)) {
313 error_setg(errp, "MyDevice: clk input must be connected");
317 Note that this only checks that the clock has been wired up; it is
318 still possible that the output clock connected to it is disabled
320 zero. You should use the clock callback to find out when the clock
323 Fetching clock frequency/period
324 -------------------------------
326 To get the current state of a clock, use the functions ``clock_get()``
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
331 2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
334 ``clock_get_hz()`` returns the frequency of the clock, rounded to the
338 It is also possible to register a callback on clock frequency changes.
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".
361 It's also possible to retrieve the clock period from a QTest by
362 accessing QOM property ``qtest-clock-period`` using a QMP command.
368 ----------------------------
370 A commonly required operation for a clock is to calculate how long
371 it will take for the clock to tick N times; this can then be used
373 which takes an unsigned 64-bit count of ticks and returns the length
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
382 For a clock with a very long period and a large number of ticks,
384 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
386 input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost
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
402 potential rounding errors. It will return '0' if the clock is stopped
404 overflows a 64-bit value (a very long duration for a clock with a
406 the 64-bit output wraps around.
408 Changing a clock period
409 -----------------------
413 updates on every connected input.
415 For example, let's say that we have an output clock *clkout* and we
419 .. code-block:: c
421 dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
424 change the clock value by doing:
426 .. code-block:: c
428 clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
430 Because updating a clock may trigger any side effects through
442 ``clock_propagate()`` on the clock. Thus, setting the clock value can
443 be separated from triggering the side-effects. This is often required
447 ---------------
449 Sometimes, one needs to forward, or inherit, a clock from another
451 expose a sub-device's clock without interfering with it. The function
453 that it is possible to expose the clock under a different name.
454 ``qdev_alias_clock()`` works for both input and output clocks.
459 .. code-block:: c
469 * Now A has a clock "b_clk" which is an alias to
470 * the clock "clk" of its child B.
474 This function does not return any clock object. The new clock has the
475 same direction (input or output) as the original one. This function
476 only adds a link to the existing clock. In the above example, object B
477 remains the only object allowed to use the clock and device A must not
478 try to change the clock period or set a callback to the clock. This
479 diagram describes the example with an input clock::
481 +--------------------------+
483 | +--------------+ |
485 | | +-------+ | |
488 | | +-------+ | |
489 | +--------------+ |
490 +--------------------------+
493 ---------
495 Clock state is not migrated automatically. Every device must handle its
496 clock migration. Alias clocks must not be migrated.
498 To ensure clock states are restored correctly during migration, there
501 Clock states can be migrated by adding an entry into the device
503 This is typically used to migrate an input clock state. For example:
505 .. code-block:: c
510 Clock *clk;
522 The second solution is to restore the clock state using information already
523 at our disposal. This can be used to restore output clock states using the
527 When adding clock support to an existing device, if you care about
533 the source virtual machine in the migration does not send the clock