| 1 | Modelling a clock tree in QEMU |
| 2 | ============================== |
| 3 | |
| 4 | What are clocks? |
| 5 | ---------------- |
| 6 | |
| 7 | Clocks are QOM objects developed for the purpose of modelling the |
| 8 | distribution of clocks in QEMU. |
| 9 | |
| 10 | They allow us to model the clock distribution of a platform and detect |
| 11 | configuration errors in the clock tree such as badly configured PLL, clock |
| 12 | source selection or disabled clock. |
| 13 | |
| 14 | The object is *Clock* and its QOM name is ``clock`` (in C code, the macro |
| 15 | ``TYPE_CLOCK``). |
| 16 | |
| 17 | Clocks are typically used with devices where they are used to model inputs |
| 18 | and outputs. They are created in a similar way to GPIOs. Inputs and outputs |
| 19 | of different devices can be connected together. |
| 20 | |
| 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. |
| 25 | |
| 26 | Here 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 | |
| 49 | Clocks are defined in the ``include/hw/core/clock.h`` header and device |
| 50 | related functions are defined in the ``include/hw/core/qdev-clock.h`` |
| 51 | header. |
| 52 | |
| 53 | The clock state |
| 54 | --------------- |
| 55 | |
| 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 |
| 58 | represent the clock being inactive or gated. The clocks do not model |
| 59 | the signal itself (pin toggling) or other properties such as the duty |
| 60 | cycle. |
| 61 | |
| 62 | All clocks contain this state: outputs as well as inputs. This allows |
| 63 | the current period of a clock to be fetched at any time. When a clock |
| 64 | is updated, the value is immediately propagated to all connected |
| 65 | clocks in the tree. |
| 66 | |
| 67 | To ease interaction with clocks, helpers with a unit suffix are defined for |
| 68 | every clock state setter or getter. The suffixes are: |
| 69 | |
| 70 | - ``_ns`` for handling periods in nanoseconds |
| 71 | - ``_hz`` for handling frequencies in hertz |
| 72 | |
| 73 | The 0 period value is converted to 0 in hertz and vice versa. 0 always means |
| 74 | that the clock is disabled. |
| 75 | |
| 76 | Adding a new clock |
| 77 | ------------------ |
| 78 | |
| 79 | Adding clocks to a device must be done during the init method of the Device |
| 80 | instance. |
| 81 | |
| 82 | To add an input clock to a device, the function ``qdev_init_clock_in()`` |
| 83 | must be used. It takes the name, a callback, an opaque parameter |
| 84 | for the callback and a mask of events when the callback should be |
| 85 | called (this will be explained in a following section). |
| 86 | Output 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 | |
| 91 | Both functions return the created Clock pointer, which should be saved in the |
| 92 | device's state structure for further use. |
| 93 | |
| 94 | These objects will be automatically deleted by the QOM reference mechanism. |
| 95 | |
| 96 | Note that it is possible to create a static array describing clock inputs and |
| 97 | outputs. The function ``qdev_init_clocks()`` must be called with the array as |
| 98 | parameter 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 |
| 100 | construction, some macros are defined in ``include/hw/core/qdev-clock.h``. |
| 101 | As an example, the following creates 2 clocks to a device: one input and one |
| 102 | output. |
| 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 | |
| 143 | An alternative way to create a clock is to simply call |
| 144 | ``object_new(TYPE_CLOCK)``. In that case the clock will neither be an |
| 145 | input nor an output of a device. After the whole QOM hierarchy of the |
| 146 | clock has been set ``clock_setup_canonical_path()`` should be called. |
| 147 | |
| 148 | At creation, the period of the clock is 0: the clock is disabled. You can |
| 149 | change it using ``clock_set_ns()`` or ``clock_set_hz()``. |
| 150 | |
| 151 | Note that if you are creating a clock with a fixed period which will never |
| 152 | change (for example the main clock source of a board), then you'll have |
| 153 | nothing else to do. This value will be propagated to other clocks when |
| 154 | connecting the clocks together and devices will fetch the right value during |
| 155 | the first reset. |
| 156 | |
| 157 | Clock callbacks |
| 158 | --------------- |
| 159 | |
| 160 | You 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 | |
| 167 | The callback function must be of this type: |
| 168 | |
| 169 | .. code-block:: c |
| 170 | |
| 171 | typedef void ClockCallback(void *opaque, ClockEvent event); |
| 172 | |
| 173 | The ``opaque`` argument is the pointer passed to ``qdev_init_clock_in()`` |
| 174 | or ``clock_set_callback()``; for ``qdev_init_clocks()`` it is the |
| 175 | ``dev`` device pointer. |
| 176 | |
| 177 | The ``event`` argument specifies why the callback has been called. |
| 178 | When you register the callback you specify a mask of ClockEvent values |
| 179 | that you are interested in. The callback will only be called for those |
| 180 | events. |
| 181 | |
| 182 | The events currently supported are: |
| 183 | |
| 184 | * ``ClockPreUpdate`` : called when the input clock's period is about to |
| 185 | update. This is useful if the device needs to do some action for |
| 186 | which it needs to know the old value of the clock period. During |
| 187 | this callback, Clock API functions like ``clock_get()`` or |
| 188 | ``clock_ticks_to_ns()`` will use the old period. |
| 189 | * ``ClockUpdate`` : called after the input clock's period has changed. |
| 190 | During this callback, Clock API functions like ``clock_ticks_to_ns()`` |
| 191 | will use the new period. |
| 192 | |
| 193 | Note that a clock only has one callback: it is not possible to register |
| 194 | different functions for different events. You must register a single |
| 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. |
| 197 | |
| 198 | Retrieving clocks from a device |
| 199 | ------------------------------- |
| 200 | |
| 201 | ``qdev_get_clock_in()`` and ``dev_get_clock_out()`` are available to |
| 202 | get the clock inputs or outputs of a device. For example: |
| 203 | |
| 204 | .. code-block:: c |
| 205 | |
| 206 | Clock *clk = qdev_get_clock_in(DEVICE(mydev), "clk_in"); |
| 207 | |
| 208 | or: |
| 209 | |
| 210 | .. code-block:: c |
| 211 | |
| 212 | Clock *clk = qdev_get_clock_out(DEVICE(mydev), "clk_out"); |
| 213 | |
| 214 | Connecting two clocks together |
| 215 | ------------------------------ |
| 216 | |
| 217 | To connect two clocks together, use the ``clock_set_source()`` function. |
| 218 | Given two clocks ``clk1``, and ``clk2``, ``clock_set_source(clk2, clk1);`` |
| 219 | configures ``clk2`` to follow the ``clk1`` period changes. Every time ``clk1`` |
| 220 | is updated, ``clk2`` will be updated too. |
| 221 | |
| 222 | When connecting clock between devices, prefer using the |
| 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: |
| 226 | |
| 227 | .. code-block:: c |
| 228 | |
| 229 | qdev_connect_clock_in(devB, "clk2", qdev_get_clock_out(devA, "clk1")) |
| 230 | |
| 231 | We used ``qdev_get_clock_out()`` above, but any clock can drive an |
| 232 | input clock, even another input clock. The following diagram shows |
| 233 | some examples of connections. Note also that a clock can drive several |
| 234 | other clocks. |
| 235 | |
| 236 | :: |
| 237 | |
| 238 | +------------+ +--------------------------------------------------+ |
| 239 | | Device A | | Device B | |
| 240 | | | | +---------------------+ | |
| 241 | | | | | Device C | | |
| 242 | | +-------+ | | +-------+ | +-------+ +-------+ | +-------+ | |
| 243 | | |Clock 1|>>-->>|Clock 2|>>+-->>|Clock 3| |Clock 5|>>>>|Clock 6|>> |
| 244 | | | (out) | | | | (in) | | | | (in) | | (out) | | | (out) | | |
| 245 | | +-------+ | | +-------+ | | +-------+ +-------+ | +-------+ | |
| 246 | +------------+ | | +---------------------+ | |
| 247 | | | | |
| 248 | | | +--------------+ | |
| 249 | | | | Device D | | |
| 250 | | | | +-------+ | | |
| 251 | | +-->>|Clock 4| | | |
| 252 | | | | (in) | | | |
| 253 | | | +-------+ | | |
| 254 | | +--------------+ | |
| 255 | +--------------------------------------------------+ |
| 256 | |
| 257 | In the above example, when *Clock 1* is updated by *Device A*, three |
| 258 | clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*. |
| 259 | |
| 260 | It is not possible to disconnect a clock or to change the clock connection |
| 261 | after it is connected. |
| 262 | |
| 263 | Clock multiplier and divider settings |
| 264 | ------------------------------------- |
| 265 | |
| 266 | By default, when clocks are connected together, the child |
| 267 | clocks run with the same period as their source (parent) clock. |
| 268 | The Clock API supports a built-in period multiplier/divider |
| 269 | mechanism so you can configure a clock to make its children |
| 270 | run at a different period from its own. If you call the |
| 271 | ``clock_set_mul_div()`` function you can specify the clock's |
| 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 |
| 275 | multiplier to 2 and its divider to 3, the child clocks will run |
| 276 | at 12MHz. |
| 277 | |
| 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. |
| 281 | |
| 282 | Similarly to ``clock_set()``, ``clock_set_mul_div()`` returns ``true`` if |
| 283 | the clock state was modified; that is, if the multiplier or the diviser |
| 284 | or both were changed by the call. |
| 285 | |
| 286 | Note that ``clock_set_mul_div()`` does not automatically call |
| 287 | ``clock_propagate()``. If you make a runtime change to the |
| 288 | multiplier or divider you must call clock_propagate() yourself. |
| 289 | |
| 290 | Unconnected input clocks |
| 291 | ------------------------ |
| 292 | |
| 293 | A newly created input clock is disabled (period of 0). This means the |
| 294 | clock will be considered as disabled until the period is updated. If |
| 295 | the clock remains unconnected it will always keep its initial value |
| 296 | of 0. If this is not the desired behaviour, ``clock_set()``, |
| 297 | ``clock_set_ns()`` or ``clock_set_hz()`` should be called on the Clock |
| 298 | object during device instance init. For example: |
| 299 | |
| 300 | .. code-block:: c |
| 301 | |
| 302 | clk = qdev_init_clock_in(DEVICE(dev), "clk-in", clk_in_callback, |
| 303 | dev, ClockUpdate); |
| 304 | /* set initial value to 10ns / 100MHz */ |
| 305 | clock_set_ns(clk, 10); |
| 306 | |
| 307 | To enforce that the clock is wired up by the board code, you can |
| 308 | call ``clock_has_source()`` in your device's realize method: |
| 309 | |
| 310 | .. code-block:: c |
| 311 | |
| 312 | if (!clock_has_source(s->clk)) { |
| 313 | error_setg(errp, "MyDevice: clk input must be connected"); |
| 314 | return; |
| 315 | } |
| 316 | |
| 317 | Note that this only checks that the clock has been wired up; it is |
| 318 | still possible that the output clock connected to it is disabled |
| 319 | or has not yet been configured, in which case the period will be |
| 320 | zero. You should use the clock callback to find out when the clock |
| 321 | period changes. |
| 322 | |
| 323 | Fetching clock frequency/period |
| 324 | ------------------------------- |
| 325 | |
| 326 | To get the current state of a clock, use the functions ``clock_get()`` |
| 327 | or ``clock_get_hz()``. |
| 328 | |
| 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 |
| 332 | be more convenient; see the section below on expiry deadlines.) |
| 333 | |
| 334 | ``clock_get_hz()`` returns the frequency of the clock, rounded to the |
| 335 | next lowest integer. This implies some inaccuracy due to the rounding, |
| 336 | so be cautious about using it in calculations. |
| 337 | |
| 338 | It is also possible to register a callback on clock frequency changes. |
| 339 | Here is an example, which assumes that ``clock_callback`` has been |
| 340 | specified as the callback for the ``ClockUpdate`` event: |
| 341 | |
| 342 | .. code-block:: c |
| 343 | |
| 344 | void clock_callback(void *opaque, ClockEvent event) { |
| 345 | MyDeviceState *s = (MyDeviceState *) opaque; |
| 346 | /* |
| 347 | * 'opaque' is the argument passed to qdev_init_clock_in(); |
| 348 | * usually this will be the device state pointer. |
| 349 | */ |
| 350 | |
| 351 | /* do something with the new period */ |
| 352 | fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n", |
| 353 | clock_get(dev->my_clk_input)); |
| 354 | } |
| 355 | |
| 356 | If you are only interested in the frequency for displaying it to |
| 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. |
| 360 | |
| 361 | It's also possible to retrieve the clock period from a QTest by |
| 362 | accessing QOM property ``qtest-clock-period`` using a QMP command. |
| 363 | This property is only present when the device is being run under |
| 364 | the ``qtest`` accelerator; it is not available when QEMU is |
| 365 | being run normally. |
| 366 | |
| 367 | Calculating expiry deadlines |
| 368 | ---------------------------- |
| 369 | |
| 370 | A commonly required operation for a clock is to calculate how long |
| 371 | it will take for the clock to tick N times; this can then be used |
| 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. |
| 375 | |
| 376 | It is important not to try to calculate expiry deadlines using a |
| 377 | shortcut like multiplying a "period of clock in nanoseconds" value |
| 378 | by the tick count, because clocks can have periods which are not a |
| 379 | whole number of nanoseconds, and the accumulated error in the |
| 380 | multiplication can be significant. |
| 381 | |
| 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()`` |
| 385 | saturates the result to INT64_MAX (because this is the largest valid |
| 386 | input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost |
| 387 | 300 years, anything with an expiry later than that is in the "will |
| 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. |
| 391 | (If you are performing further calculations on the returned value |
| 392 | rather than simply passing it to a QEMUTimer function like |
| 393 | ``timer_mod_ns()`` then you should be careful to avoid overflow |
| 394 | in those calculations, of course.) |
| 395 | |
| 396 | Obtaining tick counts |
| 397 | --------------------- |
| 398 | |
| 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 |
| 402 | potential rounding errors. It will return '0' if the clock is stopped |
| 403 | (i.e. it has period zero). If the inputs imply a tick count that |
| 404 | overflows a 64-bit value (a very long duration for a clock with a |
| 405 | very short period) the output value is truncated, so effectively |
| 406 | the 64-bit output wraps around. |
| 407 | |
| 408 | Changing a clock period |
| 409 | ----------------------- |
| 410 | |
| 411 | A device can change its outputs using the ``clock_update()``, |
| 412 | ``clock_update_ns()`` or ``clock_update_hz()`` function. It will trigger |
| 413 | updates on every connected input. |
| 414 | |
| 415 | For example, let's say that we have an output clock *clkout* and we |
| 416 | have a pointer to it in the device state because we did the following |
| 417 | in init phase: |
| 418 | |
| 419 | .. code-block:: c |
| 420 | |
| 421 | dev->clkout = qdev_init_clock_out(DEVICE(dev), "clkout"); |
| 422 | |
| 423 | Then at any time (apart from the cases listed below), it is possible to |
| 424 | change the clock value by doing: |
| 425 | |
| 426 | .. code-block:: c |
| 427 | |
| 428 | clock_update_hz(dev->clkout, 1000 * 1000 * 1000); /* 1GHz */ |
| 429 | |
| 430 | Because updating a clock may trigger any side effects through |
| 431 | connected clocks and their callbacks, this operation must be done |
| 432 | while holding the qemu io lock. |
| 433 | |
| 434 | For the same reason, one can update clocks only when it is allowed to have |
| 435 | side effects on other objects. In consequence, it is forbidden: |
| 436 | |
| 437 | * during migration, |
| 438 | * and in the enter phase of reset. |
| 439 | |
| 440 | Note that calling ``clock_update[_ns|_hz]()`` is equivalent to calling |
| 441 | ``clock_set[_ns|_hz]()`` (with the same arguments) then |
| 442 | ``clock_propagate()`` on the clock. Thus, setting the clock value can |
| 443 | be separated from triggering the side-effects. This is often required |
| 444 | to factorize code to handle reset and migration in devices. |
| 445 | |
| 446 | Aliasing clocks |
| 447 | --------------- |
| 448 | |
| 449 | Sometimes, one needs to forward, or inherit, a clock from another |
| 450 | device. Typically, when doing device composition, a device might |
| 451 | expose a sub-device's clock without interfering with it. The function |
| 452 | ``qdev_alias_clock()`` can be used to achieve this behaviour. Note |
| 453 | that it is possible to expose the clock under a different name. |
| 454 | ``qdev_alias_clock()`` works for both input and output clocks. |
| 455 | |
| 456 | For example, if device B is a child of device A, |
| 457 | ``device_a_instance_init()`` may do something like this: |
| 458 | |
| 459 | .. code-block:: c |
| 460 | |
| 461 | void device_a_instance_init(Object *obj) |
| 462 | { |
| 463 | AState *A = DEVICE_A(obj); |
| 464 | BState *B; |
| 465 | /* create object B as child of A */ |
| 466 | [...] |
| 467 | qdev_alias_clock(B, "clk", A, "b_clk"); |
| 468 | /* |
| 469 | * Now A has a clock "b_clk" which is an alias to |
| 470 | * the clock "clk" of its child B. |
| 471 | */ |
| 472 | } |
| 473 | |
| 474 | This function does not return any clock object. The new clock has the |
| 475 | same direction (input or output) as the original one. This function |
| 476 | only adds a link to the existing clock. In the above example, object B |
| 477 | remains the only object allowed to use the clock and device A must not |
| 478 | try to change the clock period or set a callback to the clock. This |
| 479 | diagram describes the example with an input clock:: |
| 480 | |
| 481 | +--------------------------+ |
| 482 | | Device A | |
| 483 | | +--------------+ | |
| 484 | | | Device B | | |
| 485 | | | +-------+ | | |
| 486 | >>"b_clk">>>| "clk" | | | |
| 487 | | (in) | | (in) | | | |
| 488 | | | +-------+ | | |
| 489 | | +--------------+ | |
| 490 | +--------------------------+ |
| 491 | |
| 492 | Migration |
| 493 | --------- |
| 494 | |
| 495 | Clock state is not migrated automatically. Every device must handle its |
| 496 | clock migration. Alias clocks must not be migrated. |
| 497 | |
| 498 | To ensure clock states are restored correctly during migration, there |
| 499 | are two solutions. |
| 500 | |
| 501 | Clock states can be migrated by adding an entry into the device |
| 502 | vmstate description. You should use the ``VMSTATE_CLOCK`` macro for this. |
| 503 | This is typically used to migrate an input clock state. For example: |
| 504 | |
| 505 | .. code-block:: c |
| 506 | |
| 507 | MyDeviceState { |
| 508 | DeviceState parent_obj; |
| 509 | [...] /* some fields */ |
| 510 | Clock *clk; |
| 511 | }; |
| 512 | |
| 513 | VMStateDescription my_device_vmstate = { |
| 514 | .name = "my_device", |
| 515 | .fields = (const VMStateField[]) { |
| 516 | [...], /* other migrated fields */ |
| 517 | VMSTATE_CLOCK(clk, MyDeviceState), |
| 518 | VMSTATE_END_OF_LIST() |
| 519 | } |
| 520 | }; |
| 521 | |
| 522 | The second solution is to restore the clock state using information already |
| 523 | at our disposal. This can be used to restore output clock states using the |
| 524 | device state. The functions ``clock_set[_ns|_hz]()`` can be used during the |
| 525 | ``post_load()`` migration callback. |
| 526 | |
| 527 | When adding clock support to an existing device, if you care about |
| 528 | migration compatibility you will need to be careful, as simply adding |
| 529 | a ``VMSTATE_CLOCK()`` line will break compatibility. Instead, you can |
| 530 | put the ``VMSTATE_CLOCK()`` line into a vmstate subsection with a |
| 531 | suitable ``needed`` function, and use ``clock_set()`` in a |
| 532 | ``pre_load()`` function to set the default value that will be used if |
| 533 | the source virtual machine in the migration does not send the clock |
| 534 | state. |
| 535 | |
| 536 | Care should be taken not to use ``clock_update[_ns|_hz]()`` or |
| 537 | ``clock_propagate()`` during the whole migration procedure because it |
| 538 | will trigger side effects to other devices in an unknown state. |