528 lines
21 KiB
ReStructuredText
528 lines
21 KiB
ReStructuredText
Modelling a clock tree in QEMU
|
|
==============================
|
|
|
|
What are clocks?
|
|
----------------
|
|
|
|
Clocks are QOM objects developed for the purpose of modelling the
|
|
distribution of clocks in QEMU.
|
|
|
|
They allow us to model the clock distribution of a platform and detect
|
|
configuration errors in the clock tree such as badly configured PLL, clock
|
|
source selection or disabled clock.
|
|
|
|
The object is *Clock* and its QOM name is ``clock`` (in C code, the macro
|
|
``TYPE_CLOCK``).
|
|
|
|
Clocks are typically used with devices where they are used to model inputs
|
|
and outputs. They are created in a similar way to GPIOs. Inputs and outputs
|
|
of different devices can be connected together.
|
|
|
|
In these cases a Clock object is a child of a Device object, but this
|
|
is not a requirement. Clocks can be independent of devices. For
|
|
example it is possible to create a clock outside of any device to
|
|
model the main clock source of a machine.
|
|
|
|
Here is an example of clocks::
|
|
|
|
+---------+ +----------------------+ +--------------+
|
|
| Clock 1 | | Device B | | Device C |
|
|
| | | +-------+ +-------+ | | +-------+ |
|
|
| |>>-+-->>|Clock 2| |Clock 3|>>--->>|Clock 6| |
|
|
+---------+ | | | (in) | | (out) | | | | (in) | |
|
|
| | +-------+ +-------+ | | +-------+ |
|
|
| | +-------+ | +--------------+
|
|
| | |Clock 4|>>
|
|
| | | (out) | | +--------------+
|
|
| | +-------+ | | Device D |
|
|
| | +-------+ | | +-------+ |
|
|
| | |Clock 5|>>--->>|Clock 7| |
|
|
| | | (out) | | | | (in) | |
|
|
| | +-------+ | | +-------+ |
|
|
| +----------------------+ | |
|
|
| | +-------+ |
|
|
+----------------------------->>|Clock 8| |
|
|
| | (in) | |
|
|
| +-------+ |
|
|
+--------------+
|
|
|
|
Clocks are defined in the ``include/hw/clock.h`` header and device
|
|
related functions are defined in the ``include/hw/qdev-clock.h``
|
|
header.
|
|
|
|
The clock state
|
|
---------------
|
|
|
|
The state of a clock is its period; it is stored as an integer
|
|
representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to
|
|
represent the clock being inactive or gated. The clocks do not model
|
|
the signal itself (pin toggling) or other properties such as the duty
|
|
cycle.
|
|
|
|
All clocks contain this state: outputs as well as inputs. This allows
|
|
the current period of a clock to be fetched at any time. When a clock
|
|
is updated, the value is immediately propagated to all connected
|
|
clocks in the tree.
|
|
|
|
To ease interaction with clocks, helpers with a unit suffix are defined for
|
|
every clock state setter or getter. The suffixes are:
|
|
|
|
- ``_ns`` for handling periods in nanoseconds
|
|
- ``_hz`` for handling frequencies in hertz
|
|
|
|
The 0 period value is converted to 0 in hertz and vice versa. 0 always means
|
|
that the clock is disabled.
|
|
|
|
Adding a new clock
|
|
------------------
|
|
|
|
Adding clocks to a device must be done during the init method of the Device
|
|
instance.
|
|
|
|
To add an input clock to a device, the function ``qdev_init_clock_in()``
|
|
must be used. It takes the name, a callback, an opaque parameter
|
|
for the callback and a mask of events when the callback should be
|
|
called (this will be explained in a following section).
|
|
Output is simpler; only the name is required. Typically::
|
|
|
|
qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev, ClockUpdate);
|
|
qdev_init_clock_out(DEVICE(dev), "clk_out");
|
|
|
|
Both functions return the created Clock pointer, which should be saved in the
|
|
device's state structure for further use.
|
|
|
|
These objects will be automatically deleted by the QOM reference mechanism.
|
|
|
|
Note that it is possible to create a static array describing clock inputs and
|
|
outputs. The function ``qdev_init_clocks()`` must be called with the array as
|
|
parameter to initialize the clocks: it has the same behaviour as calling the
|
|
``qdev_init_clock_in/out()`` for each clock in the array. To ease the array
|
|
construction, some macros are defined in ``include/hw/qdev-clock.h``.
|
|
As an example, the following creates 2 clocks to a device: one input and one
|
|
output.
|
|
|
|
.. code-block:: c
|
|
|
|
/* device structure containing pointers to the clock objects */
|
|
typedef struct MyDeviceState {
|
|
DeviceState parent_obj;
|
|
Clock *clk_in;
|
|
Clock *clk_out;
|
|
} MyDeviceState;
|
|
|
|
/*
|
|
* callback for the input clock (see "Callback on input clock
|
|
* change" section below for more information).
|
|
*/
|
|
static void clk_in_callback(void *opaque, ClockEvent event);
|
|
|
|
/*
|
|
* static array describing clocks:
|
|
* + a clock input named "clk_in", whose pointer is stored in
|
|
* the clk_in field of a MyDeviceState structure with callback
|
|
* clk_in_callback.
|
|
* + a clock output named "clk_out" whose pointer is stored in
|
|
* the clk_out field of a MyDeviceState structure.
|
|
*/
|
|
static const ClockPortInitArray mydev_clocks = {
|
|
QDEV_CLOCK_IN(MyDeviceState, clk_in, clk_in_callback, ClockUpdate),
|
|
QDEV_CLOCK_OUT(MyDeviceState, clk_out),
|
|
QDEV_CLOCK_END
|
|
};
|
|
|
|
/* device initialization function */
|
|
static void mydev_init(Object *obj)
|
|
{
|
|
/* cast to MyDeviceState */
|
|
MyDeviceState *mydev = MYDEVICE(obj);
|
|
/* create and fill the pointer fields in the MyDeviceState */
|
|
qdev_init_clocks(mydev, mydev_clocks);
|
|
[...]
|
|
}
|
|
|
|
An alternative way to create a clock is to simply call
|
|
``object_new(TYPE_CLOCK)``. In that case the clock will neither be an
|
|
input nor an output of a device. After the whole QOM hierarchy of the
|
|
clock has been set ``clock_setup_canonical_path()`` should be called.
|
|
|
|
At creation, the period of the clock is 0: the clock is disabled. You can
|
|
change it using ``clock_set_ns()`` or ``clock_set_hz()``.
|
|
|
|
Note that if you are creating a clock with a fixed period which will never
|
|
change (for example the main clock source of a board), then you'll have
|
|
nothing else to do. This value will be propagated to other clocks when
|
|
connecting the clocks together and devices will fetch the right value during
|
|
the first reset.
|
|
|
|
Clock callbacks
|
|
---------------
|
|
|
|
You can give a clock a callback function in several ways:
|
|
|
|
* by passing it as an argument to ``qdev_init_clock_in()``
|
|
* as an argument to the ``QDEV_CLOCK_IN()`` macro initializing an
|
|
array to be passed to ``qdev_init_clocks()``
|
|
* by directly calling the ``clock_set_callback()`` function
|
|
|
|
The callback function must be of this type:
|
|
|
|
.. code-block:: c
|
|
|
|
typedef void ClockCallback(void *opaque, ClockEvent event);
|
|
|
|
The ``opaque`` argument is the pointer passed to ``qdev_init_clock_in()``
|
|
or ``clock_set_callback()``; for ``qdev_init_clocks()`` it is the
|
|
``dev`` device pointer.
|
|
|
|
The ``event`` argument specifies why the callback has been called.
|
|
When you register the callback you specify a mask of ClockEvent values
|
|
that you are interested in. The callback will only be called for those
|
|
events.
|
|
|
|
The events currently supported are:
|
|
|
|
* ``ClockPreUpdate`` : called when the input clock's period is about to
|
|
update. This is useful if the device needs to do some action for
|
|
which it needs to know the old value of the clock period. During
|
|
this callback, Clock API functions like ``clock_get()`` or
|
|
``clock_ticks_to_ns()`` will use the old period.
|
|
* ``ClockUpdate`` : called after the input clock's period has changed.
|
|
During this callback, Clock API functions like ``clock_ticks_to_ns()``
|
|
will use the new period.
|
|
|
|
Note that a clock only has one callback: it is not possible to register
|
|
different functions for different events. You must register a single
|
|
callback which listens for all of the events you are interested in,
|
|
and use the ``event`` argument to identify which event has happened.
|
|
|
|
Retrieving clocks from a device
|
|
-------------------------------
|
|
|
|
``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to
|
|
get the clock inputs or outputs of a device. For example:
|
|
|
|
.. code-block:: c
|
|
|
|
Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in");
|
|
|
|
or:
|
|
|
|
.. code-block:: c
|
|
|
|
Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out");
|
|
|
|
Connecting two clocks together
|
|
------------------------------
|
|
|
|
To connect two clocks together, use the ``clock_set_source()`` function.
|
|
Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);``
|
|
configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1``
|
|
is updated, ``clk2`` will be updated too.
|
|
|
|
When connecting clock between devices, prefer using the
|
|
``qdev_connect_clock_in()`` function to set the source of an input
|
|
device clock. For example, to connect the input clock ``clk2`` of
|
|
``devB`` to the output clock ``clk1`` of ``devA``, do:
|
|
|
|
.. code-block:: c
|
|
|
|
qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1"))
|
|
|
|
We used ``qdev_get_clock_out()`` above, but any clock can drive an
|
|
input clock, even another input clock. The following diagram shows
|
|
some examples of connections. Note also that a clock can drive several
|
|
other clocks.
|
|
|
|
::
|
|
|
|
+------------+ +--------------------------------------------------+
|
|
| Device A | | Device B |
|
|
| | | +---------------------+ |
|
|
| | | | Device C | |
|
|
| +-------+ | | +-------+ | +-------+ +-------+ | +-------+ |
|
|
| |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>>
|
|
| | (out) | | | | (in) | | | | (in) | | (out) | | | (out) | |
|
|
| +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ |
|
|
+------------+ | | +---------------------+ |
|
|
| | |
|
|
| | +--------------+ |
|
|
| | | Device D | |
|
|
| | | +-------+ | |
|
|
| +-->>|Clock 4| | |
|
|
| | | (in) | | |
|
|
| | +-------+ | |
|
|
| +--------------+ |
|
|
+--------------------------------------------------+
|
|
|
|
In the above example, when *Clock 1* is updated by *Device A*, three
|
|
clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*.
|
|
|
|
It is not possible to disconnect a clock or to change the clock connection
|
|
after it is connected.
|
|
|
|
Clock multiplier and divider settings
|
|
-------------------------------------
|
|
|
|
By default, when clocks are connected together, the child
|
|
clocks run with the same period as their source (parent) clock.
|
|
The Clock API supports a built-in period multiplier/divider
|
|
mechanism so you can configure a clock to make its children
|
|
run at a different period from its own. If you call the
|
|
``clock_set_mul_div()`` function you can specify the clock's
|
|
multiplier and divider values. The children of that clock
|
|
will all run with a period of ``parent_period * multiplier / divider``.
|
|
For instance, if the clock has a frequency of 8MHz and you set its
|
|
multiplier to 2 and its divider to 3, the child clocks will run
|
|
at 12MHz.
|
|
|
|
You can change the multiplier and divider of a clock at runtime,
|
|
so you can use this to model clock controller devices which
|
|
have guest-programmable frequency multipliers or dividers.
|
|
|
|
Note that ``clock_set_mul_div()`` does not automatically call
|
|
``clock_propagate()``. If you make a runtime change to the
|
|
multiplier or divider you must call clock_propagate() yourself.
|
|
|
|
Unconnected input clocks
|
|
------------------------
|
|
|
|
A newly created input clock is disabled (period of 0). This means the
|
|
clock will be considered as disabled until the period is updated. If
|
|
the clock remains unconnected it will always keep its initial value
|
|
of 0. If this is not the desired behaviour, ``clock_set()``,
|
|
``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock
|
|
object during device instance init. For example:
|
|
|
|
.. code-block:: c
|
|
|
|
clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback,
|
|
dev, ClockUpdate);
|
|
/* set initial value to 10ns / 100MHz */
|
|
clock_set_ns(clk, 10);
|
|
|
|
To enforce that the clock is wired up by the board code, you can
|
|
call ``clock_has_source()`` in your device's realize method:
|
|
|
|
.. code-block:: c
|
|
|
|
if (!clock_has_source(s->clk)) {
|
|
error_setg(errp, "MyDevice: clk input must be connected");
|
|
return;
|
|
}
|
|
|
|
Note that this only checks that the clock has been wired up; it is
|
|
still possible that the output clock connected to it is disabled
|
|
or has not yet been configured, in which case the period will be
|
|
zero. You should use the clock callback to find out when the clock
|
|
period changes.
|
|
|
|
Fetching clock frequency/period
|
|
-------------------------------
|
|
|
|
To get the current state of a clock, use the functions ``clock_get()``
|
|
or ``clock_get_hz()``.
|
|
|
|
``clock_get()`` returns the period of the clock in its fully precise
|
|
internal representation, as an unsigned 64-bit integer in units of
|
|
2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
|
|
be more convenient; see the section below on expiry deadlines.)
|
|
|
|
``clock_get_hz()`` returns the frequency of the clock, rounded to the
|
|
next lowest integer. This implies some inaccuracy due to the rounding,
|
|
so be cautious about using it in calculations.
|
|
|
|
It is also possible to register a callback on clock frequency changes.
|
|
Here is an example, which assumes that ``clock_callback`` has been
|
|
specified as the callback for the ``ClockUpdate`` event:
|
|
|
|
.. code-block:: c
|
|
|
|
void clock_callback(void *opaque, ClockEvent event) {
|
|
MyDeviceState *s = (MyDeviceState *) opaque;
|
|
/*
|
|
* 'opaque' is the argument passed to qdev_init_clock_in();
|
|
* usually this will be the device state pointer.
|
|
*/
|
|
|
|
/* do something with the new period */
|
|
fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
|
|
clock_get(dev->my_clk_input));
|
|
}
|
|
|
|
If you are only interested in the frequency for displaying it to
|
|
humans (for instance in debugging), use ``clock_display_freq()``,
|
|
which returns a prettified string-representation, e.g. "33.3 MHz".
|
|
The caller must free the string with g_free() after use.
|
|
|
|
Calculating expiry deadlines
|
|
----------------------------
|
|
|
|
A commonly required operation for a clock is to calculate how long
|
|
it will take for the clock to tick N times; this can then be used
|
|
to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``,
|
|
which takes an unsigned 64-bit count of ticks and returns the length
|
|
of time in nanoseconds required for the clock to tick that many times.
|
|
|
|
It is important not to try to calculate expiry deadlines using a
|
|
shortcut like multiplying a "period of clock in nanoseconds" value
|
|
by the tick count, because clocks can have periods which are not a
|
|
whole number of nanoseconds, and the accumulated error in the
|
|
multiplication can be significant.
|
|
|
|
For a clock with a very long period and a large number of ticks,
|
|
the result of this function could in theory be too large to fit in
|
|
a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()``
|
|
saturates the result to INT64_MAX (because this is the largest valid
|
|
input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost
|
|
300 years, anything with an expiry later than that is in the "will
|
|
never happen" category. Callers of ``clock_ticks_to_ns()`` should
|
|
therefore generally not special-case the possibility of a saturated
|
|
result but just allow the timer to be set to that far-future value.
|
|
(If you are performing further calculations on the returned value
|
|
rather than simply passing it to a QEMUTimer function like
|
|
``timer_mod_ns()`` then you should be careful to avoid overflow
|
|
in those calculations, of course.)
|
|
|
|
Obtaining tick counts
|
|
---------------------
|
|
|
|
For calculations where you need to know the number of ticks in
|
|
a given duration, use ``clock_ns_to_ticks()``. This function handles
|
|
possible non-whole-number-of-nanoseconds periods and avoids
|
|
potential rounding errors. It will return '0' if the clock is stopped
|
|
(i.e. it has period zero). If the inputs imply a tick count that
|
|
overflows a 64-bit value (a very long duration for a clock with a
|
|
very short period) the output value is truncated, so effectively
|
|
the 64-bit output wraps around.
|
|
|
|
Changing a clock period
|
|
-----------------------
|
|
|
|
A device can change its outputs using the ``clock_update()``,
|
|
``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger
|
|
updates on every connected input.
|
|
|
|
For example, let's say that we have an output clock *clkout* and we
|
|
have a pointer to it in the device state because we did the following
|
|
in init phase:
|
|
|
|
.. code-block:: c
|
|
|
|
dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout");
|
|
|
|
Then at any time (apart from the cases listed below), it is possible to
|
|
change the clock value by doing:
|
|
|
|
.. code-block:: c
|
|
|
|
clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */
|
|
|
|
Because updating a clock may trigger any side effects through
|
|
connected clocks and their callbacks, this operation must be done
|
|
while holding the qemu io lock.
|
|
|
|
For the same reason, one can update clocks only when it is allowed to have
|
|
side effects on other objects. In consequence, it is forbidden:
|
|
|
|
* during migration,
|
|
* and in the enter phase of reset.
|
|
|
|
Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling
|
|
``clock_set[_ns|_hz]()`` (with the same arguments) then
|
|
``clock_propagate()`` on the clock. Thus, setting the clock value can
|
|
be separated from triggering the side-effects. This is often required
|
|
to factorize code to handle reset and migration in devices.
|
|
|
|
Aliasing clocks
|
|
---------------
|
|
|
|
Sometimes, one needs to forward, or inherit, a clock from another
|
|
device. Typically, when doing device composition, a device might
|
|
expose a sub-device's clock without interfering with it. The function
|
|
``qdev_alias_clock()`` can be used to achieve this behaviour. Note
|
|
that it is possible to expose the clock under a different name.
|
|
``qdev_alias_clock()`` works for both input and output clocks.
|
|
|
|
For example, if device B is a child of device A,
|
|
``device_a_instance_init()`` may do something like this:
|
|
|
|
.. code-block:: c
|
|
|
|
void device_a_instance_init(Object *obj)
|
|
{
|
|
AState *A = DEVICE_A(obj);
|
|
BState *B;
|
|
/* create object B as child of A */
|
|
[...]
|
|
qdev_alias_clock(B, "clk", A, "b_clk");
|
|
/*
|
|
* Now A has a clock "b_clk" which is an alias to
|
|
* the clock "clk" of its child B.
|
|
*/
|
|
}
|
|
|
|
This function does not return any clock object. The new clock has the
|
|
same direction (input or output) as the original one. This function
|
|
only adds a link to the existing clock. In the above example, object B
|
|
remains the only object allowed to use the clock and device A must not
|
|
try to change the clock period or set a callback to the clock. This
|
|
diagram describes the example with an input clock::
|
|
|
|
+--------------------------+
|
|
| Device A |
|
|
| +--------------+ |
|
|
| | Device B | |
|
|
| | +-------+ | |
|
|
>>"b_clk">>>| "clk" | | |
|
|
| (in) | | (in) | | |
|
|
| | +-------+ | |
|
|
| +--------------+ |
|
|
+--------------------------+
|
|
|
|
Migration
|
|
---------
|
|
|
|
Clock state is not migrated automatically. Every device must handle its
|
|
clock migration. Alias clocks must not be migrated.
|
|
|
|
To ensure clock states are restored correctly during migration, there
|
|
are two solutions.
|
|
|
|
Clock states can be migrated by adding an entry into the device
|
|
vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this.
|
|
This is typically used to migrate an input clock state. For example:
|
|
|
|
.. code-block:: c
|
|
|
|
MyDeviceState {
|
|
DeviceState parent_obj;
|
|
[...] /* some fields */
|
|
Clock *clk;
|
|
};
|
|
|
|
VMStateDescription my_device_vmstate = {
|
|
.name = "my_device",
|
|
.fields = (VMStateField[]) {
|
|
[...], /* other migrated fields */
|
|
VMSTATE_CLOCK(clk, MyDeviceState),
|
|
VMSTATE_END_OF_LIST()
|
|
}
|
|
};
|
|
|
|
The second solution is to restore the clock state using information already
|
|
at our disposal. This can be used to restore output clock states using the
|
|
device state. The functions ``clock_set[_ns|_hz]()`` can be used during the
|
|
``post_load()`` migration callback.
|
|
|
|
When adding clock support to an existing device, if you care about
|
|
migration compatibility you will need to be careful, as simply adding
|
|
a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can
|
|
put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a
|
|
suitable ``needed`` function, and use ``clock_set()`` in a
|
|
``pre_load()`` function to set the default value that will be used if
|
|
the source virtual machine in the migration does not send the clock
|
|
state.
|
|
|
|
Care should be taken not to use ``clock_update[_ns|_hz]()`` or
|
|
``clock_propagate()`` during the whole migration procedure because it
|
|
will trigger side effects to other devices in an unknown state.
|