include/hw/clock.h

   1 /*
   2  * Hardware Clocks
   3  *
   4  * Copyright GreenSocs 2016-2020
   5  *
   6  * Authors:
   7  *  Frederic Konrad
   8  *  Damien Hedde
   9  *
  10  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  11  * See the COPYING file in the top-level directory.
  12  */
  13
  14 #ifndef QEMU_HW_CLOCK_H
  15 #define QEMU_HW_CLOCK_H
  16
  17 #include "qom/object.h"
  18 #include "qemu/queue.h"
  19 #include "qemu/host-utils.h"
  20 #include "qemu/bitops.h"
  21
  22 #define TYPE_CLOCK "clock"
  23 OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK)
  24
  25 /*
  26  * Argument to ClockCallback functions indicating why the callback
  27  * has been called. A mask of these values logically ORed together
  28  * is used to specify which events are interesting when the callback
  29  * is registered, so these values must all be different bit values.
  30  */
  31 typedef enum ClockEvent {
  32     ClockUpdate = 1, /* Clock period has just updated */
  33     ClockPreUpdate = 2, /* Clock period is about to update */
  34 } ClockEvent;
  35
  36 typedef void ClockCallback(void *opaque, ClockEvent event);
  37
  38 /*
  39  * clock store a value representing the clock's period in 2^-32ns unit.
  40  * It can represent:
  41  *  + periods from 2^-32ns up to 4seconds
  42  *  + frequency from ~0.25Hz 2e10Ghz
  43  * Resolution of frequency representation decreases with frequency:
  44  * + at 100MHz, resolution is ~2mHz
  45  * + at 1Ghz,   resolution is ~0.2Hz
  46  * + at 10Ghz,  resolution is ~20Hz
  47  */
  48 #define CLOCK_PERIOD_1SEC (1000000000llu << 32)
  49
  50 /*
  51  * macro helpers to convert to hertz / nanosecond
  52  */
  53 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu))
  54 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u)
  55 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
  56
  57 /**
  58  * Clock:
  59  * @parent_obj: parent class
  60  * @period: unsigned integer representing the period of the clock
  61  * @canonical_path: clock path string cache (used for trace purpose)
  62  * @callback: called when clock changes
  63  * @callback_opaque: argument for @callback
  64  * @callback_events: mask of events when callback should be called
  65  * @source: source (or parent in clock tree) of the clock
  66  * @children: list of clocks connected to this one (it is their source)
  67  * @sibling: structure used to form a clock list
  68  */
  69
  70
  71 struct Clock {
  72     /*< private >*/
  73     Object parent_obj;
  74
  75     /* all fields are private and should not be modified directly */
  76
  77     /* fields */
  78     uint64_t period;
  79     char *canonical_path;
  80     ClockCallback *callback;
  81     void *callback_opaque;
  82     unsigned int callback_events;
  83
  84     /* Clocks are organized in a clock tree */
  85     Clock *source;
  86     QLIST_HEAD(, Clock) children;
  87     QLIST_ENTRY(Clock) sibling;
  88 };
  89
  90 /*
  91  * vmstate description entry to be added in device vmsd.
  92  */
  93 extern const VMStateDescription vmstate_clock;
  94 #define VMSTATE_CLOCK(field, state) \
  95     VMSTATE_CLOCK_V(field, state, 0)
  96 #define VMSTATE_CLOCK_V(field, state, version) \
  97     VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
  98 #define VMSTATE_ARRAY_CLOCK(field, state, num) \
  99     VMSTATE_ARRAY_CLOCK_V(field, state, num, 0)
 100 #define VMSTATE_ARRAY_CLOCK_V(field, state, num, version)          \
 101     VMSTATE_ARRAY_OF_POINTER_TO_STRUCT(field, state, num, version, \
 102                                        vmstate_clock, Clock)
 103
 104 /**
 105  * clock_setup_canonical_path:
 106  * @clk: clock
 107  *
 108  * compute the canonical path of the clock (used by log messages)
 109  */
 110 void clock_setup_canonical_path(Clock *clk);
 111
 112 /**
 113  * clock_new:
 114  * @parent: the clock parent
 115  * @name: the clock object name
 116  *
 117  * Helper function to create a new clock and parent it to @parent. There is no
 118  * need to call clock_setup_canonical_path on the returned clock as it is done
 119  * by this function.
 120  *
 121  * @return the newly created clock
 122  */
 123 Clock *clock_new(Object *parent, const char *name);
 124
 125 /**
 126  * clock_set_callback:
 127  * @clk: the clock to register the callback into
 128  * @cb: the callback function
 129  * @opaque: the argument to the callback
 130  * @events: the events the callback should be called for
 131  *          (logical OR of ClockEvent enum values)
 132  *
 133  * Register a callback called on every clock update.
 134  * Note that a clock has only one callback: you cannot register
 135  * different callback functions for different events.
 136  */
 137 void clock_set_callback(Clock *clk, ClockCallback *cb,
 138                         void *opaque, unsigned int events);
 139
 140 /**
 141  * clock_clear_callback:
 142  * @clk: the clock to delete the callback from
 143  *
 144  * Unregister the callback registered with clock_set_callback.
 145  */
 146 void clock_clear_callback(Clock *clk);
 147
 148 /**
 149  * clock_set_source:
 150  * @clk: the clock.
 151  * @src: the source clock
 152  *
 153  * Setup @src as the clock source of @clk. The current @src period
 154  * value is also copied to @clk and its subtree but no callback is
 155  * called.
 156  * Further @src update will be propagated to @clk and its subtree.
 157  */
 158 void clock_set_source(Clock *clk, Clock *src);
 159
 160 /**
 161  * clock_has_source:
 162  * @clk: the clock
 163  *
 164  * Returns true if the clock has a source clock connected to it.
 165  * This is useful for devices which have input clocks which must
 166  * be connected by the board/SoC code which creates them. The
 167  * device code can use this to check in its realize method that
 168  * the clock has been connected.
 169  */
 170 static inline bool clock_has_source(const Clock *clk)
 171 {
 172     return clk->source != NULL;
 173 }
 174
 175 /**
 176  * clock_set:
 177  * @clk: the clock to initialize.
 178  * @value: the clock's value, 0 means unclocked
 179  *
 180  * Set the local cached period value of @clk to @value.
 181  *
 182  * @return: true if the clock is changed.
 183  */
 184 bool clock_set(Clock *clk, uint64_t value);
 185
 186 static inline bool clock_set_hz(Clock *clk, unsigned hz)
 187 {
 188     return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
 189 }
 190
 191 static inline bool clock_set_ns(Clock *clk, unsigned ns)
 192 {
 193     return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
 194 }
 195
 196 /**
 197  * clock_propagate:
 198  * @clk: the clock
 199  *
 200  * Propagate the clock period that has been previously configured using
 201  * @clock_set(). This will update recursively all connected clocks.
 202  * It is an error to call this function on a clock which has a source.
 203  * Note: this function must not be called during device inititialization
 204  * or migration.
 205  */
 206 void clock_propagate(Clock *clk);
 207
 208 /**
 209  * clock_update:
 210  * @clk: the clock to update.
 211  * @value: the new clock's value, 0 means unclocked
 212  *
 213  * Update the @clk to the new @value. All connected clocks will be informed
 214  * of this update. This is equivalent to call @clock_set() then
 215  * @clock_propagate().
 216  */
 217 static inline void clock_update(Clock *clk, uint64_t value)
 218 {
 219     if (clock_set(clk, value)) {
 220         clock_propagate(clk);
 221     }
 222 }
 223
 224 static inline void clock_update_hz(Clock *clk, unsigned hz)
 225 {
 226     clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
 227 }
 228
 229 static inline void clock_update_ns(Clock *clk, unsigned ns)
 230 {
 231     clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
 232 }
 233
 234 /**
 235  * clock_get:
 236  * @clk: the clk to fetch the clock
 237  *
 238  * @return: the current period.
 239  */
 240 static inline uint64_t clock_get(const Clock *clk)
 241 {
 242     return clk->period;
 243 }
 244
 245 static inline unsigned clock_get_hz(Clock *clk)
 246 {
 247     return CLOCK_PERIOD_TO_HZ(clock_get(clk));
 248 }
 249
 250 /**
 251  * clock_ticks_to_ns:
 252  * @clk: the clock to query
 253  * @ticks: number of ticks
 254  *
 255  * Returns the length of time in nanoseconds for this clock
 256  * to tick @ticks times. Because a clock can have a period
 257  * which is not a whole number of nanoseconds, it is important
 258  * to use this function when calculating things like timer
 259  * expiry deadlines, rather than attempting to obtain a "period
 260  * in nanoseconds" value and then multiplying that by a number
 261  * of ticks.
 262  *
 263  * The result could in theory be too large to fit in a 64-bit
 264  * value if the number of ticks and the clock period are both
 265  * large; to avoid overflow the result will be saturated to INT64_MAX
 266  * (because this is the largest valid input to the QEMUTimer APIs).
 267  * Since INT64_MAX nanoseconds is almost 300 years, anything with
 268  * an expiry later than that is in the "will never happen" category
 269  * and callers can reasonably not special-case the saturated result.
 270  */
 271 static inline uint64_t clock_ticks_to_ns(const Clock *clk, uint64_t ticks)
 272 {
 273     uint64_t ns_low, ns_high;
 274
 275     /*
 276      * clk->period is the period in units of 2^-32 ns, so
 277      * (clk->period * ticks) is the required length of time in those
 278      * units, and we can convert to nanoseconds by multiplying by
 279      * 2^32, which is the same as shifting the 128-bit multiplication
 280      * result right by 32.
 281      */
 282     mulu64(&ns_low, &ns_high, clk->period, ticks);
 283     if (ns_high & MAKE_64BIT_MASK(31, 33)) {
 284         return INT64_MAX;
 285     }
 286     return ns_low >> 32 | ns_high << 32;
 287 }
 288
 289 /**
 290  * clock_ns_to_ticks:
 291  * @clk: the clock to query
 292  * @ns: duration in nanoseconds
 293  *
 294  * Returns the number of ticks this clock would make in the given
 295  * number of nanoseconds. Because a clock can have a period which
 296  * is not a whole number of nanoseconds, it is important to use this
 297  * function rather than attempting to obtain a "period in nanoseconds"
 298  * value and then dividing the duration by that value.
 299  *
 300  * If the clock is stopped (ie it has period zero), returns 0.
 301  *
 302  * For some inputs the result could overflow a 64-bit value (because
 303  * the clock's period is short and the duration is long). In these
 304  * cases we truncate the result to a 64-bit value. This is on the
 305  * assumption that generally the result is going to be used to report
 306  * a 32-bit or 64-bit guest register value, so wrapping either cannot
 307  * happen or is the desired behaviour.
 308  */
 309 static inline uint64_t clock_ns_to_ticks(const Clock *clk, uint64_t ns)
 310 {
 311     /*
 312      * ticks = duration_in_ns / period_in_ns
 313      *       = ns / (period / 2^32)
 314      *       = (ns * 2^32) / period
 315      * The hi, lo inputs to divu128() are (ns << 32) as a 128 bit value.
 316      */
 317     uint64_t lo = ns << 32;
 318     uint64_t hi = ns >> 32;
 319     if (clk->period == 0) {
 320         return 0;
 321     }
 322     /*
 323      * Ignore divu128() return value as we've caught div-by-zero and don't
 324      * need different behaviour for overflow.
 325      */
 326     divu128(&lo, &hi, clk->period);
 327     return lo;
 328 }
 329
 330 /**
 331  * clock_is_enabled:
 332  * @clk: a clock
 333  *
 334  * @return: true if the clock is running.
 335  */
 336 static inline bool clock_is_enabled(const Clock *clk)
 337 {
 338     return clock_get(clk) != 0;
 339 }
 340
 341 /**
 342  * clock_display_freq: return human-readable representation of clock frequency
 343  * @clk: clock
 344  *
 345  * Return a string which has a human-readable representation of the
 346  * clock's frequency, e.g. "33.3 MHz". This is intended for debug
 347  * and display purposes.
 348  *
 349  * The caller is responsible for freeing the string with g_free().
 350  */
 351 char *clock_display_freq(Clock *clk);
 352
 353 #endif /* QEMU_HW_CLOCK_H */