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 */ 217