xref: /openbmc/qemu/docs/devel/clocks.rst (revision 0ed93f4c)
1Modelling a clock tree in QEMU
2==============================
3
4What are clocks?
5----------------
6
7Clocks are QOM objects developed for the purpose of modelling the
8distribution of clocks in QEMU.
9
10They allow us to model the clock distribution of a platform and detect
11configuration errors in the clock tree such as badly configured PLL, clock
12source selection or disabled clock.
13
14The object is *Clock* and its QOM name is ``clock`` (in C code, the macro
15``TYPE_CLOCK``).
16
17Clocks are typically used with devices where they are used to model inputs
18and outputs. They are created in a similar way to GPIOs. Inputs and outputs
19of different devices can be connected together.
20
21In these cases a Clock object is a child of a Device object, but this
22is not a requirement. Clocks can be independent of devices. For
23example it is possible to create a clock outside of any device to
24model the main clock source of a machine.
25
26Here 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
49Clocks are defined in the ``include/hw/clock.h`` header and device
50related functions are defined in the ``include/hw/qdev-clock.h``
51header.
52
53The clock state
54---------------
55
56The state of a clock is its period; it is stored as an integer
57representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to
58represent the clock being inactive or gated. The clocks do not model
59the signal itself (pin toggling) or other properties such as the duty
60cycle.
61
62All clocks contain this state: outputs as well as inputs. This allows
63the current period of a clock to be fetched at any time. When a clock
64is updated, the value is immediately propagated to all connected
65clocks in the tree.
66
67To ease interaction with clocks, helpers with a unit suffix are defined for
68every clock state setter or getter. The suffixes are:
69
70- ``_ns`` for handling periods in nanoseconds
71- ``_hz`` for handling frequencies in hertz
72
73The 0 period value is converted to 0 in hertz and vice versa. 0 always means
74that the clock is disabled.
75
76Adding a new clock
77------------------
78
79Adding clocks to a device must be done during the init method of the Device
80instance.
81
82To add an input clock to a device, the function ``qdev_init_clock_in()``
83must be used.  It takes the name, a callback and an opaque parameter
84for the callback (this will be explained in a following section).
85Output 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
90Both functions return the created Clock pointer, which should be saved in the
91device's state structure for further use.
92
93These objects will be automatically deleted by the QOM reference mechanism.
94
95Note that it is possible to create a static array describing clock inputs and
96outputs. The function ``qdev_init_clocks()`` must be called with the array as
97parameter 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
99construction, some macros are defined in ``include/hw/qdev-clock.h``.
100As an example, the following creates 2 clocks to a device: one input and one
101output.
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
142An alternative way to create a clock is to simply call
143``object_new(TYPE_CLOCK)``. In that case the clock will neither be an
144input nor an output of a device. After the whole QOM hierarchy of the
145clock has been set ``clock_setup_canonical_path()`` should be called.
146
147At creation, the period of the clock is 0: the clock is disabled. You can
148change it using ``clock_set_ns()`` or ``clock_set_hz()``.
149
150Note that if you are creating a clock with a fixed period which will never
151change (for example the main clock source of a board), then you'll have
152nothing else to do. This value will be propagated to other clocks when
153connecting the clocks together and devices will fetch the right value during
154the first reset.
155
156Retrieving clocks from a device
157-------------------------------
158
159``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to
160get 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
166or:
167
168.. code-block:: c
169
170   Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out");
171
172Connecting two clocks together
173------------------------------
174
175To connect two clocks together, use the ``clock_set_source()`` function.
176Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);``
177configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1``
178is updated, ``clk2`` will be updated too.
179
180When connecting clock between devices, prefer using the
181``qdev_connect_clock_in()`` function to set the source of an input
182device 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
189We used ``qdev_get_clock_out()`` above, but any clock can drive an
190input clock, even another input clock. The following diagram shows
191some examples of connections. Note also that a clock can drive several
192other 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
215In the above example, when *Clock 1* is updated by *Device A*, three
216clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*.
217
218It is not possible to disconnect a clock or to change the clock connection
219after it is connected.
220
221Unconnected input clocks
222------------------------
223
224A newly created input clock is disabled (period of 0). This means the
225clock will be considered as disabled until the period is updated. If
226the clock remains unconnected it will always keep its initial value
227of 0. If this is not the desired behaviour, ``clock_set()``,
228``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock
229object 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
238Fetching clock frequency/period
239-------------------------------
240
241To get the current state of a clock, use the functions ``clock_get()``,
242``clock_get_ns()`` or ``clock_get_hz()``.
243
244It is also possible to register a callback on clock frequency changes.
245Here 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
261Changing a clock period
262-----------------------
263
264A device can change its outputs using the ``clock_update()``,
265``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger
266updates on every connected input.
267
268For example, let's say that we have an output clock *clkout* and we
269have a pointer to it in the device state because we did the following
270in init phase:
271
272.. code-block:: c
273
274   dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
275
276Then at any time (apart from the cases listed below), it is possible to
277change the clock value by doing:
278
279.. code-block:: c
280
281   clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
282
283Because updating a clock may trigger any side effects through
284connected clocks and their callbacks, this operation must be done
285while holding the qemu io lock.
286
287For the same reason, one can update clocks only when it is allowed to have
288side effects on other objects. In consequence, it is forbidden:
289
290* during migration,
291* and in the enter phase of reset.
292
293Note 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
296be separated from triggering the side-effects. This is often required
297to factorize code to handle reset and migration in devices.
298
299Aliasing clocks
300---------------
301
302Sometimes, one needs to forward, or inherit, a clock from another
303device.  Typically, when doing device composition, a device might
304expose a sub-device's clock without interfering with it.  The function
305``qdev_alias_clock()`` can be used to achieve this behaviour. Note
306that it is possible to expose the clock under a different name.
307``qdev_alias_clock()`` works for both input and output clocks.
308
309For 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
327This function does not return any clock object. The new clock has the
328same direction (input or output) as the original one. This function
329only adds a link to the existing clock. In the above example, object B
330remains the only object allowed to use the clock and device A must not
331try to change the clock period or set a callback to the clock. This
332diagram 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
345Migration
346---------
347
348Clock state is not migrated automatically. Every device must handle its
349clock migration. Alias clocks must not be migrated.
350
351To ensure clock states are restored correctly during migration, there
352are two solutions.
353
354Clock states can be migrated by adding an entry into the device
355vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
356This 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
375The second solution is to restore the clock state using information already
376at our disposal. This can be used to restore output clock states using the
377device state. The functions ``clock_set[_ns|_hz]()`` can be used during the
378``post_load()`` migration callback.
379
380When adding clock support to an existing device, if you care about
381migration compatibility you will need to be careful, as simply adding
382a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can
383put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a
384suitable ``needed`` function, and use ``clock_set()`` in a
385``pre_load()`` function to set the default value that will be used if
386the source virtual machine in the migration does not send the clock
387state.
388
389Care should be taken not to use ``clock_update[_ns|_hz]()`` or
390``clock_propagate()`` during the whole migration procedure because it
391will trigger side effects to other devices in an unknown state.
392