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 typedef void ClockCallback(void *opaque);
  26
  27 /*
  28  * clock store a value representing the clock's period in 2^-32ns unit.
  29  * It can represent:
  30  *  + periods from 2^-32ns up to 4seconds
  31  *  + frequency from ~0.25Hz 2e10Ghz
  32  * Resolution of frequency representation decreases with frequency:
  33  * + at 100MHz, resolution is ~2mHz
  34  * + at 1Ghz,   resolution is ~0.2Hz
  35  * + at 10Ghz,  resolution is ~20Hz
  36  */
  37 #define CLOCK_PERIOD_1SEC (1000000000llu << 32)
  38
  39 /*
  40  * macro helpers to convert to hertz / nanosecond
  41  */
  42 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu))
  43 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u)
  44 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
  45
  46 /**
  47  * Clock:
  48  * @parent_obj: parent class
  49  * @period: unsigned integer representing the period of the clock
  50  * @canonical_path: clock path string cache (used for trace purpose)
  51  * @callback: called when clock changes
  52  * @callback_opaque: argument for @callback
  53  * @source: source (or parent in clock tree) of the clock
  54  * @children: list of clocks connected to this one (it is their source)
  55  * @sibling: structure used to form a clock list
  56  */
  57
  58
  59 struct Clock {
  60     /*< private >*/
  61     Object parent_obj;
  62
  63     /* all fields are private and should not be modified directly */
  64
  65     /* fields */
  66     uint64_t period;
  67     char *canonical_path;
  68     ClockCallback *callback;
  69     void *callback_opaque;
  70
  71     /* Clocks are organized in a clock tree */
  72     Clock *source;
  73     QLIST_HEAD(, Clock) children;
  74     QLIST_ENTRY(Clock) sibling;
  75 };
  76
  77 /*
  78  * vmstate description entry to be added in device vmsd.
  79  */
  80 extern const VMStateDescription vmstate_clock;
  81 #define VMSTATE_CLOCK(field, state) \
  82     VMSTATE_CLOCK_V(field, state, 0)
  83 #define VMSTATE_CLOCK_V(field, state, version) \
  84     VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
  85 #define VMSTATE_ARRAY_CLOCK(field, state, num) \
  86     VMSTATE_ARRAY_CLOCK_V(field, state, num, 0)
  87 #define VMSTATE_ARRAY_CLOCK_V(field, state, num, version)          \
  88     VMSTATE_ARRAY_OF_POINTER_TO_STRUCT(field, state, num, version, \
  89                                        vmstate_clock, Clock)
  90
  91 /**
  92  * clock_setup_canonical_path:
  93  * @clk: clock
  94  *
  95  * compute the canonical path of the clock (used by log messages)
  96  */
  97 void clock_setup_canonical_path(Clock *clk);
  98
  99 /**
 100  * clock_new:
 101  * @parent: the clock parent
 102  * @name: the clock object name
 103  *
 104  * Helper function to create a new clock and parent it to @parent. There is no
 105  * need to call clock_setup_canonical_path on the returned clock as it is done
 106  * by this function.
 107  *
 108  * @return the newly created clock
 109  */
 110 Clock *clock_new(Object *parent, const char *name);
 111
 112 /**
 113  * clock_set_callback:
 114  * @clk: the clock to register the callback into
 115  * @cb: the callback function
 116  * @opaque: the argument to the callback
 117  *
 118  * Register a callback called on every clock update.
 119  */
 120 void clock_set_callback(Clock *clk, ClockCallback *cb, void *opaque);
 121
 122 /**
 123  * clock_clear_callback:
 124  * @clk: the clock to delete the callback from
 125  *
 126  * Unregister the callback registered with clock_set_callback.
 127  */
 128 void clock_clear_callback(Clock *clk);
 129
 130 /**
 131  * clock_set_source:
 132  * @clk: the clock.
 133  * @src: the source clock
 134  *
 135  * Setup @src as the clock source of @clk. The current @src period
 136  * value is also copied to @clk and its subtree but no callback is
 137  * called.
 138  * Further @src update will be propagated to @clk and its subtree.
 139  */
 140 void clock_set_source(Clock *clk, Clock *src);
 141
 142 /**
 143  * clock_has_source:
 144  * @clk: the clock
 145  *
 146  * Returns true if the clock has a source clock connected to it.
 147  * This is useful for devices which have input clocks which must
 148  * be connected by the board/SoC code which creates them. The
 149  * device code can use this to check in its realize method that
 150  * the clock has been connected.
 151  */
 152 static inline bool clock_has_source(const Clock *clk)
 153 {
 154     return clk->source != NULL;
 155 }
 156
 157 /**
 158  * clock_set:
 159  * @clk: the clock to initialize.
 160  * @value: the clock's value, 0 means unclocked
 161  *
 162  * Set the local cached period value of @clk to @value.
 163  *
 164  * @return: true if the clock is changed.
 165  */
 166 bool clock_set(Clock *clk, uint64_t value);
 167
 168 static inline bool clock_set_hz(Clock *clk, unsigned hz)
 169 {
 170     return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
 171 }
 172
 173 static inline bool clock_set_ns(Clock *clk, unsigned ns)
 174 {
 175     return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
 176 }
 177
 178 /**
 179  * clock_propagate:
 180  * @clk: the clock
 181  *
 182  * Propagate the clock period that has been previously configured using
 183  * @clock_set(). This will update recursively all connected clocks.
 184  * It is an error to call this function on a clock which has a source.
 185  * Note: this function must not be called during device inititialization
 186  * or migration.
 187  */
 188 void clock_propagate(Clock *clk);
 189
 190 /**
 191  * clock_update:
 192  * @clk: the clock to update.
 193  * @value: the new clock's value, 0 means unclocked
 194  *
 195  * Update the @clk to the new @value. All connected clocks will be informed
 196  * of this update. This is equivalent to call @clock_set() then
 197  * @clock_propagate().
 198  */
 199 static inline void clock_update(Clock *clk, uint64_t value)
 200 {
 201     if (clock_set(clk, value)) {
 202         clock_propagate(clk);
 203     }
 204 }
 205
 206 static inline void clock_update_hz(Clock *clk, unsigned hz)
 207 {
 208     clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
 209 }
 210
 211 static inline void clock_update_ns(Clock *clk, unsigned ns)
 212 {
 213     clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
 214 }
 215
 216 /**
 217  * clock_get:
 218  * @clk: the clk to fetch the clock
 219  *
 220  * @return: the current period.
 221  */
 222 static inline uint64_t clock_get(const Clock *clk)
 223 {
 224     return clk->period;
 225 }
 226
 227 static inline unsigned clock_get_hz(Clock *clk)
 228 {
 229     return CLOCK_PERIOD_TO_HZ(clock_get(clk));
 230 }
 231
 232 /**
 233  * clock_ticks_to_ns:
 234  * @clk: the clock to query
 235  * @ticks: number of ticks
 236  *
 237  * Returns the length of time in nanoseconds for this clock
 238  * to tick @ticks times. Because a clock can have a period
 239  * which is not a whole number of nanoseconds, it is important
 240  * to use this function when calculating things like timer
 241  * expiry deadlines, rather than attempting to obtain a "period
 242  * in nanoseconds" value and then multiplying that by a number
 243  * of ticks.
 244  *
 245  * The result could in theory be too large to fit in a 64-bit
 246  * value if the number of ticks and the clock period are both
 247  * large; to avoid overflow the result will be saturated to INT64_MAX
 248  * (because this is the largest valid input to the QEMUTimer APIs).
 249  * Since INT64_MAX nanoseconds is almost 300 years, anything with
 250  * an expiry later than that is in the "will never happen" category
 251  * and callers can reasonably not special-case the saturated result.
 252  */
 253 static inline uint64_t clock_ticks_to_ns(const Clock *clk, uint64_t ticks)
 254 {
 255     uint64_t ns_low, ns_high;
 256
 257     /*
 258      * clk->period is the period in units of 2^-32 ns, so
 259      * (clk->period * ticks) is the required length of time in those
 260      * units, and we can convert to nanoseconds by multiplying by
 261      * 2^32, which is the same as shifting the 128-bit multiplication
 262      * result right by 32.
 263      */
 264     mulu64(&ns_low, &ns_high, clk->period, ticks);
 265     if (ns_high & MAKE_64BIT_MASK(31, 33)) {
 266         return INT64_MAX;
 267     }
 268     return ns_low >> 32 | ns_high << 32;
 269 }
 270
 271 /**
 272  * clock_is_enabled:
 273  * @clk: a clock
 274  *
 275  * @return: true if the clock is running.
 276  */
 277 static inline bool clock_is_enabled(const Clock *clk)
 278 {
 279     return clock_get(clk) != 0;
 280 }
 281
 282 /**
 283  * clock_display_freq: return human-readable representation of clock frequency
 284  * @clk: clock
 285  *
 286  * Return a string which has a human-readable representation of the
 287  * clock's frequency, e.g. "33.3 MHz". This is intended for debug
 288  * and display purposes.
 289  *
 290  * The caller is responsible for freeing the string with g_free().
 291  */
 292 char *clock_display_freq(Clock *clk);
 293
 294 #endif /* QEMU_HW_CLOCK_H */