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