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, an opaque parameter 84for the callback and a mask of events when the callback should be 85called (this will be explained in a following section). 86Output is simpler; only the name is required. Typically:: 87 88 qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev, ClockUpdate); 89 qdev_init_clock_out(DEVICE(dev), "clk_out"); 90 91Both functions return the created Clock pointer, which should be saved in the 92device's state structure for further use. 93 94These objects will be automatically deleted by the QOM reference mechanism. 95 96Note that it is possible to create a static array describing clock inputs and 97outputs. The function ``qdev_init_clocks()`` must be called with the array as 98parameter to initialize the clocks: it has the same behaviour as calling the 99``qdev_init_clock_in/out()`` for each clock in the array. To ease the array 100construction, some macros are defined in ``include/hw/qdev-clock.h``. 101As an example, the following creates 2 clocks to a device: one input and one 102output. 103 104.. code-block:: c 105 106 /* device structure containing pointers to the clock objects */ 107 typedef struct MyDeviceState { 108 DeviceState parent_obj; 109 Clock *clk_in; 110 Clock *clk_out; 111 } MyDeviceState; 112 113 /* 114 * callback for the input clock (see "Callback on input clock 115 * change" section below for more information). 116 */ 117 static void clk_in_callback(void *opaque, ClockEvent event); 118 119 /* 120 * static array describing clocks: 121 * + a clock input named "clk_in", whose pointer is stored in 122 * the clk_in field of a MyDeviceState structure with callback 123 * clk_in_callback. 124 * + a clock output named "clk_out" whose pointer is stored in 125 * the clk_out field of a MyDeviceState structure. 126 */ 127 static const ClockPortInitArray mydev_clocks = { 128 QDEV_CLOCK_IN(MyDeviceState, clk_in, clk_in_callback, ClockUpdate), 129 QDEV_CLOCK_OUT(MyDeviceState, clk_out), 130 QDEV_CLOCK_END 131 }; 132 133 /* device initialization function */ 134 static void mydev_init(Object *obj) 135 { 136 /* cast to MyDeviceState */ 137 MyDeviceState *mydev = MYDEVICE(obj); 138 /* create and fill the pointer fields in the MyDeviceState */ 139 qdev_init_clocks(mydev, mydev_clocks); 140 [...] 141 } 142 143An alternative way to create a clock is to simply call 144``object_new(TYPE_CLOCK)``. In that case the clock will neither be an 145input nor an output of a device. After the whole QOM hierarchy of the 146clock has been set ``clock_setup_canonical_path()`` should be called. 147 148At creation, the period of the clock is 0: the clock is disabled. You can 149change it using ``clock_set_ns()`` or ``clock_set_hz()``. 150 151Note that if you are creating a clock with a fixed period which will never 152change (for example the main clock source of a board), then you'll have 153nothing else to do. This value will be propagated to other clocks when 154connecting the clocks together and devices will fetch the right value during 155the first reset. 156 157Clock callbacks 158--------------- 159 160You can give a clock a callback function in several ways: 161 162 * by passing it as an argument to ``qdev_init_clock_in()`` 163 * as an argument to the ``QDEV_CLOCK_IN()`` macro initializing an 164 array to be passed to ``qdev_init_clocks()`` 165 * by directly calling the ``clock_set_callback()`` function 166 167The callback function must be of this type: 168 169.. code-block:: c 170 171 typedef void ClockCallback(void *opaque, ClockEvent event); 172 173The ``opaque`` argument is the pointer passed to ``qdev_init_clock_in()`` 174or ``clock_set_callback()``; for ``qdev_init_clocks()`` it is the 175``dev`` device pointer. 176 177The ``event`` argument specifies why the callback has been called. 178When you register the callback you specify a mask of ClockEvent values 179that you are interested in. The callback will only be called for those 180events. 181 182The events currently supported are: 183 184 * ``ClockUpdate`` : called after the input clock's period has changed 185 186Note that a clock only has one callback: it is not possible to register 187different functions for different events. You must register a single 188callback which listens for all of the events you are interested in, 189and use the ``event`` argument to identify which event has happened. 190 191Retrieving clocks from a device 192------------------------------- 193 194``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to 195get the clock inputs or outputs of a device. For example: 196 197.. code-block:: c 198 199 Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in"); 200 201or: 202 203.. code-block:: c 204 205 Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out"); 206 207Connecting two clocks together 208------------------------------ 209 210To connect two clocks together, use the ``clock_set_source()`` function. 211Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);`` 212configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1`` 213is updated, ``clk2`` will be updated too. 214 215When connecting clock between devices, prefer using the 216``qdev_connect_clock_in()`` function to set the source of an input 217device clock. For example, to connect the input clock ``clk2`` of 218``devB`` to the output clock ``clk1`` of ``devA``, do: 219 220.. code-block:: c 221 222 qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1")) 223 224We used ``qdev_get_clock_out()`` above, but any clock can drive an 225input clock, even another input clock. The following diagram shows 226some examples of connections. Note also that a clock can drive several 227other clocks. 228 229:: 230 231 +------------+ +--------------------------------------------------+ 232 | Device A | | Device B | 233 | | | +---------------------+ | 234 | | | | Device C | | 235 | +-------+ | | +-------+ | +-------+ +-------+ | +-------+ | 236 | |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>> 237 | | (out) | | | | (in) | | | | (in) | | (out) | | | (out) | | 238 | +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ | 239 +------------+ | | +---------------------+ | 240 | | | 241 | | +--------------+ | 242 | | | Device D | | 243 | | | +-------+ | | 244 | +-->>|Clock 4| | | 245 | | | (in) | | | 246 | | +-------+ | | 247 | +--------------+ | 248 +--------------------------------------------------+ 249 250In the above example, when *Clock 1* is updated by *Device A*, three 251clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*. 252 253It is not possible to disconnect a clock or to change the clock connection 254after it is connected. 255 256Unconnected input clocks 257------------------------ 258 259A newly created input clock is disabled (period of 0). This means the 260clock will be considered as disabled until the period is updated. If 261the clock remains unconnected it will always keep its initial value 262of 0. If this is not the desired behaviour, ``clock_set()``, 263``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock 264object during device instance init. For example: 265 266.. code-block:: c 267 268 clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback, 269 dev, ClockUpdate); 270 /* set initial value to 10ns / 100MHz */ 271 clock_set_ns(clk, 10); 272 273To enforce that the clock is wired up by the board code, you can 274call ``clock_has_source()`` in your device's realize method: 275 276.. code-block:: c 277 278 if (!clock_has_source(s->clk)) { 279 error_setg(errp, "MyDevice: clk input must be connected"); 280 return; 281 } 282 283Note that this only checks that the clock has been wired up; it is 284still possible that the output clock connected to it is disabled 285or has not yet been configured, in which case the period will be 286zero. You should use the clock callback to find out when the clock 287period changes. 288 289Fetching clock frequency/period 290------------------------------- 291 292To get the current state of a clock, use the functions ``clock_get()`` 293or ``clock_get_hz()``. 294 295``clock_get()`` returns the period of the clock in its fully precise 296internal representation, as an unsigned 64-bit integer in units of 2972^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will 298be more convenient; see the section below on expiry deadlines.) 299 300``clock_get_hz()`` returns the frequency of the clock, rounded to the 301next lowest integer. This implies some inaccuracy due to the rounding, 302so be cautious about using it in calculations. 303 304It is also possible to register a callback on clock frequency changes. 305Here is an example, which assumes that ``clock_callback`` has been 306specified as the callback for the ``ClockUpdate`` event: 307 308.. code-block:: c 309 310 void clock_callback(void *opaque, ClockEvent event) { 311 MyDeviceState *s = (MyDeviceState *) opaque; 312 /* 313 * 'opaque' is the argument passed to qdev_init_clock_in(); 314 * usually this will be the device state pointer. 315 */ 316 317 /* do something with the new period */ 318 fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n", 319 clock_get(dev->my_clk_input)); 320 } 321 322If you are only interested in the frequency for displaying it to 323humans (for instance in debugging), use ``clock_display_freq()``, 324which returns a prettified string-representation, e.g. "33.3 MHz". 325The caller must free the string with g_free() after use. 326 327Calculating expiry deadlines 328---------------------------- 329 330A commonly required operation for a clock is to calculate how long 331it will take for the clock to tick N times; this can then be used 332to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``, 333which takes an unsigned 64-bit count of ticks and returns the length 334of time in nanoseconds required for the clock to tick that many times. 335 336It is important not to try to calculate expiry deadlines using a 337shortcut like multiplying a "period of clock in nanoseconds" value 338by the tick count, because clocks can have periods which are not a 339whole number of nanoseconds, and the accumulated error in the 340multiplication can be significant. 341 342For a clock with a very long period and a large number of ticks, 343the result of this function could in theory be too large to fit in 344a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()`` 345saturates the result to INT64_MAX (because this is the largest valid 346input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost 347300 years, anything with an expiry later than that is in the "will 348never happen" category. Callers of ``clock_ticks_to_ns()`` should 349therefore generally not special-case the possibility of a saturated 350result but just allow the timer to be set to that far-future value. 351(If you are performing further calculations on the returned value 352rather than simply passing it to a QEMUTimer function like 353``timer_mod_ns()`` then you should be careful to avoid overflow 354in those calculations, of course.) 355 356Changing a clock period 357----------------------- 358 359A device can change its outputs using the ``clock_update()``, 360``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger 361updates on every connected input. 362 363For example, let's say that we have an output clock *clkout* and we 364have a pointer to it in the device state because we did the following 365in init phase: 366 367.. code-block:: c 368 369 dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout"); 370 371Then at any time (apart from the cases listed below), it is possible to 372change the clock value by doing: 373 374.. code-block:: c 375 376 clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */ 377 378Because updating a clock may trigger any side effects through 379connected clocks and their callbacks, this operation must be done 380while holding the qemu io lock. 381 382For the same reason, one can update clocks only when it is allowed to have 383side effects on other objects. In consequence, it is forbidden: 384 385* during migration, 386* and in the enter phase of reset. 387 388Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling 389``clock_set[_ns|_hz]()`` (with the same arguments) then 390``clock_propagate()`` on the clock. Thus, setting the clock value can 391be separated from triggering the side-effects. This is often required 392to factorize code to handle reset and migration in devices. 393 394Aliasing clocks 395--------------- 396 397Sometimes, one needs to forward, or inherit, a clock from another 398device. Typically, when doing device composition, a device might 399expose a sub-device's clock without interfering with it. The function 400``qdev_alias_clock()`` can be used to achieve this behaviour. Note 401that it is possible to expose the clock under a different name. 402``qdev_alias_clock()`` works for both input and output clocks. 403 404For example, if device B is a child of device A, 405``device_a_instance_init()`` may do something like this: 406 407.. code-block:: c 408 409 void device_a_instance_init(Object *obj) 410 { 411 AState *A = DEVICE_A(obj); 412 BState *B; 413 /* create object B as child of A */ 414 [...] 415 qdev_alias_clock(B, "clk", A, "b_clk"); 416 /* 417 * Now A has a clock "b_clk" which is an alias to 418 * the clock "clk" of its child B. 419 */ 420 } 421 422This function does not return any clock object. The new clock has the 423same direction (input or output) as the original one. This function 424only adds a link to the existing clock. In the above example, object B 425remains the only object allowed to use the clock and device A must not 426try to change the clock period or set a callback to the clock. This 427diagram describes the example with an input clock:: 428 429 +--------------------------+ 430 | Device A | 431 | +--------------+ | 432 | | Device B | | 433 | | +-------+ | | 434 >>"b_clk">>>| "clk" | | | 435 | (in) | | (in) | | | 436 | | +-------+ | | 437 | +--------------+ | 438 +--------------------------+ 439 440Migration 441--------- 442 443Clock state is not migrated automatically. Every device must handle its 444clock migration. Alias clocks must not be migrated. 445 446To ensure clock states are restored correctly during migration, there 447are two solutions. 448 449Clock states can be migrated by adding an entry into the device 450vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this. 451This is typically used to migrate an input clock state. For example: 452 453.. code-block:: c 454 455 MyDeviceState { 456 DeviceState parent_obj; 457 [...] /* some fields */ 458 Clock *clk; 459 }; 460 461 VMStateDescription my_device_vmstate = { 462 .name = "my_device", 463 .fields = (VMStateField[]) { 464 [...], /* other migrated fields */ 465 VMSTATE_CLOCK(clk, MyDeviceState), 466 VMSTATE_END_OF_LIST() 467 } 468 }; 469 470The second solution is to restore the clock state using information already 471at our disposal. This can be used to restore output clock states using the 472device state. The functions ``clock_set[_ns|_hz]()`` can be used during the 473``post_load()`` migration callback. 474 475When adding clock support to an existing device, if you care about 476migration compatibility you will need to be careful, as simply adding 477a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can 478put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a 479suitable ``needed`` function, and use ``clock_set()`` in a 480``pre_load()`` function to set the default value that will be used if 481the source virtual machine in the migration does not send the clock 482state. 483 484Care should be taken not to use ``clock_update[_ns|_hz]()`` or 485``clock_propagate()`` during the whole migration procedure because it 486will trigger side effects to other devices in an unknown state. 487