clock.h (11517B)
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 #include "qemu/host-utils.h" 20 #include "qemu/bitops.h" 21 22 #define TYPE_CLOCK "clock" 23 OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK) 24 25 /* 26 * Argument to ClockCallback functions indicating why the callback 27 * has been called. A mask of these values logically ORed together 28 * is used to specify which events are interesting when the callback 29 * is registered, so these values must all be different bit values. 30 */ 31 typedef enum ClockEvent { 32 ClockUpdate = 1, /* Clock period has just updated */ 33 ClockPreUpdate = 2, /* Clock period is about to update */ 34 } ClockEvent; 35 36 typedef void ClockCallback(void *opaque, ClockEvent event); 37 38 /* 39 * clock store a value representing the clock's period in 2^-32ns unit. 40 * It can represent: 41 * + periods from 2^-32ns up to 4seconds 42 * + frequency from ~0.25Hz 2e10Ghz 43 * Resolution of frequency representation decreases with frequency: 44 * + at 100MHz, resolution is ~2mHz 45 * + at 1Ghz, resolution is ~0.2Hz 46 * + at 10Ghz, resolution is ~20Hz 47 */ 48 #define CLOCK_PERIOD_1SEC (1000000000llu << 32) 49 50 /* 51 * macro helpers to convert to hertz / nanosecond 52 */ 53 #define CLOCK_PERIOD_FROM_NS(ns) ((ns) * (CLOCK_PERIOD_1SEC / 1000000000llu)) 54 #define CLOCK_PERIOD_FROM_HZ(hz) (((hz) != 0) ? CLOCK_PERIOD_1SEC / (hz) : 0u) 55 #define CLOCK_PERIOD_TO_HZ(per) (((per) != 0) ? CLOCK_PERIOD_1SEC / (per) : 0u) 56 57 /** 58 * Clock: 59 * @parent_obj: parent class 60 * @period: unsigned integer representing the period of the clock 61 * @canonical_path: clock path string cache (used for trace purpose) 62 * @callback: called when clock changes 63 * @callback_opaque: argument for @callback 64 * @callback_events: mask of events when callback should be called 65 * @source: source (or parent in clock tree) of the clock 66 * @children: list of clocks connected to this one (it is their source) 67 * @sibling: structure used to form a clock list 68 */ 69 70 71 struct Clock { 72 /*< private >*/ 73 Object parent_obj; 74 75 /* all fields are private and should not be modified directly */ 76 77 /* fields */ 78 uint64_t period; 79 char *canonical_path; 80 ClockCallback *callback; 81 void *callback_opaque; 82 unsigned int callback_events; 83 84 /* Ratio of the parent clock to run the child clocks at */ 85 uint32_t multiplier; 86 uint32_t divider; 87 88 /* Clocks are organized in a clock tree */ 89 Clock *source; 90 QLIST_HEAD(, Clock) children; 91 QLIST_ENTRY(Clock) sibling; 92 }; 93 94 /* 95 * vmstate description entry to be added in device vmsd. 96 */ 97 extern const VMStateDescription vmstate_clock; 98 #define VMSTATE_CLOCK(field, state) \ 99 VMSTATE_CLOCK_V(field, state, 0) 100 #define VMSTATE_CLOCK_V(field, state, version) \ 101 VMSTATE_STRUCT_POINTER_V(field, state, version, vmstate_clock, Clock) 102 #define VMSTATE_ARRAY_CLOCK(field, state, num) \ 103 VMSTATE_ARRAY_CLOCK_V(field, state, num, 0) 104 #define VMSTATE_ARRAY_CLOCK_V(field, state, num, version) \ 105 VMSTATE_ARRAY_OF_POINTER_TO_STRUCT(field, state, num, version, \ 106 vmstate_clock, Clock) 107 108 /** 109 * clock_setup_canonical_path: 110 * @clk: clock 111 * 112 * compute the canonical path of the clock (used by log messages) 113 */ 114 void clock_setup_canonical_path(Clock *clk); 115 116 /** 117 * clock_new: 118 * @parent: the clock parent 119 * @name: the clock object name 120 * 121 * Helper function to create a new clock and parent it to @parent. There is no 122 * need to call clock_setup_canonical_path on the returned clock as it is done 123 * by this function. 124 * 125 * @return the newly created clock 126 */ 127 Clock *clock_new(Object *parent, const char *name); 128 129 /** 130 * clock_set_callback: 131 * @clk: the clock to register the callback into 132 * @cb: the callback function 133 * @opaque: the argument to the callback 134 * @events: the events the callback should be called for 135 * (logical OR of ClockEvent enum values) 136 * 137 * Register a callback called on every clock update. 138 * Note that a clock has only one callback: you cannot register 139 * different callback functions for different events. 140 */ 141 void clock_set_callback(Clock *clk, ClockCallback *cb, 142 void *opaque, unsigned int events); 143 144 /** 145 * clock_clear_callback: 146 * @clk: the clock to delete the callback from 147 * 148 * Unregister the callback registered with clock_set_callback. 149 */ 150 void clock_clear_callback(Clock *clk); 151 152 /** 153 * clock_set_source: 154 * @clk: the clock. 155 * @src: the source clock 156 * 157 * Setup @src as the clock source of @clk. The current @src period 158 * value is also copied to @clk and its subtree but no callback is 159 * called. 160 * Further @src update will be propagated to @clk and its subtree. 161 */ 162 void clock_set_source(Clock *clk, Clock *src); 163 164 /** 165 * clock_has_source: 166 * @clk: the clock 167 * 168 * Returns true if the clock has a source clock connected to it. 169 * This is useful for devices which have input clocks which must 170 * be connected by the board/SoC code which creates them. The 171 * device code can use this to check in its realize method that 172 * the clock has been connected. 173 */ 174 static inline bool clock_has_source(const Clock *clk) 175 { 176 return clk->source != NULL; 177 } 178 179 /** 180 * clock_set: 181 * @clk: the clock to initialize. 182 * @value: the clock's value, 0 means unclocked 183 * 184 * Set the local cached period value of @clk to @value. 185 * 186 * @return: true if the clock is changed. 187 */ 188 bool clock_set(Clock *clk, uint64_t value); 189 190 static inline bool clock_set_hz(Clock *clk, unsigned hz) 191 { 192 return clock_set(clk, CLOCK_PERIOD_FROM_HZ(hz)); 193 } 194 195 static inline bool clock_set_ns(Clock *clk, unsigned ns) 196 { 197 return clock_set(clk, CLOCK_PERIOD_FROM_NS(ns)); 198 } 199 200 /** 201 * clock_propagate: 202 * @clk: the clock 203 * 204 * Propagate the clock period that has been previously configured using 205 * @clock_set(). This will update recursively all connected clocks. 206 * It is an error to call this function on a clock which has a source. 207 * Note: this function must not be called during device inititialization 208 * or migration. 209 */ 210 void clock_propagate(Clock *clk); 211 212 /** 213 * clock_update: 214 * @clk: the clock to update. 215 * @value: the new clock's value, 0 means unclocked 216 * 217 * Update the @clk to the new @value. All connected clocks will be informed 218 * of this update. This is equivalent to call @clock_set() then 219 * @clock_propagate(). 220 */ 221 static inline void clock_update(Clock *clk, uint64_t value) 222 { 223 if (clock_set(clk, value)) { 224 clock_propagate(clk); 225 } 226 } 227 228 static inline void clock_update_hz(Clock *clk, unsigned hz) 229 { 230 clock_update(clk, CLOCK_PERIOD_FROM_HZ(hz)); 231 } 232 233 static inline void clock_update_ns(Clock *clk, unsigned ns) 234 { 235 clock_update(clk, CLOCK_PERIOD_FROM_NS(ns)); 236 } 237 238 /** 239 * clock_get: 240 * @clk: the clk to fetch the clock 241 * 242 * @return: the current period. 243 */ 244 static inline uint64_t clock_get(const Clock *clk) 245 { 246 return clk->period; 247 } 248 249 static inline unsigned clock_get_hz(Clock *clk) 250 { 251 return CLOCK_PERIOD_TO_HZ(clock_get(clk)); 252 } 253 254 /** 255 * clock_ticks_to_ns: 256 * @clk: the clock to query 257 * @ticks: number of ticks 258 * 259 * Returns the length of time in nanoseconds for this clock 260 * to tick @ticks times. Because a clock can have a period 261 * which is not a whole number of nanoseconds, it is important 262 * to use this function when calculating things like timer 263 * expiry deadlines, rather than attempting to obtain a "period 264 * in nanoseconds" value and then multiplying that by a number 265 * of ticks. 266 * 267 * The result could in theory be too large to fit in a 64-bit 268 * value if the number of ticks and the clock period are both 269 * large; to avoid overflow the result will be saturated to INT64_MAX 270 * (because this is the largest valid input to the QEMUTimer APIs). 271 * Since INT64_MAX nanoseconds is almost 300 years, anything with 272 * an expiry later than that is in the "will never happen" category 273 * and callers can reasonably not special-case the saturated result. 274 */ 275 static inline uint64_t clock_ticks_to_ns(const Clock *clk, uint64_t ticks) 276 { 277 uint64_t ns_low, ns_high; 278 279 /* 280 * clk->period is the period in units of 2^-32 ns, so 281 * (clk->period * ticks) is the required length of time in those 282 * units, and we can convert to nanoseconds by multiplying by 283 * 2^32, which is the same as shifting the 128-bit multiplication 284 * result right by 32. 285 */ 286 mulu64(&ns_low, &ns_high, clk->period, ticks); 287 if (ns_high & MAKE_64BIT_MASK(31, 33)) { 288 return INT64_MAX; 289 } 290 return ns_low >> 32 | ns_high << 32; 291 } 292 293 /** 294 * clock_ns_to_ticks: 295 * @clk: the clock to query 296 * @ns: duration in nanoseconds 297 * 298 * Returns the number of ticks this clock would make in the given 299 * number of nanoseconds. Because a clock can have a period which 300 * is not a whole number of nanoseconds, it is important to use this 301 * function rather than attempting to obtain a "period in nanoseconds" 302 * value and then dividing the duration by that value. 303 * 304 * If the clock is stopped (ie it has period zero), returns 0. 305 * 306 * For some inputs the result could overflow a 64-bit value (because 307 * the clock's period is short and the duration is long). In these 308 * cases we truncate the result to a 64-bit value. This is on the 309 * assumption that generally the result is going to be used to report 310 * a 32-bit or 64-bit guest register value, so wrapping either cannot 311 * happen or is the desired behaviour. 312 */ 313 static inline uint64_t clock_ns_to_ticks(const Clock *clk, uint64_t ns) 314 { 315 /* 316 * ticks = duration_in_ns / period_in_ns 317 * = ns / (period / 2^32) 318 * = (ns * 2^32) / period 319 * The hi, lo inputs to divu128() are (ns << 32) as a 128 bit value. 320 */ 321 uint64_t lo = ns << 32; 322 uint64_t hi = ns >> 32; 323 if (clk->period == 0) { 324 return 0; 325 } 326 327 divu128(&lo, &hi, clk->period); 328 return lo; 329 } 330 331 /** 332 * clock_is_enabled: 333 * @clk: a clock 334 * 335 * @return: true if the clock is running. 336 */ 337 static inline bool clock_is_enabled(const Clock *clk) 338 { 339 return clock_get(clk) != 0; 340 } 341 342 /** 343 * clock_display_freq: return human-readable representation of clock frequency 344 * @clk: clock 345 * 346 * Return a string which has a human-readable representation of the 347 * clock's frequency, e.g. "33.3 MHz". This is intended for debug 348 * and display purposes. 349 * 350 * The caller is responsible for freeing the string with g_free(). 351 */ 352 char *clock_display_freq(Clock *clk); 353 354 /** 355 * clock_set_mul_div: set multiplier/divider for child clocks 356 * @clk: clock 357 * @multiplier: multiplier value 358 * @divider: divider value 359 * 360 * By default, a Clock's children will all run with the same period 361 * as their parent. This function allows you to adjust the multiplier 362 * and divider used to derive the child clock frequency. 363 * For example, setting a multiplier of 2 and a divider of 3 364 * will run child clocks with a period 2/3 of the parent clock, 365 * so if the parent clock is an 8MHz clock the children will 366 * be 12MHz. 367 * 368 * Setting the multiplier to 0 will stop the child clocks. 369 * Setting the divider to 0 is a programming error (diagnosed with 370 * an assertion failure). 371 * Setting a multiplier value that results in the child period 372 * overflowing is not diagnosed. 373 * 374 * Note that this function does not call clock_propagate(); the 375 * caller should do that if necessary. 376 */ 377 void clock_set_mul_div(Clock *clk, uint32_t multiplier, uint32_t divider); 378 379 #endif /* QEMU_HW_CLOCK_H */