Branch data Line data Source code
1 : : /* SPDX-License-Identifier: GPL-2.0 */ 2 : : /* linux/include/linux/clocksource.h 3 : : * 4 : : * This file contains the structure definitions for clocksources. 5 : : * 6 : : * If you are not a clocksource, or timekeeping code, you should 7 : : * not be including this file! 8 : : */ 9 : : #ifndef _LINUX_CLOCKSOURCE_H 10 : : #define _LINUX_CLOCKSOURCE_H 11 : : 12 : : #include <linux/types.h> 13 : : #include <linux/timex.h> 14 : : #include <linux/time.h> 15 : : #include <linux/list.h> 16 : : #include <linux/cache.h> 17 : : #include <linux/timer.h> 18 : : #include <linux/init.h> 19 : : #include <linux/of.h> 20 : : #include <asm/div64.h> 21 : : #include <asm/io.h> 22 : : 23 : : struct clocksource; 24 : : struct module; 25 : : 26 : : #ifdef CONFIG_ARCH_CLOCKSOURCE_DATA 27 : : #include <asm/clocksource.h> 28 : : #endif 29 : : 30 : : /** 31 : : * struct clocksource - hardware abstraction for a free running counter 32 : : * Provides mostly state-free accessors to the underlying hardware. 33 : : * This is the structure used for system time. 34 : : * 35 : : * @name: ptr to clocksource name 36 : : * @list: list head for registration 37 : : * @rating: rating value for selection (higher is better) 38 : : * To avoid rating inflation the following 39 : : * list should give you a guide as to how 40 : : * to assign your clocksource a rating 41 : : * 1-99: Unfit for real use 42 : : * Only available for bootup and testing purposes. 43 : : * 100-199: Base level usability. 44 : : * Functional for real use, but not desired. 45 : : * 200-299: Good. 46 : : * A correct and usable clocksource. 47 : : * 300-399: Desired. 48 : : * A reasonably fast and accurate clocksource. 49 : : * 400-499: Perfect 50 : : * The ideal clocksource. A must-use where 51 : : * available. 52 : : * @read: returns a cycle value, passes clocksource as argument 53 : : * @enable: optional function to enable the clocksource 54 : : * @disable: optional function to disable the clocksource 55 : : * @mask: bitmask for two's complement 56 : : * subtraction of non 64 bit counters 57 : : * @mult: cycle to nanosecond multiplier 58 : : * @shift: cycle to nanosecond divisor (power of two) 59 : : * @max_idle_ns: max idle time permitted by the clocksource (nsecs) 60 : : * @maxadj: maximum adjustment value to mult (~11%) 61 : : * @max_cycles: maximum safe cycle value which won't overflow on multiplication 62 : : * @flags: flags describing special properties 63 : : * @archdata: arch-specific data 64 : : * @suspend: suspend function for the clocksource, if necessary 65 : : * @resume: resume function for the clocksource, if necessary 66 : : * @mark_unstable: Optional function to inform the clocksource driver that 67 : : * the watchdog marked the clocksource unstable 68 : : * @owner: module reference, must be set by clocksource in modules 69 : : * 70 : : * Note: This struct is not used in hotpathes of the timekeeping code 71 : : * because the timekeeper caches the hot path fields in its own data 72 : : * structure, so no line cache alignment is required, 73 : : * 74 : : * The pointer to the clocksource itself is handed to the read 75 : : * callback. If you need extra information there you can wrap struct 76 : : * clocksource into your own struct. Depending on the amount of 77 : : * information you need you should consider to cache line align that 78 : : * structure. 79 : : */ 80 : : struct clocksource { 81 : : u64 (*read)(struct clocksource *cs); 82 : : u64 mask; 83 : : u32 mult; 84 : : u32 shift; 85 : : u64 max_idle_ns; 86 : : u32 maxadj; 87 : : #ifdef CONFIG_ARCH_CLOCKSOURCE_DATA 88 : : struct arch_clocksource_data archdata; 89 : : #endif 90 : : u64 max_cycles; 91 : : const char *name; 92 : : struct list_head list; 93 : : int rating; 94 : : int (*enable)(struct clocksource *cs); 95 : : void (*disable)(struct clocksource *cs); 96 : : unsigned long flags; 97 : : void (*suspend)(struct clocksource *cs); 98 : : void (*resume)(struct clocksource *cs); 99 : : void (*mark_unstable)(struct clocksource *cs); 100 : : void (*tick_stable)(struct clocksource *cs); 101 : : 102 : : /* private: */ 103 : : #ifdef CONFIG_CLOCKSOURCE_WATCHDOG 104 : : /* Watchdog related data, used by the framework */ 105 : : struct list_head wd_list; 106 : : u64 cs_last; 107 : : u64 wd_last; 108 : : #endif 109 : : struct module *owner; 110 : : }; 111 : : 112 : : /* 113 : : * Clock source flags bits:: 114 : : */ 115 : : #define CLOCK_SOURCE_IS_CONTINUOUS 0x01 116 : : #define CLOCK_SOURCE_MUST_VERIFY 0x02 117 : : 118 : : #define CLOCK_SOURCE_WATCHDOG 0x10 119 : : #define CLOCK_SOURCE_VALID_FOR_HRES 0x20 120 : : #define CLOCK_SOURCE_UNSTABLE 0x40 121 : : #define CLOCK_SOURCE_SUSPEND_NONSTOP 0x80 122 : : #define CLOCK_SOURCE_RESELECT 0x100 123 : : 124 : : /* simplify initialization of mask field */ 125 : : #define CLOCKSOURCE_MASK(bits) GENMASK_ULL((bits) - 1, 0) 126 : : 127 : : static inline u32 clocksource_freq2mult(u32 freq, u32 shift_constant, u64 from) 128 : : { 129 : : /* freq = cyc/from 130 : : * mult/2^shift = ns/cyc 131 : : * mult = ns/cyc * 2^shift 132 : : * mult = from/freq * 2^shift 133 : : * mult = from * 2^shift / freq 134 : : * mult = (from<<shift) / freq 135 : : */ 136 : : u64 tmp = ((u64)from) << shift_constant; 137 : : 138 : : tmp += freq/2; /* round for do_div */ 139 : : do_div(tmp, freq); 140 : : 141 : : return (u32)tmp; 142 : : } 143 : : 144 : : /** 145 : : * clocksource_khz2mult - calculates mult from khz and shift 146 : : * @khz: Clocksource frequency in KHz 147 : : * @shift_constant: Clocksource shift factor 148 : : * 149 : : * Helper functions that converts a khz counter frequency to a timsource 150 : : * multiplier, given the clocksource shift value 151 : : */ 152 : : static inline u32 clocksource_khz2mult(u32 khz, u32 shift_constant) 153 : : { 154 : : return clocksource_freq2mult(khz, shift_constant, NSEC_PER_MSEC); 155 : : } 156 : : 157 : : /** 158 : : * clocksource_hz2mult - calculates mult from hz and shift 159 : : * @hz: Clocksource frequency in Hz 160 : : * @shift_constant: Clocksource shift factor 161 : : * 162 : : * Helper functions that converts a hz counter 163 : : * frequency to a timsource multiplier, given the 164 : : * clocksource shift value 165 : : */ 166 : : static inline u32 clocksource_hz2mult(u32 hz, u32 shift_constant) 167 : : { 168 : : return clocksource_freq2mult(hz, shift_constant, NSEC_PER_SEC); 169 : : } 170 : : 171 : : /** 172 : : * clocksource_cyc2ns - converts clocksource cycles to nanoseconds 173 : : * @cycles: cycles 174 : : * @mult: cycle to nanosecond multiplier 175 : : * @shift: cycle to nanosecond divisor (power of two) 176 : : * 177 : : * Converts clocksource cycles to nanoseconds, using the given @mult and @shift. 178 : : * The code is optimized for performance and is not intended to work 179 : : * with absolute clocksource cycles (as those will easily overflow), 180 : : * but is only intended to be used with relative (delta) clocksource cycles. 181 : : * 182 : : * XXX - This could use some mult_lxl_ll() asm optimization 183 : : */ 184 : : static inline s64 clocksource_cyc2ns(u64 cycles, u32 mult, u32 shift) 185 : : { 186 : 3 : return ((u64) cycles * mult) >> shift; 187 : : } 188 : : 189 : : 190 : : extern int clocksource_unregister(struct clocksource*); 191 : : extern void clocksource_touch_watchdog(void); 192 : : extern void clocksource_change_rating(struct clocksource *cs, int rating); 193 : : extern void clocksource_suspend(void); 194 : : extern void clocksource_resume(void); 195 : : extern struct clocksource * __init clocksource_default_clock(void); 196 : : extern void clocksource_mark_unstable(struct clocksource *cs); 197 : : extern void 198 : : clocksource_start_suspend_timing(struct clocksource *cs, u64 start_cycles); 199 : : extern u64 clocksource_stop_suspend_timing(struct clocksource *cs, u64 now); 200 : : 201 : : extern u64 202 : : clocks_calc_max_nsecs(u32 mult, u32 shift, u32 maxadj, u64 mask, u64 *max_cycles); 203 : : extern void 204 : : clocks_calc_mult_shift(u32 *mult, u32 *shift, u32 from, u32 to, u32 minsec); 205 : : 206 : : /* 207 : : * Don't call __clocksource_register_scale directly, use 208 : : * clocksource_register_hz/khz 209 : : */ 210 : : extern int 211 : : __clocksource_register_scale(struct clocksource *cs, u32 scale, u32 freq); 212 : : extern void 213 : : __clocksource_update_freq_scale(struct clocksource *cs, u32 scale, u32 freq); 214 : : 215 : : /* 216 : : * Don't call this unless you are a default clocksource 217 : : * (AKA: jiffies) and absolutely have to. 218 : : */ 219 : : static inline int __clocksource_register(struct clocksource *cs) 220 : : { 221 : 3 : return __clocksource_register_scale(cs, 1, 0); 222 : : } 223 : : 224 : : static inline int clocksource_register_hz(struct clocksource *cs, u32 hz) 225 : : { 226 : 3 : return __clocksource_register_scale(cs, 1, hz); 227 : : } 228 : : 229 : : static inline int clocksource_register_khz(struct clocksource *cs, u32 khz) 230 : : { 231 : : return __clocksource_register_scale(cs, 1000, khz); 232 : : } 233 : : 234 : : static inline void __clocksource_update_freq_hz(struct clocksource *cs, u32 hz) 235 : : { 236 : : __clocksource_update_freq_scale(cs, 1, hz); 237 : : } 238 : : 239 : : static inline void __clocksource_update_freq_khz(struct clocksource *cs, u32 khz) 240 : : { 241 : : __clocksource_update_freq_scale(cs, 1000, khz); 242 : : } 243 : : 244 : : #ifdef CONFIG_ARCH_CLOCKSOURCE_INIT 245 : : extern void clocksource_arch_init(struct clocksource *cs); 246 : : #else 247 : : static inline void clocksource_arch_init(struct clocksource *cs) { } 248 : : #endif 249 : : 250 : : extern int timekeeping_notify(struct clocksource *clock); 251 : : 252 : : extern u64 clocksource_mmio_readl_up(struct clocksource *); 253 : : extern u64 clocksource_mmio_readl_down(struct clocksource *); 254 : : extern u64 clocksource_mmio_readw_up(struct clocksource *); 255 : : extern u64 clocksource_mmio_readw_down(struct clocksource *); 256 : : 257 : : extern int clocksource_mmio_init(void __iomem *, const char *, 258 : : unsigned long, int, unsigned, u64 (*)(struct clocksource *)); 259 : : 260 : : extern int clocksource_i8253_init(void); 261 : : 262 : : #define TIMER_OF_DECLARE(name, compat, fn) \ 263 : : OF_DECLARE_1_RET(timer, name, compat, fn) 264 : : 265 : : #ifdef CONFIG_TIMER_PROBE 266 : : extern void timer_probe(void); 267 : : #else 268 : : static inline void timer_probe(void) {} 269 : : #endif 270 : : 271 : : #define TIMER_ACPI_DECLARE(name, table_id, fn) \ 272 : : ACPI_DECLARE_PROBE_ENTRY(timer, name, table_id, 0, NULL, 0, fn) 273 : : 274 : : #endif /* _LINUX_CLOCKSOURCE_H */