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