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 * @return: true if the clock is changed. 132 */ 133 bool clock_set(Clock *clk, uint64_t value); 134 135 static inline bool clock_set_hz(Clock *clk, unsigned hz) 136 { 137 return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz)); 138 } 139 140 static inline bool clock_set_ns(Clock *clk, unsigned ns) 141 { 142 return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns)); 143 } 144 145 /** 146 * clock_propagate: 147 * @clk: the clock 148 * 149 * Propagate the clock period that has been previously configured using 150 * @clock_set(). This will update recursively all connected clocks. 151 * It is an error to call this function on a clock which has a source. 152 * Note: this function must not be called during device inititialization 153 * or migration. 154 */ 155 void clock_propagate(Clock *clk); 156 157 /** 158 * clock_update: 159 * @clk: the clock to update. 160 * @value: the new clock's value, 0 means unclocked 161 * 162 * Update the @clk to the new @value. All connected clocks will be informed 163 * of this update. This is equivalent to call @clock_set() then 164 * @clock_propagate(). 165 */ 166 static inline void clock_update(Clock *clk, uint64_t value) 167 { 168 if (clock_set(clk, value)) { 169 clock_propagate(clk); 170 } 171 } 172 173 static inline void clock_update_hz(Clock *clk, unsigned hz) 174 { 175 clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz)); 176 } 177 178 static inline void clock_update_ns(Clock *clk, unsigned ns) 179 { 180 clock_update(clk, CLOCK_PERIOD_FROM_NS(ns)); 181 } 182 183 /** 184 * clock_get: 185 * @clk: the clk to fetch the clock 186 * 187 * @return: the current period. 188 */ 189 static inline uint64_t clock_get(const Clock *clk) 190 { 191 return clk->period; 192 } 193 194 static inline unsigned clock_get_hz(Clock *clk) 195 { 196 return CLOCK_PERIOD_TO_HZ(clock_get(clk)); 197 } 198 199 static inline unsigned clock_get_ns(Clock *clk) 200 { 201 return CLOCK_PERIOD_TO_NS(clock_get(clk)); 202 } 203 204 /** 205 * clock_is_enabled: 206 * @clk: a clock 207 * 208 * @return: true if the clock is running. 209 */ 210 static inline bool clock_is_enabled(const Clock *clk) 211 { 212 return clock_get(clk) != 0; 213 } 214 215 #endif /* QEMU_HW_CLOCK_H */ 216