stubs: Move qemu_timer_notify_cb() and remove qemu_notify_event() stub
[qemu.git] / docs / devel / clocks.rst
1 Modelling a clock tree in QEMU
2 ==============================
3
4 What are clocks?
5 ----------------
6
7 Clocks are QOM objects developed for the purpose of modelling the
8 distribution of clocks in QEMU.
9
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.
13
14 The object is *Clock* and its QOM name is ``clock`` (in C code, the macro
15 ``TYPE_CLOCK``).
16
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.
20
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.
25
26 Here is an example of clocks::
27
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                                                 +--------------+
48
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.
52
53 The clock state
54 ---------------
55
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.
61
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.
66
67 To ease interaction with clocks, helpers with a unit suffix are defined for
68 every clock state setter or getter. The suffixes are:
69
70 - ``_ns`` for handling periods in nanoseconds
71 - ``_hz`` for handling frequencies in hertz
72
73 The 0 period value is converted to 0 in hertz and vice versa. 0 always means
74 that the clock is disabled.
75
76 Adding a new clock
77 ------------------
78
79 Adding clocks to a device must be done during the init method of the Device
80 instance.
81
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::
86
87     qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev);
88     qdev_init_clock_out(DEVICE(dev), "clk_out");
89
90 Both functions return the created Clock pointer, which should be saved in the
91 device's state structure for further use.
92
93 These objects will be automatically deleted by the QOM reference mechanism.
94
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
101 output.
102
103 .. code-block:: c
104
105     /* device structure containing pointers to the clock objects */
106     typedef struct MyDeviceState {
107         DeviceState parent_obj;
108         Clock *clk_in;
109         Clock *clk_out;
110     } MyDeviceState;
111
112     /*
113      * callback for the input clock (see "Callback on input clock
114      * change" section below for more information).
115      */
116     static void clk_in_callback(void *opaque);
117
118     /*
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
122      *   clk_in_callback.
123      * + a clock output named "clk_out" whose pointer is stored in
124      *   the clk_out field of a MyDeviceState structure.
125      */
126     static const ClockPortInitArray mydev_clocks = {
127         QDEV_CLOCK_IN(MyDeviceState, clk_in, clk_in_callback),
128         QDEV_CLOCK_OUT(MyDeviceState, clk_out),
129         QDEV_CLOCK_END
130     };
131
132     /* device initialization function */
133     static void mydev_init(Object *obj)
134     {
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);
139         [...]
140     }
141
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.
146
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()``.
149
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
154 the first reset.
155
156 Retrieving clocks from a device
157 -------------------------------
158
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:
161
162 .. code-block:: c
163
164    Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in");
165
166 or:
167
168 .. code-block:: c
169
170    Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out");
171
172 Connecting two clocks together
173 ------------------------------
174
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.
179
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:
184
185 .. code-block:: c
186
187     qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1"))
188
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
192 other clocks.
193
194 ::
195
196   +------------+  +--------------------------------------------------+
197   |  Device A  |  |                   Device B                       |
198   |            |  |               +---------------------+            |
199   |            |  |               |       Device C      |            |
200   |  +-------+ |  | +-------+     | +-------+ +-------+ |  +-------+ |
201   |  |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
202   |  | (out) | |  | | (in)  |  |  | | (in)  | | (out) | |  | (out) | |
203   |  +-------+ |  | +-------+  |  | +-------+ +-------+ |  +-------+ |
204   +------------+  |            |  +---------------------+            |
205                   |            |                                     |
206                   |            |  +--------------+                   |
207                   |            |  |   Device D   |                   |
208                   |            |  | +-------+    |                   |
209                   |            +-->>|Clock 4|    |                   |
210                   |               | | (in)  |    |                   |
211                   |               | +-------+    |                   |
212                   |               +--------------+                   |
213                   +--------------------------------------------------+
214
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*.
217
218 It is not possible to disconnect a clock or to change the clock connection
219 after it is connected.
220
221 Unconnected input clocks
222 ------------------------
223
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:
230
231 .. code-block:: c
232
233     clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
234                              dev);
235     /* set initial value to 10ns / 100MHz */
236     clock_set_ns(clk, 10);
237
238 Fetching clock frequency/period
239 -------------------------------
240
241 To get the current state of a clock, use the functions ``clock_get()``,
242 ``clock_get_ns()`` or ``clock_get_hz()``.
243
244 It is also possible to register a callback on clock frequency changes.
245 Here is an example:
246
247 .. code-block:: c
248
249     void clock_callback(void *opaque) {
250         MyDeviceState *s = (MyDeviceState *) opaque;
251         /*
252          * 'opaque' is the argument passed to qdev_init_clock_in();
253          * usually this will be the device state pointer.
254          */
255
256         /* do something with the new period */
257         fprintf(stdout, "device new period is %" PRIu64 "ns\n",
258                         clock_get_ns(dev->my_clk_input));
259     }
260
261 Changing a clock period
262 -----------------------
263
264 A device can change its outputs using the ``clock_update()``,
265 ``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger
266 updates on every connected input.
267
268 For example, let's say that we have an output clock *clkout* and we
269 have a pointer to it in the device state because we did the following
270 in init phase:
271
272 .. code-block:: c
273
274    dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
275
276 Then at any time (apart from the cases listed below), it is possible to
277 change the clock value by doing:
278
279 .. code-block:: c
280
281    clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
282
283 Because updating a clock may trigger any side effects through
284 connected clocks and their callbacks, this operation must be done
285 while holding the qemu io lock.
286
287 For the same reason, one can update clocks only when it is allowed to have
288 side effects on other objects. In consequence, it is forbidden:
289
290 * during migration,
291 * and in the enter phase of reset.
292
293 Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling
294 ``clock_set[_ns|_hz]()`` (with the same arguments) then
295 ``clock_propagate()`` on the clock. Thus, setting the clock value can
296 be separated from triggering the side-effects. This is often required
297 to factorize code to handle reset and migration in devices.
298
299 Aliasing clocks
300 ---------------
301
302 Sometimes, one needs to forward, or inherit, a clock from another
303 device.  Typically, when doing device composition, a device might
304 expose a sub-device's clock without interfering with it.  The function
305 ``qdev_alias_clock()`` can be used to achieve this behaviour. Note
306 that it is possible to expose the clock under a different name.
307 ``qdev_alias_clock()`` works for both input and output clocks.
308
309 For example, if device B is a child of device A,
310 ``device_a_instance_init()`` may do something like this:
311
312 .. code-block:: c
313
314     void device_a_instance_init(Object *obj)
315     {
316         AState *A = DEVICE_A(obj);
317         BState *B;
318         /* create object B as child of A */
319         [...]
320         qdev_alias_clock(B, "clk", A, "b_clk");
321         /*
322          * Now A has a clock "b_clk" which is an alias to
323          * the clock "clk" of its child B.
324          */
325     }
326
327 This function does not return any clock object. The new clock has the
328 same direction (input or output) as the original one. This function
329 only adds a link to the existing clock. In the above example, object B
330 remains the only object allowed to use the clock and device A must not
331 try to change the clock period or set a callback to the clock. This
332 diagram describes the example with an input clock::
333
334     +--------------------------+
335     |        Device A          |
336     |         +--------------+ |
337     |         |   Device B   | |
338     |         | +-------+    | |
339     >>"b_clk">>>| "clk" |    | |
340     |  (in)   | |  (in) |    | |
341     |         | +-------+    | |
342     |         +--------------+ |
343     +--------------------------+
344
345 Migration
346 ---------
347
348 Clock state is not migrated automatically. Every device must handle its
349 clock migration. Alias clocks must not be migrated.
350
351 To ensure clock states are restored correctly during migration, there
352 are two solutions.
353
354 Clock states can be migrated by adding an entry into the device
355 vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
356 This is typically used to migrate an input clock state. For example:
357
358 .. code-block:: c
359
360     MyDeviceState {
361         DeviceState parent_obj;
362         [...] /* some fields */
363         Clock *clk;
364     };
365
366     VMStateDescription my_device_vmstate = {
367         .name = "my_device",
368         .fields = (VMStateField[]) {
369             [...], /* other migrated fields */
370             VMSTATE_CLOCK(clk, MyDeviceState),
371             VMSTATE_END_OF_LIST()
372         }
373     };
374
375 The second solution is to restore the clock state using information already
376 at our disposal. This can be used to restore output clock states using the
377 device state. The functions ``clock_set[_ns|_hz]()`` can be used during the
378 ``post_load()`` migration callback.
379
380 When adding clock support to an existing device, if you care about
381 migration compatibility you will need to be careful, as simply adding
382 a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can
383 put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a
384 suitable ``needed`` function, and use ``clock_set()`` in a
385 ``pre_load()`` function to set the default value that will be used if
386 the source virtual machine in the migration does not send the clock
387 state.
388
389 Care should be taken not to use ``clock_update[_ns|_hz]()`` or
390 ``clock_propagate()`` during the whole migration procedure because it
391 will trigger side effects to other devices in an unknown state.