hw/mips/malta: turn off x86 specific features of PIIX4_PM
[qemu/ar7.git] / docs / devel / clocks.rst
blob675fbeb6abea15a01cdefe3065bd7bac9b5e00b5
1 Modelling a clock tree in QEMU
2 ==============================
4 What are clocks?
5 ----------------
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
15 ``TYPE_CLOCK``).
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                   |  |            +-------+ |   +--------------+
35                   |  |            |Clock 4|>>
36                   |  |            | (out) | |   +--------------+
37                   |  |            +-------+ |   |   Device D   |
38                   |  |            +-------+ |   | +-------+    |
39                   |  |            |Clock 5|>>--->>|Clock 7|    |
40                   |  |            | (out) | |   | | (in)  |    |
41                   |  |            +-------+ |   | +-------+    |
42                   |  +----------------------+   |              |
43                   |                             | +-------+    |
44                   +----------------------------->>|Clock 8|    |
45                                                 | | (in)  |    |
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``
51 header.
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
59 the signal itself (pin toggling) or other properties such as the duty
60 cycle.
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
65 clocks in the tree.
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.
76 Adding a new clock
77 ------------------
79 Adding clocks to a device must be done during the init method of the Device
80 instance.
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, an opaque parameter
84 for the callback and a mask of events when the callback should be
85 called (this will be explained in a following section).
86 Output is simpler; only the name is required. Typically::
88     qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev, ClockUpdate);
89     qdev_init_clock_out(DEVICE(dev), "clk_out");
91 Both functions return the created Clock pointer, which should be saved in the
92 device's state structure for further use.
94 These objects will be automatically deleted by the QOM reference mechanism.
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
98 parameter to initialize the clocks: it has the same behaviour as calling 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``.
101 As an example, the following creates 2 clocks to a device: one input and one
102 output.
104 .. code-block:: c
106     /* device structure containing pointers to the clock objects */
107     typedef struct MyDeviceState {
108         DeviceState parent_obj;
109         Clock *clk_in;
110         Clock *clk_out;
111     } MyDeviceState;
113     /*
114      * callback for the input clock (see "Callback on input clock
115      * change" section below for more information).
116      */
117     static void clk_in_callback(void *opaque, ClockEvent event);
119     /*
120      * static array describing clocks:
121      * + a clock input named "clk_in", whose pointer is stored in
122      *   the clk_in field of a MyDeviceState structure with callback
123      *   clk_in_callback.
124      * + a clock output named "clk_out" whose pointer is stored in
125      *   the clk_out field of a MyDeviceState structure.
126      */
127     static const ClockPortInitArray mydev_clocks = {
128         QDEV_CLOCK_IN(MyDeviceState, clk_in, clk_in_callback, ClockUpdate),
129         QDEV_CLOCK_OUT(MyDeviceState, clk_out),
130         QDEV_CLOCK_END
131     };
133     /* device initialization function */
134     static void mydev_init(Object *obj)
135     {
136         /* cast to MyDeviceState */
137         MyDeviceState *mydev = MYDEVICE(obj);
138         /* create and fill the pointer fields in the MyDeviceState */
139         qdev_init_clocks(mydev, mydev_clocks);
140         [...]
141     }
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
149 change it using ``clock_set_ns()`` or ``clock_set_hz()``.
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
153 nothing else to do. This value will be propagated to other clocks when
154 connecting the clocks together and devices will fetch the right value during
155 the first reset.
157 Clock callbacks
158 ---------------
160 You can give a clock a callback function in several ways:
162  * by passing it as an argument to ``qdev_init_clock_in()``
163  * as an argument to the ``QDEV_CLOCK_IN()`` macro initializing an
164    array to be passed to ``qdev_init_clocks()``
165  * by directly calling the ``clock_set_callback()`` function
167 The callback function must be of this type:
169 .. code-block:: c
171    typedef void ClockCallback(void *opaque, ClockEvent event);
173 The ``opaque`` argument is the pointer passed to ``qdev_init_clock_in()``
174 or ``clock_set_callback()``; for ``qdev_init_clocks()`` it is the
175 ``dev`` device pointer.
177 The ``event`` argument specifies why the callback has been called.
178 When you register the callback you specify a mask of ClockEvent values
179 that you are interested in. The callback will only be called for those
180 events.
182 The events currently supported are:
184  * ``ClockPreUpdate`` : called when the input clock's period is about to
185    update. This is useful if the device needs to do some action for
186    which it needs to know the old value of the clock period. During
187    this callback, Clock API functions like ``clock_get()`` or
188    ``clock_ticks_to_ns()`` will use the old period.
189  * ``ClockUpdate`` : called after the input clock's period has changed.
190    During this callback, Clock API functions like ``clock_ticks_to_ns()``
191    will use the new period.
193 Note that a clock only has one callback: it is not possible to register
194 different functions for different events. You must register a single
195 callback which listens for all of the events you are interested in,
196 and use the ``event`` argument to identify which event has happened.
198 Retrieving clocks from a device
199 -------------------------------
201 ``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to
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");
214 Connecting two clocks together
215 ------------------------------
217 To connect two clocks together, use the ``clock_set_source()`` function.
218 Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);``
219 configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1``
220 is updated, ``clk2`` will be updated too.
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
229     qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1"))
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
234 other clocks.
238   +------------+  +--------------------------------------------------+
239   |  Device A  |  |                   Device B                       |
240   |            |  |               +---------------------+            |
241   |            |  |               |       Device C      |            |
242   |  +-------+ |  | +-------+     | +-------+ +-------+ |  +-------+ |
243   |  |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
244   |  | (out) | |  | | (in)  |  |  | | (in)  | | (out) | |  | (out) | |
245   |  +-------+ |  | +-------+  |  | +-------+ +-------+ |  +-------+ |
246   +------------+  |            |  +---------------------+            |
247                   |            |                                     |
248                   |            |  +--------------+                   |
249                   |            |  |   Device D   |                   |
250                   |            |  | +-------+    |                   |
251                   |            +-->>|Clock 4|    |                   |
252                   |               | | (in)  |    |                   |
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
261 after it is connected.
263 Clock multiplier and divider settings
264 -------------------------------------
266 By default, when clocks are connected together, the child
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
270 run at a different period from its own. If you call the
271 ``clock_set_mul_div()`` function you can specify the clock's
272 multiplier and divider values. The children of that clock
273 will all run with a period of ``parent_period * multiplier / divider``.
274 For instance, if the clock has a frequency of 8MHz and you set its
275 multiplier to 2 and its divider to 3, the child clocks will run
276 at 12MHz.
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.
282 Note that ``clock_set_mul_div()`` does not automatically call
283 ``clock_propagate()``. If you make a runtime change to the
284 multiplier or divider you must call clock_propagate() yourself.
286 Unconnected input clocks
287 ------------------------
289 A newly created input clock is disabled (period of 0). This means the
290 clock will be considered as disabled until the period is updated. If
291 the clock remains unconnected it will always keep its initial value
292 of 0. If this is not the desired behaviour, ``clock_set()``,
293 ``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock
294 object during device instance init. For example:
296 .. code-block:: c
298     clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
299                              dev, ClockUpdate);
300     /* set initial value to 10ns / 100MHz */
301     clock_set_ns(clk, 10);
303 To enforce that the clock is wired up by the board code, you can
304 call ``clock_has_source()`` in your device's realize method:
306 .. code-block:: c
308    if (!clock_has_source(s->clk)) {
309        error_setg(errp, "MyDevice: clk input must be connected");
310        return;
311    }
313 Note that this only checks that the clock has been wired up; it is
314 still possible that the output clock connected to it is disabled
315 or has not yet been configured, in which case the period will be
316 zero. You should use the clock callback to find out when the clock
317 period changes.
319 Fetching clock frequency/period
320 -------------------------------
322 To get the current state of a clock, use the functions ``clock_get()``
323 or ``clock_get_hz()``.
325 ``clock_get()`` returns the period of the clock in its fully precise
326 internal representation, as an unsigned 64-bit integer in units of
327 2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
328 be more convenient; see the section below on expiry deadlines.)
330 ``clock_get_hz()`` returns the frequency of the clock, rounded to the
331 next lowest integer. This implies some inaccuracy due to the rounding,
332 so be cautious about using it in calculations.
334 It is also possible to register a callback on clock frequency changes.
335 Here is an example, which assumes that ``clock_callback`` has been
336 specified as the callback for the ``ClockUpdate`` event:
338 .. code-block:: c
340     void clock_callback(void *opaque, ClockEvent event) {
341         MyDeviceState *s = (MyDeviceState *) opaque;
342         /*
343          * 'opaque' is the argument passed to qdev_init_clock_in();
344          * usually this will be the device state pointer.
345          */
347         /* do something with the new period */
348         fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
349                         clock_get(dev->my_clk_input));
350     }
352 If you are only interested in the frequency for displaying it to
353 humans (for instance in debugging), use ``clock_display_freq()``,
354 which returns a prettified string-representation, e.g. "33.3 MHz".
355 The caller must free the string with g_free() after use.
357 Calculating expiry deadlines
358 ----------------------------
360 A commonly required operation for a clock is to calculate how long
361 it will take for the clock to tick N times; this can then be used
362 to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``,
363 which takes an unsigned 64-bit count of ticks and returns the length
364 of time in nanoseconds required for the clock to tick that many times.
366 It is important not to try to calculate expiry deadlines using a
367 shortcut like multiplying a "period of clock in nanoseconds" value
368 by the tick count, because clocks can have periods which are not a
369 whole number of nanoseconds, and the accumulated error in the
370 multiplication can be significant.
372 For a clock with a very long period and a large number of ticks,
373 the result of this function could in theory be too large to fit in
374 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
375 saturates the result to INT64_MAX (because this is the largest valid
376 input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost
377 300 years, anything with an expiry later than that is in the "will
378 never happen" category. Callers of ``clock_ticks_to_ns()`` should
379 therefore generally not special-case the possibility of a saturated
380 result but just allow the timer to be set to that far-future value.
381 (If you are performing further calculations on the returned value
382 rather than simply passing it to a QEMUTimer function like
383 ``timer_mod_ns()`` then you should be careful to avoid overflow
384 in those calculations, of course.)
386 Obtaining tick counts
387 ---------------------
389 For calculations where you need to know the number of ticks in
390 a given duration, use ``clock_ns_to_ticks()``. This function handles
391 possible non-whole-number-of-nanoseconds periods and avoids
392 potential rounding errors. It will return '0' if the clock is stopped
393 (i.e. it has period zero). If the inputs imply a tick count that
394 overflows a 64-bit value (a very long duration for a clock with a
395 very short period) the output value is truncated, so effectively
396 the 64-bit output wraps around.
398 Changing a clock period
399 -----------------------
401 A device can change its outputs using the ``clock_update()``,
402 ``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger
403 updates on every connected input.
405 For example, let's say that we have an output clock *clkout* and we
406 have a pointer to it in the device state because we did the following
407 in init phase:
409 .. code-block:: c
411    dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
413 Then at any time (apart from the cases listed below), it is possible to
414 change the clock value by doing:
416 .. code-block:: c
418    clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
420 Because updating a clock may trigger any side effects through
421 connected clocks and their callbacks, this operation must be done
422 while holding the qemu io lock.
424 For the same reason, one can update clocks only when it is allowed to have
425 side effects on other objects. In consequence, it is forbidden:
427 * during migration,
428 * and in the enter phase of reset.
430 Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling
431 ``clock_set[_ns|_hz]()`` (with the same arguments) then
432 ``clock_propagate()`` on the clock. Thus, setting the clock value can
433 be separated from triggering the side-effects. This is often required
434 to factorize code to handle reset and migration in devices.
436 Aliasing clocks
437 ---------------
439 Sometimes, one needs to forward, or inherit, a clock from another
440 device.  Typically, when doing device composition, a device might
441 expose a sub-device's clock without interfering with it.  The function
442 ``qdev_alias_clock()`` can be used to achieve this behaviour. Note
443 that it is possible to expose the clock under a different name.
444 ``qdev_alias_clock()`` works for both input and output clocks.
446 For example, if device B is a child of device A,
447 ``device_a_instance_init()`` may do something like this:
449 .. code-block:: c
451     void device_a_instance_init(Object *obj)
452     {
453         AState *A = DEVICE_A(obj);
454         BState *B;
455         /* create object B as child of A */
456         [...]
457         qdev_alias_clock(B, "clk", A, "b_clk");
458         /*
459          * Now A has a clock "b_clk" which is an alias to
460          * the clock "clk" of its child B.
461          */
462     }
464 This function does not return any clock object. The new clock has the
465 same direction (input or output) as the original one. This function
466 only adds a link to the existing clock. In the above example, object B
467 remains the only object allowed to use the clock and device A must not
468 try to change the clock period or set a callback to the clock. This
469 diagram describes the example with an input clock::
471     +--------------------------+
472     |        Device A          |
473     |         +--------------+ |
474     |         |   Device B   | |
475     |         | +-------+    | |
476     >>"b_clk">>>| "clk" |    | |
477     |  (in)   | |  (in) |    | |
478     |         | +-------+    | |
479     |         +--------------+ |
480     +--------------------------+
482 Migration
483 ---------
485 Clock state is not migrated automatically. Every device must handle its
486 clock migration. Alias clocks must not be migrated.
488 To ensure clock states are restored correctly during migration, there
489 are two solutions.
491 Clock states can be migrated by adding an entry into the device
492 vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
493 This is typically used to migrate an input clock state. For example:
495 .. code-block:: c
497     MyDeviceState {
498         DeviceState parent_obj;
499         [...] /* some fields */
500         Clock *clk;
501     };
503     VMStateDescription my_device_vmstate = {
504         .name = "my_device",
505         .fields = (VMStateField[]) {
506             [...], /* other migrated fields */
507             VMSTATE_CLOCK(clk, MyDeviceState),
508             VMSTATE_END_OF_LIST()
509         }
510     };
512 The second solution is to restore the clock state using information already
513 at our disposal. This can be used to restore output clock states using the
514 device state. The functions ``clock_set[_ns|_hz]()`` can be used during the
515 ``post_load()`` migration callback.
517 When adding clock support to an existing device, if you care about
518 migration compatibility you will need to be careful, as simply adding
519 a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can
520 put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a
521 suitable ``needed`` function, and use ``clock_set()`` in a
522 ``pre_load()`` function to set the default value that will be used if
523 the source virtual machine in the migration does not send the clock
524 state.
526 Care should be taken not to use ``clock_update[_ns|_hz]()`` or
527 ``clock_propagate()`` during the whole migration procedure because it
528 will trigger side effects to other devices in an unknown state.