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
  85 /**
  86  * clock_setup_canonical_path:
  87  * @clk: clock
  88  *
  89  * compute the canonical path of the clock (used by log messages)
  90  */
  91 void clock_setup_canonical_path(Clock *clk);
  92
  93 /**
  94  * clock_new:
  95  * @parent: the clock parent
  96  * @name: the clock object name
  97  *
  98  * Helper function to create a new clock and parent it to @parent. There is no
  99  * need to call clock_setup_canonical_path on the returned clock as it is done
 100  * by this function.
 101  *
 102  * @return the newly created clock
 103  */
 104 Clock *clock_new(Object *parent, const char *name);
 105
 106 /**
 107  * clock_set_callback:
 108  * @clk: the clock to register the callback into
 109  * @cb: the callback function
 110  * @opaque: the argument to the callback
 111  *
 112  * Register a callback called on every clock update.
 113  */
 114 void clock_set_callback(Clock *clk, ClockCallback *cb, void *opaque);
 115
 116 /**
 117  * clock_clear_callback:
 118  * @clk: the clock to delete the callback from
 119  *
 120  * Unregister the callback registered with clock_set_callback.
 121  */
 122 void clock_clear_callback(Clock *clk);
 123
 124 /**
 125  * clock_set_source:
 126  * @clk: the clock.
 127  * @src: the source clock
 128  *
 129  * Setup @src as the clock source of @clk. The current @src period
 130  * value is also copied to @clk and its subtree but no callback is
 131  * called.
 132  * Further @src update will be propagated to @clk and its subtree.
 133  */
 134 void clock_set_source(Clock *clk, Clock *src);
 135
 136 /**
 137  * clock_set:
 138  * @clk: the clock to initialize.
 139  * @value: the clock's value, 0 means unclocked
 140  *
 141  * Set the local cached period value of @clk to @value.
 142  *
 143  * @return: true if the clock is changed.
 144  */
 145 bool clock_set(Clock *clk, uint64_t value);
 146
 147 static inline bool clock_set_hz(Clock *clk, unsigned hz)
 148 {
 149     return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz));
 150 }
 151
 152 static inline bool clock_set_ns(Clock *clk, unsigned ns)
 153 {
 154     return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns));
 155 }
 156
 157 /**
 158  * clock_propagate:
 159  * @clk: the clock
 160  *
 161  * Propagate the clock period that has been previously configured using
 162  * @clock_set(). This will update recursively all connected clocks.
 163  * It is an error to call this function on a clock which has a source.
 164  * Note: this function must not be called during device inititialization
 165  * or migration.
 166  */
 167 void clock_propagate(Clock *clk);
 168
 169 /**
 170  * clock_update:
 171  * @clk: the clock to update.
 172  * @value: the new clock's value, 0 means unclocked
 173  *
 174  * Update the @clk to the new @value. All connected clocks will be informed
 175  * of this update. This is equivalent to call @clock_set() then
 176  * @clock_propagate().
 177  */
 178 static inline void clock_update(Clock *clk, uint64_t value)
 179 {
 180     if (clock_set(clk, value)) {
 181         clock_propagate(clk);
 182     }
 183 }
 184
 185 static inline void clock_update_hz(Clock *clk, unsigned hz)
 186 {
 187     clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz));
 188 }
 189
 190 static inline void clock_update_ns(Clock *clk, unsigned ns)
 191 {
 192     clock_update(clk, CLOCK_PERIOD_FROM_NS(ns));
 193 }
 194
 195 /**
 196  * clock_get:
 197  * @clk: the clk to fetch the clock
 198  *
 199  * @return: the current period.
 200  */
 201 static inline uint64_t clock_get(const Clock *clk)
 202 {
 203     return clk->period;
 204 }
 205
 206 static inline unsigned clock_get_hz(Clock *clk)
 207 {
 208     return CLOCK_PERIOD_TO_HZ(clock_get(clk));
 209 }
 210
 211 static inline unsigned clock_get_ns(Clock *clk)
 212 {
 213     return CLOCK_PERIOD_TO_NS(clock_get(clk));
 214 }
 215
 216 /**
 217  * clock_is_enabled:
 218  * @clk: a clock
 219  *
 220  * @return: true if the clock is running.
 221  */
 222 static inline bool clock_is_enabled(const Clock *clk)
 223 {
 224     return clock_get(clk) != 0;
 225 }
 226
 227 #endif /* QEMU_HW_CLOCK_H */