Lines Matching +full:ease +full:- +full:of +full:- +full:use
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
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 +---------+ +----------------------+ +--------------+
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 ---------------
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
63 the current period of a clock to be fetched at any time. When a clock
67 To ease interaction with clocks, helpers with a unit suffix are defined for
70 - ``_ns`` for handling periods in nanoseconds
71 - ``_hz`` for handling frequencies in hertz
77 ------------------
79 Adding clocks to a device must be done during the init method of the Device
84 for the callback and a mask of events when the callback should be
92 device's state structure for further use.
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
122 * the clk_in field of a MyDeviceState structure with callback
125 * the clk_out field of a MyDeviceState structure.
145 input nor an output of a device. After the whole QOM hierarchy of the
148 At creation, the period of the clock is 0: the clock is disabled. You can
152 change (for example the main clock source of a board), then you'll have
158 ---------------
167 The callback function must be of this type:
169 .. code-block:: c
178 When you register the callback you specify a mask of ClockEvent values
186 which it needs to know the old value of the clock period. During
188 ``clock_ticks_to_ns()`` will use the old period.
191 will use the new period.
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.
199 -------------------------------
202 get the clock inputs or outputs of a device. For example:
204 .. code-block:: c
210 .. code-block:: c
215 ------------------------------
217 To connect two clocks together, use the ``clock_set_source()`` function.
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
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 +--------------------------------------------------+
264 -------------------------------------
268 The Clock API supports a built-in period multiplier/divider
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
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.
291 ------------------------
293 A newly created input clock is disabled (period of 0). This means the
296 of 0. If this is not the desired behaviour, ``clock_set()``,
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)) {
320 zero. You should use the clock callback to find out when the clock
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
342 .. code-block:: c
352 fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
353 clock_get(dev->my_clk_input));
357 humans (for instance in debugging), use ``clock_display_freq()``,
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.
368 ----------------------------
372 to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``,
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
379 whole number of nanoseconds, and the accumulated error in the
382 For a clock with a very long period and a large number of ticks,
383 the result of this function could in theory be too large to fit in
384 a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
388 never happen" category. Callers of ``clock_ticks_to_ns()`` should
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.
394 in those calculations, of course.)
397 ---------------------
399 For calculations where you need to know the number of ticks in
400 a given duration, use ``clock_ns_to_ticks()``. This function handles
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 */
438 * and in the enter phase of reset.
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
456 For example, if device B is a child of device A,
459 .. code-block:: c
465 /* create object B as child of A */
470 * the clock "clk" of its child B.
477 remains the only object allowed to use the clock and device A must not
481 +--------------------------+
483 | +--------------+ |
485 | | +-------+ | |
488 | | +-------+ | |
489 | +--------------+ |
490 +--------------------------+
493 ---------
502 vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
505 .. code-block:: c
531 suitable ``needed`` function, and use ``clock_set()`` in a
536 Care should be taken not to use ``clock_update[_ns|_hz]()`` or