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