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
  20 #define TYPE_CLOCK "clock"
  21 OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK)
  22
  23 typedef void ClockCallback(void *opaque);
  24
  25 /*
  26  * clock store a value representing the clock's period in 2^-32ns unit.
  27  * It can represent:
  28  *  + periods from 2^-32ns up to 4seconds
  29  *  + frequency from ~0.25Hz 2e10Ghz
  30  * Resolution of frequency representation decreases with frequency:
  31  * + at 100MHz, resolution is ~2mHz
  32  * + at 1Ghz,   resolution is ~0.2Hz
  33  * + at 10Ghz,  resolution is ~20Hz
  34  */
  35 #define CLOCK_PERIOD_1SEC (1000000000llu << 32)
  36
  37 /*
  38  * macro helpers to convert to hertz / nanosecond
  39  */
  40 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu))
  41 #define CLOCK_PERIOD_TO_NS(per) ((per) / (CLOCK_PERIOD_1SEC / 1000000000llu))
  42 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u)
  43 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u)
  44
  45 /**
  46  * Clock:
  47  * @parent_obj: parent class
  48  * @period: unsigned integer representing the period of the clock
  49  * @canonical_path: clock path string cache (used for trace purpose)
  50  * @callback: called when clock changes
  51  * @callback_opaque: argument for @callback
  52  * @source: source (or parent in clock tree) of the clock
  53  * @children: list of clocks connected to this one (it is their source)
  54  * @sibling: structure used to form a clock list
  55  */
  56
  57
  58 struct Clock {
  59     /*< private >*/
  60     Object parent_obj;
  61
  62     /* all fields are private and should not be modified directly */
  63
  64     /* fields */
  65     uint64_t period;
  66     char *canonical_path;
  67     ClockCallback *callback;
  68     void *callback_opaque;
  69
  70     /* Clocks are organized in a clock tree */
  71     Clock *source;
  72     QLIST_HEAD(, Clock) children;
  73     QLIST_ENTRY(Clock) sibling;
  74 };
  75
  76 /*
  77  * vmstate description entry to be added in device vmsd.
  78  */
  79 extern const VMStateDescription vmstate_clock;
  80 #define VMSTATE_CLOCK(field, state) \
  81     VMSTATE_CLOCK_V(field, state, 0)
  82 #define VMSTATE_CLOCK_V(field, state, version) \
  83     VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock)
  84 #define VMSTATE_ARRAY_CLOCK(field, state, num) \
  85     VMSTATE_ARRAY_CLOCK_V(field, state, num, 0)
  86 #define VMSTATE_ARRAY_CLOCK_V(field, state, num, version)          \
  87     VMSTATE_ARRAY_OF_POINTER_TO_STRUCT(field, state, num, version, \
  88                                        vmstate_clock, Clock)
  89
  90 /**
  91  * clock_setup_canonical_path:
  92  * @clk: clock
  93  *
  94  * compute the canonical path of the clock (used by log messages)
  95  */
  96 void clock_setup_canonical_path(Clock *clk);
  97
  98 /**
  99  * clock_new:
 100  * @parent: the clock parent
 101  * @name: the clock object name
 102  *
 103  * Helper function to create a new clock and parent it to @parent. There is no
 104  * need to call clock_setup_canonical_path on the returned clock as it is done
 105  * by this function.
 106  *
 107  * @return the newly created clock
 108  */
 109 Clock *clock_new(Object *parent, const char *name);
 110
 111 /**
 112  * clock_set_callback:
 113  * @clk: the clock to register the callback into
 114  * @cb: the callback function
 115  * @opaque: the argument to the callback
 116  *
 117  * Register a callback called on every clock update.
 118  */
 119 void clock_set_callback(Clock *clk, ClockCallback *cb, void *opaque);
 120
 121 /**
 122  * clock_clear_callback:
 123  * @clk: the clock to delete the callback from
 124  *
 125  * Unregister the callback registered with clock_set_callback.
 126  */
 127 void clock_clear_callback(Clock *clk);
 128
 129 /**
 130  * clock_set_source:
 131  * @clk: the clock.
 132  * @src: the source clock
 133  *
 134  * Setup @src as the clock source of @clk. The current @src period
 135  * value is also copied to @clk and its subtree but no callback is
 136  * called.
 137  * Further @src update will be propagated to @clk and its subtree.
 138  */
 139 void clock_set_source(Clock *clk, Clock *src);
 140
 141 /**
 142  * clock_set:
 143  * @clk: the clock to initialize.
 144  * @value: the clock's value, 0 means unclocked
 145  *
 146  * Set the local cached period value of @clk to @value.
 147  *
 148  * @return: true if the clock is changed.
 149  */
 150 bool clock_set(Clock *clk, uint64_t value);
 151
 152 static inline bool clock_set_hz(Clock *clk, unsigned hz)
 153 {
 154     return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
 155 }
 156
 157 static inline bool clock_set_ns(Clock *clk, unsigned ns)
 158 {
 159     return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
 160 }
 161
 162 /**
 163  * clock_propagate:
 164  * @clk: the clock
 165  *
 166  * Propagate the clock period that has been previously configured using
 167  * @clock_set(). This will update recursively all connected clocks.
 168  * It is an error to call this function on a clock which has a source.
 169  * Note: this function must not be called during device inititialization
 170  * or migration.
 171  */
 172 void clock_propagate(Clock *clk);
 173
 174 /**
 175  * clock_update:
 176  * @clk: the clock to update.
 177  * @value: the new clock's value, 0 means unclocked
 178  *
 179  * Update the @clk to the new @value. All connected clocks will be informed
 180  * of this update. This is equivalent to call @clock_set() then
 181  * @clock_propagate().
 182  */
 183 static inline void clock_update(Clock *clk, uint64_t value)
 184 {
 185     if (clock_set(clk, value)) {
 186         clock_propagate(clk);
 187     }
 188 }
 189
 190 static inline void clock_update_hz(Clock *clk, unsigned hz)
 191 {
 192     clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
 193 }
 194
 195 static inline void clock_update_ns(Clock *clk, unsigned ns)
 196 {
 197     clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
 198 }
 199
 200 /**
 201  * clock_get:
 202  * @clk: the clk to fetch the clock
 203  *
 204  * @return: the current period.
 205  */
 206 static inline uint64_t clock_get(const Clock *clk)
 207 {
 208     return clk->period;
 209 }
 210
 211 static inline unsigned clock_get_hz(Clock *clk)
 212 {
 213     return CLOCK_PERIOD_TO_HZ(clock_get(clk));
 214 }
 215
 216 static inline unsigned clock_get_ns(Clock *clk)
 217 {
 218     return CLOCK_PERIOD_TO_NS(clock_get(clk));
 219 }
 220
 221 /**
 222  * clock_is_enabled:
 223  * @clk: a clock
 224  *
 225  * @return: true if the clock is running.
 226  */
 227 static inline bool clock_is_enabled(const Clock *clk)
 228 {
 229     return clock_get(clk) != 0;
 230 }
 231
 232 #endif /* QEMU_HW_CLOCK_H */