One Hat Cyber Team

Edit File: clocks.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
 <meta charset="utf-8">
 
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <title>Modelling a clock tree in QEMU &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
 
 
 
 
 
 
 Contents:
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></li>
<li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Information</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="code-of-conduct.html">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="conflict-resolution.html">Conflict Resolution Policy</a></li>
<li class="toctree-l2"><a class="reference internal" href="build-system.html">The QEMU build system architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">QEMU Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="kconfig.html">QEMU and Kconfig</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="fuzzing.html">Fuzzing</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow-integrity.html">Control-Flow Integrity (CFI)</a></li>
<li class="toctree-l2"><a class="reference internal" href="loads-stores.html">Load and Store APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html">The memory API</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="atomics.html">Atomic operations in QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="stable-process.html">QEMU and the stable process</a></li>
<li class="toctree-l2"><a class="reference internal" href="ci.html">CI</a></li>
<li class="toctree-l2"><a class="reference internal" href="qtest.html">QTest Device Emulation Testing Framework</a></li>
<li class="toctree-l2"><a class="reference internal" href="decodetree.html">Decodetree Specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="secure-coding-practices.html">Secure Coding Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg.html">Translator Internals</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-icount.html">TCG Instruction Counting</a></li>
<li class="toctree-l2"><a class="reference internal" href="tracing.html">Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-thread-tcg.html">Multi-threaded TCG</a></li>
<li class="toctree-l2"><a class="reference internal" href="tcg-plugins.html">QEMU TCG Plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="bitops.html">Bitwise operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="ui.html">QEMU UI subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="reset.html">Reset in QEMU: the Resettable interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="s390-dasd-ipl.html">Booting from real channel-attached devices on s390x</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Modelling a clock tree in QEMU</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#what-are-clocks">What are clocks?</a></li>
<li class="toctree-l3"><a class="reference internal" href="#the-clock-state">The clock state</a></li>
<li class="toctree-l3"><a class="reference internal" href="#adding-a-new-clock">Adding a new clock</a></li>
<li class="toctree-l3"><a class="reference internal" href="#clock-callbacks">Clock callbacks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#retrieving-clocks-from-a-device">Retrieving clocks from a device</a></li>
<li class="toctree-l3"><a class="reference internal" href="#connecting-two-clocks-together">Connecting two clocks together</a></li>
<li class="toctree-l3"><a class="reference internal" href="#clock-multiplier-and-divider-settings">Clock multiplier and divider settings</a></li>
<li class="toctree-l3"><a class="reference internal" href="#unconnected-input-clocks">Unconnected input clocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#fetching-clock-frequency-period">Fetching clock frequency/period</a></li>
<li class="toctree-l3"><a class="reference internal" href="#calculating-expiry-deadlines">Calculating expiry deadlines</a></li>
<li class="toctree-l3"><a class="reference internal" href="#obtaining-tick-counts">Obtaining tick counts</a></li>
<li class="toctree-l3"><a class="reference internal" href="#changing-a-clock-period">Changing a clock period</a></li>
<li class="toctree-l3"><a class="reference internal" href="#aliasing-clocks">Aliasing clocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#migration">Migration</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="qom.html">The QEMU Object Model (QOM)</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html">QEMU modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="block-coroutine-wrapper.html">block-coroutine-wrapper</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="ebpf_rss.html">eBPF RSS virtio-net support</a></li>
<li class="toctree-l2"><a class="reference internal" href="vfio-migration.html">VFIO device Migration</a></li>
<li class="toctree-l2"><a class="reference internal" href="qapi-code-gen.html">How to use the QAPI code generator</a></li>
<li class="toctree-l2"><a class="reference internal" href="writing-monitor-commands.html">How to write monitor commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="trivial-patches.html">Trivial Patches</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-patch.html">Submitting a Patch</a></li>
<li class="toctree-l2"><a class="reference internal" href="submitting-a-pull-request.html">Submitting a Pull Request</a></li>
</ul>
</li>
</ul>

</div>
 </div>
 </nav>

<ul class="wy-breadcrumbs">
 
 <li><a href="../index.html">Docs</a> &raquo;</li>
 
 <li><a href="index.html">Developer Information</a> &raquo;</li>
 
 <li>Modelling a clock tree in QEMU</li>
 
 
 <li class="wy-breadcrumbs-aside">
 
 
 
 <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/devel/clocks.rst" class="fa fa-gitlab"> Edit on GitLab</a>
 
 
 
 </li>
 
 </ul>

<hr/>
</div>
 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 <div itemprop="articleBody">
 
 <div class="section" id="modelling-a-clock-tree-in-qemu">
<h1>Modelling a clock tree in QEMU<a class="headerlink" href="#modelling-a-clock-tree-in-qemu" title="Permalink to this headline">¶</a></h1>
<div class="section" id="what-are-clocks">
<h2>What are clocks?<a class="headerlink" href="#what-are-clocks" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">clock</code> (in C code, the macro
<code class="docutils literal notranslate">TYPE_CLOCK</code>).
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:
<div class="highlight-default notranslate"><div class="highlight"><pre>+---------+ +----------------------+ +--------------+
| Clock 1 | | Device B | | Device C |
| | | +-------+ +-------+ | | +-------+ |
| |&gt;&gt;-+--&gt;&gt;|Clock 2| |Clock 3|&gt;&gt;---&gt;&gt;|Clock 6| |
+---------+ | | | (in) | | (out) | | | | (in) | |
 | | +-------+ +-------+ | | +-------+ |
 | | +-------+ | +--------------+
 | | |Clock 4|&gt;&gt;
 | | | (out) | | +--------------+
 | | +-------+ | | Device D |
 | | +-------+ | | +-------+ |
 | | |Clock 5|&gt;&gt;---&gt;&gt;|Clock 7| |
 | | | (out) | | | | (in) | |
 | | +-------+ | | +-------+ |
 | +----------------------+ | |
 | | +-------+ |
 +-----------------------------&gt;&gt;|Clock 8| |
 | | (in) | |
 | +-------+ |
 +--------------+
</pre></div>
</div>
Clocks are defined in the <code class="docutils literal notranslate">include/hw/clock.h</code> header and device
related functions are defined in the <code class="docutils literal notranslate">include/hw/qdev-clock.h</code>
header.
</div>
<div class="section" id="the-clock-state">
<h2>The clock state<a class="headerlink" href="#the-clock-state" title="Permalink to this headline">¶</a></h2>
The state of a clock is its period; it is stored as an integer
representing it in units of 2 -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:
<ul class="simple">
<li><code class="docutils literal notranslate">_ns</code> for handling periods in nanoseconds</li>
<li><code class="docutils literal notranslate">_hz</code> for handling frequencies in hertz</li>
</ul>
The 0 period value is converted to 0 in hertz and vice versa. 0 always means
that the clock is disabled.
</div>
<div class="section" id="adding-a-new-clock">
<h2>Adding a new clock<a class="headerlink" href="#adding-a-new-clock" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">qdev_init_clock_in()</code>
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:
<div class="highlight-default notranslate"><div class="highlight"><pre>qdev_init_clock_in(DEVICE(dev), &quot;clk_in&quot;, clk_in_callback, dev, ClockUpdate);
qdev_init_clock_out(DEVICE(dev), &quot;clk_out&quot;);
</pre></div>
</div>
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 <code class="docutils literal notranslate">qdev_init_clocks()</code> must be called with the array as
parameter to initialize the clocks: it has the same behaviour as calling the
<code class="docutils literal notranslate">qdev_init_clock_in/out()</code> for each clock in the array. To ease the array
construction, some macros are defined in <code class="docutils literal notranslate">include/hw/qdev-clock.h</code>.
As an example, the following creates 2 clocks to a device: one input and one
output.
<div class="highlight-c notranslate"><div class="highlight"><pre>/* 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 &quot;Callback on input clock
 * change&quot; section below for more information).
 */
static void clk_in_callback(void *opaque, ClockEvent event);

/*
 * static array describing clocks:
 * + a clock input named &quot;clk_in&quot;, whose pointer is stored in
 * the clk_in field of a MyDeviceState structure with callback
 * clk_in_callback.
 * + a clock output named &quot;clk_out&quot; 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);
 [...]
}
</pre></div>
</div>
An alternative way to create a clock is to simply call
<code class="docutils literal notranslate">object_new(TYPE_CLOCK)</code>. 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 <code class="docutils literal notranslate">clock_setup_canonical_path()</code> should be called.
At creation, the period of the clock is 0: the clock is disabled. You can
change it using <code class="docutils literal notranslate">clock_set_ns()</code> or <code class="docutils literal notranslate">clock_set_hz()</code>.
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.
</div>
<div class="section" id="clock-callbacks">
<h2>Clock callbacks<a class="headerlink" href="#clock-callbacks" title="Permalink to this headline">¶</a></h2>
You can give a clock a callback function in several ways:
<blockquote>
<div><ul class="simple">
<li>by passing it as an argument to <code class="docutils literal notranslate">qdev_init_clock_in()</code></li>
<li>as an argument to the <code class="docutils literal notranslate">QDEV_CLOCK_IN()</code> macro initializing an
array to be passed to <code class="docutils literal notranslate">qdev_init_clocks()</code></li>
<li>by directly calling the <code class="docutils literal notranslate">clock_set_callback()</code> function</li>
</ul>
</div></blockquote>
The callback function must be of this type:
<div class="highlight-c notranslate"><div class="highlight"><pre>typedef void ClockCallback(void *opaque, ClockEvent event);
</pre></div>
</div>
The <code class="docutils literal notranslate">opaque</code> argument is the pointer passed to <code class="docutils literal notranslate">qdev_init_clock_in()</code>
or <code class="docutils literal notranslate">clock_set_callback()</code>; for <code class="docutils literal notranslate">qdev_init_clocks()</code> it is the
<code class="docutils literal notranslate">dev</code> device pointer.
The <code class="docutils literal notranslate">event</code> 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:
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal notranslate">ClockPreUpdate</code> : 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 <code class="docutils literal notranslate">clock_get()</code> or
<code class="docutils literal notranslate">clock_ticks_to_ns()</code> will use the old period.</li>
<li><code class="docutils literal notranslate">ClockUpdate</code> : called after the input clock’s period has changed.
During this callback, Clock API functions like <code class="docutils literal notranslate">clock_ticks_to_ns()</code>
will use the new period.</li>
</ul>
</div></blockquote>
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 <code class="docutils literal notranslate">event</code> argument to identify which event has happened.
</div>
<div class="section" id="retrieving-clocks-from-a-device">
<h2>Retrieving clocks from a device<a class="headerlink" href="#retrieving-clocks-from-a-device" title="Permalink to this headline">¶</a></h2>
<code class="docutils literal notranslate">qdev_get_clock_in()</code> and <code class="docutils literal notranslate">dev_get_clock_out()</code> are available to
get the clock inputs or outputs of a device. For example:
<div class="highlight-c notranslate"><div class="highlight"><pre>Clock *clk = qdev_get_clock_in(DEVICE(mydev), &quot;clk_in&quot;);
</pre></div>
</div>
or:
<div class="highlight-c notranslate"><div class="highlight"><pre>Clock *clk = qdev_get_clock_out(DEVICE(mydev), &quot;clk_out&quot;);
</pre></div>
</div>
</div>
<div class="section" id="connecting-two-clocks-together">
<h2>Connecting two clocks together<a class="headerlink" href="#connecting-two-clocks-together" title="Permalink to this headline">¶</a></h2>
To connect two clocks together, use the <code class="docutils literal notranslate">clock_set_source()</code> function.
Given two clocks <code class="docutils literal notranslate">clk1</code>, and <code class="docutils literal notranslate">clk2</code>, <code class="docutils literal notranslate">clock_set_source(clk2, clk1);</code>
configures <code class="docutils literal notranslate">clk2</code> to follow the <code class="docutils literal notranslate">clk1</code> period changes. Every time <code class="docutils literal notranslate">clk1</code>
is updated, <code class="docutils literal notranslate">clk2</code> will be updated too.
When connecting clock between devices, prefer using the
<code class="docutils literal notranslate">qdev_connect_clock_in()</code> function to set the source of an input
device clock. For example, to connect the input clock <code class="docutils literal notranslate">clk2</code> of
<code class="docutils literal notranslate">devB</code> to the output clock <code class="docutils literal notranslate">clk1</code> of <code class="docutils literal notranslate">devA</code>, do:
<div class="highlight-c notranslate"><div class="highlight"><pre>qdev_connect_clock_in(devB, &quot;clk2&quot;, qdev_get_clock_out(devA, &quot;clk1&quot;))
</pre></div>
</div>
We used <code class="docutils literal notranslate">qdev_get_clock_out()</code> 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.
<div class="highlight-default notranslate"><div class="highlight"><pre>+------------+ +--------------------------------------------------+
| Device A | | Device B |
| | | +---------------------+ |
| | | | Device C | |
| +-------+ | | +-------+ | +-------+ +-------+ | +-------+ |
| |Clock 1|&gt;&gt;--&gt;&gt;|Clock 2|&gt;&gt;+--&gt;&gt;|Clock 3| |Clock 5|&gt;&gt;&gt;&gt;|Clock 6|&gt;&gt;
| | (out) | | | | (in) | | | | (in) | | (out) | | | (out) | |
| +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ |
+------------+ | | +---------------------+ |
 | | |
 | | +--------------+ |
 | | | Device D | |
 | | | +-------+ | |
 | +--&gt;&gt;|Clock 4| | |
 | | | (in) | | |
 | | +-------+ | |
 | +--------------+ |
 +--------------------------------------------------+
</pre></div>
</div>
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.
</div>
<div class="section" id="clock-multiplier-and-divider-settings">
<h2>Clock multiplier and divider settings<a class="headerlink" href="#clock-multiplier-and-divider-settings" title="Permalink to this headline">¶</a></h2>
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
<code class="docutils literal notranslate">clock_set_mul_div()</code> function you can specify the clock’s
multiplier and divider values. The children of that clock
will all run with a period of <code class="docutils literal notranslate">parent_period * multiplier / divider</code>.
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 <code class="docutils literal notranslate">clock_set_mul_div()</code> does not automatically call
<code class="docutils literal notranslate">clock_propagate()</code>. If you make a runtime change to the
multiplier or divider you must call clock_propagate() yourself.
</div>
<div class="section" id="unconnected-input-clocks">
<h2>Unconnected input clocks<a class="headerlink" href="#unconnected-input-clocks" title="Permalink to this headline">¶</a></h2>
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, <code class="docutils literal notranslate">clock_set()</code>,
<code class="docutils literal notranslate">clock_set_ns()</code> or <code class="docutils literal notranslate">clock_set_hz()</code> should be called on the Clock
object during device instance init. For example:
<div class="highlight-c notranslate"><div class="highlight"><pre>clk = qdev_init_clock_in(DEVICE(dev), &quot;clk-in&quot;, clk_in_callback,
 dev, ClockUpdate);
/* set initial value to 10ns / 100MHz */
clock_set_ns(clk, 10);
</pre></div>
</div>
To enforce that the clock is wired up by the board code, you can
call <code class="docutils literal notranslate">clock_has_source()</code> in your device’s realize method:
<div class="highlight-c notranslate"><div class="highlight"><pre>if (!clock_has_source(s-&gt;clk)) {
 error_setg(errp, &quot;MyDevice: clk input must be connected&quot;);
 return;
}
</pre></div>
</div>
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.
</div>
<div class="section" id="fetching-clock-frequency-period">
<h2>Fetching clock frequency/period<a class="headerlink" href="#fetching-clock-frequency-period" title="Permalink to this headline">¶</a></h2>
To get the current state of a clock, use the functions <code class="docutils literal notranslate">clock_get()</code>
or <code class="docutils literal notranslate">clock_get_hz()</code>.
<code class="docutils literal notranslate">clock_get()</code> 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 <code class="docutils literal notranslate">clock_ticks_to_ns()</code> will
be more convenient; see the section below on expiry deadlines.)
<code class="docutils literal notranslate">clock_get_hz()</code> 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 <code class="docutils literal notranslate">clock_callback</code> has been
specified as the callback for the <code class="docutils literal notranslate">ClockUpdate</code> event:
<div class="highlight-c notranslate"><div class="highlight"><pre>void clock_callback(void *opaque, ClockEvent event) {
 MyDeviceState *s = (MyDeviceState *) opaque;
 /*
 * &#39;opaque&#39; 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, &quot;device new period is %&quot; PRIu64 &quot;* 2^-32 ns\n&quot;,
 clock_get(dev-&gt;my_clk_input));
}
</pre></div>
</div>
If you are only interested in the frequency for displaying it to
humans (for instance in debugging), use <code class="docutils literal notranslate">clock_display_freq()</code>,
which returns a prettified string-representation, e.g. “33.3 MHz”.
The caller must free the string with g_free() after use.
</div>
<div class="section" id="calculating-expiry-deadlines">
<h2>Calculating expiry deadlines<a class="headerlink" href="#calculating-expiry-deadlines" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">clock_ticks_to_ns()</code>,
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, <code class="docutils literal notranslate">clock_ticks_to_ns()</code>
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 <code class="docutils literal notranslate">clock_ticks_to_ns()</code> 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
<code class="docutils literal notranslate">timer_mod_ns()</code> then you should be careful to avoid overflow
in those calculations, of course.)
</div>
<div class="section" id="obtaining-tick-counts">
<h2>Obtaining tick counts<a class="headerlink" href="#obtaining-tick-counts" title="Permalink to this headline">¶</a></h2>
For calculations where you need to know the number of ticks in
a given duration, use <code class="docutils literal notranslate">clock_ns_to_ticks()</code>. 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.
</div>
<div class="section" id="changing-a-clock-period">
<h2>Changing a clock period<a class="headerlink" href="#changing-a-clock-period" title="Permalink to this headline">¶</a></h2>
A device can change its outputs using the <code class="docutils literal notranslate">clock_update()</code>,
<code class="docutils literal notranslate">clock_update_ns()</code> or <code class="docutils literal notranslate">clock_update_hz()</code> 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:
<div class="highlight-c notranslate"><div class="highlight"><pre>dev-&gt;clkout = qdev_init_clock_out(DEVICE(dev), &quot;clkout&quot;);
</pre></div>
</div>
Then at any time (apart from the cases listed below), it is possible to
change the clock value by doing:
<div class="highlight-c notranslate"><div class="highlight"><pre>clock_update_hz(dev-&gt;clkout, 1000 * 1000 * 1000); /* 1GHz */
</pre></div>
</div>
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:
<ul class="simple">
<li>during migration,</li>
<li>and in the enter phase of reset.</li>
</ul>
Note that calling <code class="docutils literal notranslate">clock_update[_ns|_hz]()</code> is equivalent to calling
<code class="docutils literal notranslate">clock_set[_ns|_hz]()</code> (with the same arguments) then
<code class="docutils literal notranslate">clock_propagate()</code> 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.
</div>
<div class="section" id="aliasing-clocks">
<h2>Aliasing clocks<a class="headerlink" href="#aliasing-clocks" title="Permalink to this headline">¶</a></h2>
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
<code class="docutils literal notranslate">qdev_alias_clock()</code> can be used to achieve this behaviour. Note
that it is possible to expose the clock under a different name.
<code class="docutils literal notranslate">qdev_alias_clock()</code> works for both input and output clocks.
For example, if device B is a child of device A,
<code class="docutils literal notranslate">device_a_instance_init()</code> may do something like this:
<div class="highlight-c notranslate"><div class="highlight"><pre>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, &quot;clk&quot;, A, &quot;b_clk&quot;);
 /*
 * Now A has a clock &quot;b_clk&quot; which is an alias to
 * the clock &quot;clk&quot; of its child B.
 */
}
</pre></div>
</div>
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:
<div class="highlight-default notranslate"><div class="highlight"><pre>+--------------------------+
| Device A |
| +--------------+ |
| | Device B | |
| | +-------+ | |
&gt;&gt;&quot;b_clk&quot;&gt;&gt;&gt;| &quot;clk&quot; | | |
| (in) | | (in) | | |
| | +-------+ | |
| +--------------+ |
+--------------------------+
</pre></div>
</div>
</div>
<div class="section" id="migration">
<h2>Migration<a class="headerlink" href="#migration" title="Permalink to this headline">¶</a></h2>
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 <code class="docutils literal notranslate">VMSTATE_CLOCK</code> macro for this.
This is typically used to migrate an input clock state. For example:
<div class="highlight-c notranslate"><div class="highlight"><pre>MyDeviceState {
 DeviceState parent_obj;
 [...] /* some fields */
 Clock *clk;
};

VMStateDescription my_device_vmstate = {
 .name = &quot;my_device&quot;,
 .fields = (VMStateField[]) {
 [...], /* other migrated fields */
 VMSTATE_CLOCK(clk, MyDeviceState),
 VMSTATE_END_OF_LIST()
 }
};
</pre></div>
</div>
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 <code class="docutils literal notranslate">clock_set[_ns|_hz]()</code> can be used during the
<code class="docutils literal notranslate">post_load()</code> 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 <code class="docutils literal notranslate">VMSTATE_CLOCK()</code> line will break compatibility. Instead, you can
put the <code class="docutils literal notranslate">VMSTATE_CLOCK()</code> line into a vmstate subsection with a
suitable <code class="docutils literal notranslate">needed</code> function, and use <code class="docutils literal notranslate">clock_set()</code> in a
<code class="docutils literal notranslate">pre_load()</code> 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 <code class="docutils literal notranslate">clock_update[_ns|_hz]()</code> or
<code class="docutils literal notranslate">clock_propagate()</code> during the whole migration procedure because it
will trigger side effects to other devices in an unknown state.
</div>
</div>

</div>
 
 </div>
 <footer>
 
 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 
 <a href="qom.html" class="btn btn-neutral float-right" title="The QEMU Object Model (QOM)" accesskey="n" rel="next">Next </a>
 
 
 <a href="s390-dasd-ipl.html" class="btn btn-neutral" title="Booting from real channel-attached devices on s390x" accesskey="p" rel="prev"> Previous</a>
 
 </div>

<hr/>

</div>
 Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

This documentation is for QEMU version 6.2.0.

<a href="../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a>

</footer>

</div>
 </div>

</section>

</div>

</body>
</html>