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