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