1 /* linux/include/linux/clocksource.h 2 * 3 * This file contains the structure definitions for clocksources. 4 * 5 * If you are not a clocksource, or timekeeping code, you should 6 * not be including this file! 7 */ 8 #ifndef _LINUX_CLOCKSOURCE_H 9 #define _LINUX_CLOCKSOURCE_H 10 11 #include <linux/types.h> 12 #include <linux/timex.h> 13 #include <linux/time.h> 14 #include <linux/list.h> 15 #include <linux/cache.h> 16 #include <linux/timer.h> 17 #include <linux/init.h> 18 #include <asm/div64.h> 19 #include <asm/io.h> 20 21 /* clocksource cycle base type */ 22 typedef u64 cycle_t; 23 struct clocksource; 24 struct module; 25 26 #ifdef CONFIG_ARCH_CLOCKSOURCE_DATA 27 #include <asm/clocksource.h> 28 #endif 29 30 /** 31 * struct cyclecounter - hardware abstraction for a free running counter 32 * Provides completely state-free accessors to the underlying hardware. 33 * Depending on which hardware it reads, the cycle counter may wrap 34 * around quickly. Locking rules (if necessary) have to be defined 35 * by the implementor and user of specific instances of this API. 36 * 37 * @read: returns the current cycle value 38 * @mask: bitmask for two's complement 39 * subtraction of non 64 bit counters, 40 * see CLOCKSOURCE_MASK() helper macro 41 * @mult: cycle to nanosecond multiplier 42 * @shift: cycle to nanosecond divisor (power of two) 43 */ 44 struct cyclecounter { 45 cycle_t (*read)(const struct cyclecounter *cc); 46 cycle_t mask; 47 u32 mult; 48 u32 shift; 49 }; 50 51 /** 52 * struct timecounter - layer above a %struct cyclecounter which counts nanoseconds 53 * Contains the state needed by timecounter_read() to detect 54 * cycle counter wrap around. Initialize with 55 * timecounter_init(). Also used to convert cycle counts into the 56 * corresponding nanosecond counts with timecounter_cyc2time(). Users 57 * of this code are responsible for initializing the underlying 58 * cycle counter hardware, locking issues and reading the time 59 * more often than the cycle counter wraps around. The nanosecond 60 * counter will only wrap around after ~585 years. 61 * 62 * @cc: the cycle counter used by this instance 63 * @cycle_last: most recent cycle counter value seen by 64 * timecounter_read() 65 * @nsec: continuously increasing count 66 */ 67 struct timecounter { 68 const struct cyclecounter *cc; 69 cycle_t cycle_last; 70 u64 nsec; 71 }; 72 73 /** 74 * cyclecounter_cyc2ns - converts cycle counter cycles to nanoseconds 75 * @cc: Pointer to cycle counter. 76 * @cycles: Cycles 77 * 78 * XXX - This could use some mult_lxl_ll() asm optimization. Same code 79 * as in cyc2ns, but with unsigned result. 80 */ 81 static inline u64 cyclecounter_cyc2ns(const struct cyclecounter *cc, 82 cycle_t cycles) 83 { 84 u64 ret = (u64)cycles; 85 ret = (ret * cc->mult) >> cc->shift; 86 return ret; 87 } 88 89 /** 90 * timecounter_init - initialize a time counter 91 * @tc: Pointer to time counter which is to be initialized/reset 92 * @cc: A cycle counter, ready to be used. 93 * @start_tstamp: Arbitrary initial time stamp. 94 * 95 * After this call the current cycle register (roughly) corresponds to 96 * the initial time stamp. Every call to timecounter_read() increments 97 * the time stamp counter by the number of elapsed nanoseconds. 98 */ 99 extern void timecounter_init(struct timecounter *tc, 100 const struct cyclecounter *cc, 101 u64 start_tstamp); 102 103 /** 104 * timecounter_read - return nanoseconds elapsed since timecounter_init() 105 * plus the initial time stamp 106 * @tc: Pointer to time counter. 107 * 108 * In other words, keeps track of time since the same epoch as 109 * the function which generated the initial time stamp. 110 */ 111 extern u64 timecounter_read(struct timecounter *tc); 112 113 /** 114 * timecounter_cyc2time - convert a cycle counter to same 115 * time base as values returned by 116 * timecounter_read() 117 * @tc: Pointer to time counter. 118 * @cycle_tstamp: a value returned by tc->cc->read() 119 * 120 * Cycle counts that are converted correctly as long as they 121 * fall into the interval [-1/2 max cycle count, +1/2 max cycle count], 122 * with "max cycle count" == cs->mask+1. 123 * 124 * This allows conversion of cycle counter values which were generated 125 * in the past. 126 */ 127 extern u64 timecounter_cyc2time(struct timecounter *tc, 128 cycle_t cycle_tstamp); 129 130 /** 131 * struct clocksource - hardware abstraction for a free running counter 132 * Provides mostly state-free accessors to the underlying hardware. 133 * This is the structure used for system time. 134 * 135 * @name: ptr to clocksource name 136 * @list: list head for registration 137 * @rating: rating value for selection (higher is better) 138 * To avoid rating inflation the following 139 * list should give you a guide as to how 140 * to assign your clocksource a rating 141 * 1-99: Unfit for real use 142 * Only available for bootup and testing purposes. 143 * 100-199: Base level usability. 144 * Functional for real use, but not desired. 145 * 200-299: Good. 146 * A correct and usable clocksource. 147 * 300-399: Desired. 148 * A reasonably fast and accurate clocksource. 149 * 400-499: Perfect 150 * The ideal clocksource. A must-use where 151 * available. 152 * @read: returns a cycle value, passes clocksource as argument 153 * @enable: optional function to enable the clocksource 154 * @disable: optional function to disable the clocksource 155 * @mask: bitmask for two's complement 156 * subtraction of non 64 bit counters 157 * @mult: cycle to nanosecond multiplier 158 * @shift: cycle to nanosecond divisor (power of two) 159 * @max_idle_ns: max idle time permitted by the clocksource (nsecs) 160 * @maxadj: maximum adjustment value to mult (~11%) 161 * @flags: flags describing special properties 162 * @archdata: arch-specific data 163 * @suspend: suspend function for the clocksource, if necessary 164 * @resume: resume function for the clocksource, if necessary 165 * @cycle_last: most recent cycle counter value seen by ::read() 166 * @owner: module reference, must be set by clocksource in modules 167 */ 168 struct clocksource { 169 /* 170 * Hotpath data, fits in a single cache line when the 171 * clocksource itself is cacheline aligned. 172 */ 173 cycle_t (*read)(struct clocksource *cs); 174 cycle_t cycle_last; 175 cycle_t mask; 176 u32 mult; 177 u32 shift; 178 u64 max_idle_ns; 179 u32 maxadj; 180 #ifdef CONFIG_ARCH_CLOCKSOURCE_DATA 181 struct arch_clocksource_data archdata; 182 #endif 183 184 const char *name; 185 struct list_head list; 186 int rating; 187 int (*enable)(struct clocksource *cs); 188 void (*disable)(struct clocksource *cs); 189 unsigned long flags; 190 void (*suspend)(struct clocksource *cs); 191 void (*resume)(struct clocksource *cs); 192 193 /* private: */ 194 #ifdef CONFIG_CLOCKSOURCE_WATCHDOG 195 /* Watchdog related data, used by the framework */ 196 struct list_head wd_list; 197 cycle_t cs_last; 198 cycle_t wd_last; 199 #endif 200 struct module *owner; 201 } ____cacheline_aligned; 202 203 /* 204 * Clock source flags bits:: 205 */ 206 #define CLOCK_SOURCE_IS_CONTINUOUS 0x01 207 #define CLOCK_SOURCE_MUST_VERIFY 0x02 208 209 #define CLOCK_SOURCE_WATCHDOG 0x10 210 #define CLOCK_SOURCE_VALID_FOR_HRES 0x20 211 #define CLOCK_SOURCE_UNSTABLE 0x40 212 #define CLOCK_SOURCE_SUSPEND_NONSTOP 0x80 213 #define CLOCK_SOURCE_RESELECT 0x100 214 215 /* simplify initialization of mask field */ 216 #define CLOCKSOURCE_MASK(bits) (cycle_t)((bits) < 64 ? ((1ULL<<(bits))-1) : -1) 217 218 /** 219 * clocksource_khz2mult - calculates mult from khz and shift 220 * @khz: Clocksource frequency in KHz 221 * @shift_constant: Clocksource shift factor 222 * 223 * Helper functions that converts a khz counter frequency to a timsource 224 * multiplier, given the clocksource shift value 225 */ 226 static inline u32 clocksource_khz2mult(u32 khz, u32 shift_constant) 227 { 228 /* khz = cyc/(Million ns) 229 * mult/2^shift = ns/cyc 230 * mult = ns/cyc * 2^shift 231 * mult = 1Million/khz * 2^shift 232 * mult = 1000000 * 2^shift / khz 233 * mult = (1000000<<shift) / khz 234 */ 235 u64 tmp = ((u64)1000000) << shift_constant; 236 237 tmp += khz/2; /* round for do_div */ 238 do_div(tmp, khz); 239 240 return (u32)tmp; 241 } 242 243 /** 244 * clocksource_hz2mult - calculates mult from hz and shift 245 * @hz: Clocksource frequency in Hz 246 * @shift_constant: Clocksource shift factor 247 * 248 * Helper functions that converts a hz counter 249 * frequency to a timsource multiplier, given the 250 * clocksource shift value 251 */ 252 static inline u32 clocksource_hz2mult(u32 hz, u32 shift_constant) 253 { 254 /* hz = cyc/(Billion ns) 255 * mult/2^shift = ns/cyc 256 * mult = ns/cyc * 2^shift 257 * mult = 1Billion/hz * 2^shift 258 * mult = 1000000000 * 2^shift / hz 259 * mult = (1000000000<<shift) / hz 260 */ 261 u64 tmp = ((u64)1000000000) << shift_constant; 262 263 tmp += hz/2; /* round for do_div */ 264 do_div(tmp, hz); 265 266 return (u32)tmp; 267 } 268 269 /** 270 * clocksource_cyc2ns - converts clocksource cycles to nanoseconds 271 * @cycles: cycles 272 * @mult: cycle to nanosecond multiplier 273 * @shift: cycle to nanosecond divisor (power of two) 274 * 275 * Converts cycles to nanoseconds, using the given mult and shift. 276 * 277 * XXX - This could use some mult_lxl_ll() asm optimization 278 */ 279 static inline s64 clocksource_cyc2ns(cycle_t cycles, u32 mult, u32 shift) 280 { 281 return ((u64) cycles * mult) >> shift; 282 } 283 284 285 extern int clocksource_register(struct clocksource*); 286 extern int clocksource_unregister(struct clocksource*); 287 extern void clocksource_touch_watchdog(void); 288 extern struct clocksource* clocksource_get_next(void); 289 extern void clocksource_change_rating(struct clocksource *cs, int rating); 290 extern void clocksource_suspend(void); 291 extern void clocksource_resume(void); 292 extern struct clocksource * __init __weak clocksource_default_clock(void); 293 extern void clocksource_mark_unstable(struct clocksource *cs); 294 295 extern u64 296 clocks_calc_max_nsecs(u32 mult, u32 shift, u32 maxadj, u64 mask); 297 extern void 298 clocks_calc_mult_shift(u32 *mult, u32 *shift, u32 from, u32 to, u32 minsec); 299 300 /* 301 * Don't call __clocksource_register_scale directly, use 302 * clocksource_register_hz/khz 303 */ 304 extern int 305 __clocksource_register_scale(struct clocksource *cs, u32 scale, u32 freq); 306 extern void 307 __clocksource_updatefreq_scale(struct clocksource *cs, u32 scale, u32 freq); 308 309 static inline int clocksource_register_hz(struct clocksource *cs, u32 hz) 310 { 311 return __clocksource_register_scale(cs, 1, hz); 312 } 313 314 static inline int clocksource_register_khz(struct clocksource *cs, u32 khz) 315 { 316 return __clocksource_register_scale(cs, 1000, khz); 317 } 318 319 static inline void __clocksource_updatefreq_hz(struct clocksource *cs, u32 hz) 320 { 321 __clocksource_updatefreq_scale(cs, 1, hz); 322 } 323 324 static inline void __clocksource_updatefreq_khz(struct clocksource *cs, u32 khz) 325 { 326 __clocksource_updatefreq_scale(cs, 1000, khz); 327 } 328 329 330 extern int timekeeping_notify(struct clocksource *clock); 331 332 extern cycle_t clocksource_mmio_readl_up(struct clocksource *); 333 extern cycle_t clocksource_mmio_readl_down(struct clocksource *); 334 extern cycle_t clocksource_mmio_readw_up(struct clocksource *); 335 extern cycle_t clocksource_mmio_readw_down(struct clocksource *); 336 337 extern int clocksource_mmio_init(void __iomem *, const char *, 338 unsigned long, int, unsigned, cycle_t (*)(struct clocksource *)); 339 340 extern int clocksource_i8253_init(void); 341 342 struct device_node; 343 typedef void(*clocksource_of_init_fn)(struct device_node *); 344 #ifdef CONFIG_CLKSRC_OF 345 extern void clocksource_of_init(void); 346 347 #define CLOCKSOURCE_OF_DECLARE(name, compat, fn) \ 348 static const struct of_device_id __clksrc_of_table_##name \ 349 __used __section(__clksrc_of_table) \ 350 = { .compatible = compat, \ 351 .data = (fn == (clocksource_of_init_fn)NULL) ? fn : fn } 352 #else 353 static inline void clocksource_of_init(void) {} 354 #define CLOCKSOURCE_OF_DECLARE(name, compat, fn) \ 355 static const struct of_device_id __clksrc_of_table_##name \ 356 __attribute__((unused)) \ 357 = { .compatible = compat, \ 358 .data = (fn == (clocksource_of_init_fn)NULL) ? fn : fn } 359 #endif 360 361 #endif /* _LINUX_CLOCKSOURCE_H */ 362