blob: 5ea3c60c160c2df2d6e0010a33d9c8e01281b1f9 [file] [log] [blame]
john stultz734efb42006-06-26 00:25:05 -07001/* 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>
Eric Dumazet329c8d82007-05-08 00:27:57 -070015#include <linux/cache.h>
Thomas Gleixner5d8b34f2007-02-16 01:27:43 -080016#include <linux/timer.h>
Martin Schwidefskyf1b82742009-08-14 15:47:21 +020017#include <linux/init.h>
john stultz734efb42006-06-26 00:25:05 -070018#include <asm/div64.h>
19#include <asm/io.h>
20
21/* clocksource cycle base type */
22typedef u64 cycle_t;
Thomas Gleixner5d8b34f2007-02-16 01:27:43 -080023struct clocksource;
john stultz734efb42006-06-26 00:25:05 -070024
25/**
Patrick Ohlya038a352009-02-12 05:03:34 +000026 * 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
68/**
69 * cyclecounter_cyc2ns - converts cycle counter cycles to nanoseconds
70 * @tc: Pointer to cycle counter.
71 * @cycles: Cycles
72 *
73 * XXX - This could use some mult_lxl_ll() asm optimization. Same code
74 * as in cyc2ns, but with unsigned result.
75 */
76static inline u64 cyclecounter_cyc2ns(const struct cyclecounter *cc,
77 cycle_t cycles)
78{
79 u64 ret = (u64)cycles;
80 ret = (ret * cc->mult) >> cc->shift;
81 return ret;
82}
83
84/**
85 * timecounter_init - initialize a time counter
86 * @tc: Pointer to time counter which is to be initialized/reset
87 * @cc: A cycle counter, ready to be used.
88 * @start_tstamp: Arbitrary initial time stamp.
89 *
90 * After this call the current cycle register (roughly) corresponds to
91 * the initial time stamp. Every call to timecounter_read() increments
92 * the time stamp counter by the number of elapsed nanoseconds.
93 */
94extern void timecounter_init(struct timecounter *tc,
95 const struct cyclecounter *cc,
96 u64 start_tstamp);
97
98/**
99 * timecounter_read - return nanoseconds elapsed since timecounter_init()
100 * plus the initial time stamp
101 * @tc: Pointer to time counter.
102 *
103 * In other words, keeps track of time since the same epoch as
104 * the function which generated the initial time stamp.
105 */
106extern u64 timecounter_read(struct timecounter *tc);
107
108/**
109 * timecounter_cyc2time - convert a cycle counter to same
110 * time base as values returned by
111 * timecounter_read()
112 * @tc: Pointer to time counter.
113 * @cycle: a value returned by tc->cc->read()
114 *
115 * Cycle counts that are converted correctly as long as they
116 * fall into the interval [-1/2 max cycle count, +1/2 max cycle count],
117 * with "max cycle count" == cs->mask+1.
118 *
119 * This allows conversion of cycle counter values which were generated
120 * in the past.
121 */
122extern u64 timecounter_cyc2time(struct timecounter *tc,
123 cycle_t cycle_tstamp);
124
125/**
john stultz734efb42006-06-26 00:25:05 -0700126 * struct clocksource - hardware abstraction for a free running counter
127 * Provides mostly state-free accessors to the underlying hardware.
Patrick Ohlya038a352009-02-12 05:03:34 +0000128 * This is the structure used for system time.
john stultz734efb42006-06-26 00:25:05 -0700129 *
130 * @name: ptr to clocksource name
131 * @list: list head for registration
132 * @rating: rating value for selection (higher is better)
133 * To avoid rating inflation the following
134 * list should give you a guide as to how
135 * to assign your clocksource a rating
136 * 1-99: Unfit for real use
137 * Only available for bootup and testing purposes.
138 * 100-199: Base level usability.
139 * Functional for real use, but not desired.
140 * 200-299: Good.
141 * A correct and usable clocksource.
142 * 300-399: Desired.
143 * A reasonably fast and accurate clocksource.
144 * 400-499: Perfect
145 * The ideal clocksource. A must-use where
146 * available.
Magnus Damm8e196082009-04-21 12:24:00 -0700147 * @read: returns a cycle value, passes clocksource as argument
Magnus Damm4614e6a2009-04-21 12:24:02 -0700148 * @enable: optional function to enable the clocksource
149 * @disable: optional function to disable the clocksource
john stultz734efb42006-06-26 00:25:05 -0700150 * @mask: bitmask for two's complement
151 * subtraction of non 64 bit counters
Martin Schwidefsky0a544192009-08-14 15:47:28 +0200152 * @mult: cycle to nanosecond multiplier
john stultz734efb42006-06-26 00:25:05 -0700153 * @shift: cycle to nanosecond divisor (power of two)
Jon Hunter98962462009-08-18 12:45:10 -0500154 * @max_idle_ns: max idle time permitted by the clocksource (nsecs)
Thomas Gleixner73b08d22007-02-16 01:27:36 -0800155 * @flags: flags describing special properties
john stultzacc9a9d2007-02-16 01:28:17 -0800156 * @vread: vsyscall based read
Magnus Dammc54a42b2010-02-02 14:41:41 -0800157 * @suspend: suspend function for the clocksource, if necessary
Thomas Gleixnerb52f52a2007-05-09 02:35:15 -0700158 * @resume: resume function for the clocksource, if necessary
john stultz734efb42006-06-26 00:25:05 -0700159 */
160struct clocksource {
Eric Dumazet329c8d82007-05-08 00:27:57 -0700161 /*
162 * First part of structure is read mostly
163 */
john stultz734efb42006-06-26 00:25:05 -0700164 char *name;
165 struct list_head list;
166 int rating;
Magnus Damm8e196082009-04-21 12:24:00 -0700167 cycle_t (*read)(struct clocksource *cs);
Magnus Damm4614e6a2009-04-21 12:24:02 -0700168 int (*enable)(struct clocksource *cs);
169 void (*disable)(struct clocksource *cs);
john stultz734efb42006-06-26 00:25:05 -0700170 cycle_t mask;
171 u32 mult;
172 u32 shift;
Jon Hunter98962462009-08-18 12:45:10 -0500173 u64 max_idle_ns;
Thomas Gleixner73b08d22007-02-16 01:27:36 -0800174 unsigned long flags;
john stultzacc9a9d2007-02-16 01:28:17 -0800175 cycle_t (*vread)(void);
Magnus Dammc54a42b2010-02-02 14:41:41 -0800176 void (*suspend)(struct clocksource *cs);
Magnus Damm17622332010-02-02 14:41:39 -0800177 void (*resume)(struct clocksource *cs);
Tony Luck0aa366f2007-07-20 11:22:30 -0700178#ifdef CONFIG_IA64
179 void *fsys_mmio; /* used by fsyscall asm code */
180#define CLKSRC_FSYS_MMIO_SET(mmio, addr) ((mmio) = (addr))
181#else
182#define CLKSRC_FSYS_MMIO_SET(mmio, addr) do { } while (0)
183#endif
john stultz734efb42006-06-26 00:25:05 -0700184
Eric Dumazet329c8d82007-05-08 00:27:57 -0700185 /*
186 * Second part is written at each timer interrupt
187 * Keep it in a different cache line to dirty no
188 * more than one cache line.
189 */
190 cycle_t cycle_last ____cacheline_aligned_in_smp;
Thomas Gleixner5d8b34f2007-02-16 01:27:43 -0800191
192#ifdef CONFIG_CLOCKSOURCE_WATCHDOG
193 /* Watchdog related data, used by the framework */
194 struct list_head wd_list;
195 cycle_t wd_last;
196#endif
john stultz734efb42006-06-26 00:25:05 -0700197};
198
Thomas Gleixner73b08d22007-02-16 01:27:36 -0800199/*
200 * Clock source flags bits::
201 */
Thomas Gleixner5d8b34f2007-02-16 01:27:43 -0800202#define CLOCK_SOURCE_IS_CONTINUOUS 0x01
203#define CLOCK_SOURCE_MUST_VERIFY 0x02
204
205#define CLOCK_SOURCE_WATCHDOG 0x10
206#define CLOCK_SOURCE_VALID_FOR_HRES 0x20
Martin Schwidefskyc55c87c2009-08-14 15:47:25 +0200207#define CLOCK_SOURCE_UNSTABLE 0x40
Thomas Gleixner73b08d22007-02-16 01:27:36 -0800208
Jim Cromie7f9f3032006-06-26 00:25:15 -0700209/* simplify initialization of mask field */
Atsushi Nemoto1d76c262008-01-30 13:30:01 +0100210#define CLOCKSOURCE_MASK(bits) (cycle_t)((bits) < 64 ? ((1ULL<<(bits))-1) : -1)
john stultz734efb42006-06-26 00:25:05 -0700211
212/**
213 * clocksource_khz2mult - calculates mult from khz and shift
214 * @khz: Clocksource frequency in KHz
215 * @shift_constant: Clocksource shift factor
216 *
217 * Helper functions that converts a khz counter frequency to a timsource
218 * multiplier, given the clocksource shift value
219 */
220static inline u32 clocksource_khz2mult(u32 khz, u32 shift_constant)
221{
222 /* khz = cyc/(Million ns)
223 * mult/2^shift = ns/cyc
224 * mult = ns/cyc * 2^shift
225 * mult = 1Million/khz * 2^shift
226 * mult = 1000000 * 2^shift / khz
227 * mult = (1000000<<shift) / khz
228 */
229 u64 tmp = ((u64)1000000) << shift_constant;
230
231 tmp += khz/2; /* round for do_div */
232 do_div(tmp, khz);
233
234 return (u32)tmp;
235}
236
237/**
238 * clocksource_hz2mult - calculates mult from hz and shift
239 * @hz: Clocksource frequency in Hz
240 * @shift_constant: Clocksource shift factor
241 *
242 * Helper functions that converts a hz counter
243 * frequency to a timsource multiplier, given the
244 * clocksource shift value
245 */
246static inline u32 clocksource_hz2mult(u32 hz, u32 shift_constant)
247{
248 /* hz = cyc/(Billion ns)
249 * mult/2^shift = ns/cyc
250 * mult = ns/cyc * 2^shift
251 * mult = 1Billion/hz * 2^shift
252 * mult = 1000000000 * 2^shift / hz
253 * mult = (1000000000<<shift) / hz
254 */
255 u64 tmp = ((u64)1000000000) << shift_constant;
256
257 tmp += hz/2; /* round for do_div */
258 do_div(tmp, hz);
259
260 return (u32)tmp;
261}
262
263/**
Martin Schwidefsky155ec602009-08-14 15:47:26 +0200264 * clocksource_cyc2ns - converts clocksource cycles to nanoseconds
john stultz734efb42006-06-26 00:25:05 -0700265 *
Martin Schwidefsky155ec602009-08-14 15:47:26 +0200266 * Converts cycles to nanoseconds, using the given mult and shift.
john stultz734efb42006-06-26 00:25:05 -0700267 *
268 * XXX - This could use some mult_lxl_ll() asm optimization
269 */
Martin Schwidefsky155ec602009-08-14 15:47:26 +0200270static inline s64 clocksource_cyc2ns(cycle_t cycles, u32 mult, u32 shift)
john stultz734efb42006-06-26 00:25:05 -0700271{
Martin Schwidefsky155ec602009-08-14 15:47:26 +0200272 return ((u64) cycles * mult) >> shift;
john stultz5eb6d202006-06-26 00:25:07 -0700273}
274
275
Thomas Gleixner92c7e002007-02-16 01:27:33 -0800276extern int clocksource_register(struct clocksource*);
Thomas Gleixner4713e22c2008-01-30 13:30:02 +0100277extern void clocksource_unregister(struct clocksource*);
Jason Wessel7c3078b2008-02-15 14:55:54 -0600278extern void clocksource_touch_watchdog(void);
Thomas Gleixner92c7e002007-02-16 01:27:33 -0800279extern struct clocksource* clocksource_get_next(void);
280extern void clocksource_change_rating(struct clocksource *cs, int rating);
Magnus Dammc54a42b2010-02-02 14:41:41 -0800281extern void clocksource_suspend(void);
Thomas Gleixnerb52f52a2007-05-09 02:35:15 -0700282extern void clocksource_resume(void);
Martin Schwidefskyf1b82742009-08-14 15:47:21 +0200283extern struct clocksource * __init __weak clocksource_default_clock(void);
Thomas Gleixner7285dd72009-08-28 20:25:24 +0200284extern void clocksource_mark_unstable(struct clocksource *cs);
john stultz734efb42006-06-26 00:25:05 -0700285
Thomas Gleixner7d2f9442009-11-11 14:05:29 +0000286extern void
287clocks_calc_mult_shift(u32 *mult, u32 *shift, u32 from, u32 to, u32 minsec);
288
John Stultzd7e81c22010-05-07 18:07:38 -0700289/*
290 * Don't call __clocksource_register_scale directly, use
291 * clocksource_register_hz/khz
292 */
293extern int
294__clocksource_register_scale(struct clocksource *cs, u32 scale, u32 freq);
295
296static inline int clocksource_register_hz(struct clocksource *cs, u32 hz)
297{
298 return __clocksource_register_scale(cs, 1, hz);
299}
300
301static inline int clocksource_register_khz(struct clocksource *cs, u32 khz)
302{
303 return __clocksource_register_scale(cs, 1000, khz);
304}
305
306
Thomas Gleixner7d2f9442009-11-11 14:05:29 +0000307static inline void
308clocksource_calc_mult_shift(struct clocksource *cs, u32 freq, u32 minsec)
309{
310 return clocks_calc_mult_shift(&cs->mult, &cs->shift, freq,
311 NSEC_PER_SEC, minsec);
312}
313
john stultzacc9a9d2007-02-16 01:28:17 -0800314#ifdef CONFIG_GENERIC_TIME_VSYSCALL
Lin Ming0696b712009-11-17 13:49:50 +0800315extern void
316update_vsyscall(struct timespec *ts, struct clocksource *c, u32 mult);
Tony Breeds2c622142007-10-18 03:04:57 -0700317extern void update_vsyscall_tz(void);
john stultzacc9a9d2007-02-16 01:28:17 -0800318#else
Lin Ming0696b712009-11-17 13:49:50 +0800319static inline void
320update_vsyscall(struct timespec *ts, struct clocksource *c, u32 mult)
john stultzacc9a9d2007-02-16 01:28:17 -0800321{
322}
Tony Breeds2c622142007-10-18 03:04:57 -0700323
324static inline void update_vsyscall_tz(void)
325{
326}
john stultzacc9a9d2007-02-16 01:28:17 -0800327#endif
328
Martin Schwidefsky75c51582009-08-14 15:47:30 +0200329extern void timekeeping_notify(struct clocksource *clock);
330
john stultz734efb42006-06-26 00:25:05 -0700331#endif /* _LINUX_CLOCKSOURCE_H */