1 /* linux/include/linux/clocksource.h
3 * This file contains the structure definitions for clocksources.
5 * If you are not a clocksource, or timekeeping code, you should
6 * not be including this file!
8 #ifndef _LINUX_CLOCKSOURCE_H
9 #define _LINUX_CLOCKSOURCE_H
11 #include <linux/types.h>
12 #include <linux/timex.h>
13 #include <linux/time.h>
14 #include <linux/list.h>
15 #include <asm/div64.h>
18 /* clocksource cycle base type */
22 * struct clocksource - hardware abstraction for a free running counter
23 * Provides mostly state-free accessors to the underlying hardware.
25 * @name: ptr to clocksource name
26 * @list: list head for registration
27 * @rating: rating value for selection (higher is better)
28 * To avoid rating inflation the following
29 * list should give you a guide as to how
30 * to assign your clocksource a rating
31 * 1-99: Unfit for real use
32 * Only available for bootup and testing purposes.
33 * 100-199: Base level usability.
34 * Functional for real use, but not desired.
36 * A correct and usable clocksource.
38 * A reasonably fast and accurate clocksource.
40 * The ideal clocksource. A must-use where
42 * @read: returns a cycle value
43 * @mask: bitmask for two's complement
44 * subtraction of non 64 bit counters
45 * @mult: cycle to nanosecond multiplier
46 * @shift: cycle to nanosecond divisor (power of two)
47 * @update_callback: called when safe to alter clocksource values
48 * @is_continuous: defines if clocksource is free-running.
49 * @interval_cycles: Used internally by timekeeping core, please ignore.
50 * @interval_snsecs: Used internally by timekeeping core, please ignore.
54 struct list_head list
;
56 cycle_t (*read
)(void);
60 int (*update_callback
)(void);
63 /* timekeeping specific data, ignore */
64 cycle_t interval_cycles
;
68 /* simplify initialization of mask field */
69 #define CLOCKSOURCE_MASK(bits) (cycle_t)(bits<64 ? ((1ULL<<bits)-1) : -1)
72 * clocksource_khz2mult - calculates mult from khz and shift
73 * @khz: Clocksource frequency in KHz
74 * @shift_constant: Clocksource shift factor
76 * Helper functions that converts a khz counter frequency to a timsource
77 * multiplier, given the clocksource shift value
79 static inline u32
clocksource_khz2mult(u32 khz
, u32 shift_constant
)
81 /* khz = cyc/(Million ns)
82 * mult/2^shift = ns/cyc
83 * mult = ns/cyc * 2^shift
84 * mult = 1Million/khz * 2^shift
85 * mult = 1000000 * 2^shift / khz
86 * mult = (1000000<<shift) / khz
88 u64 tmp
= ((u64
)1000000) << shift_constant
;
90 tmp
+= khz
/2; /* round for do_div */
97 * clocksource_hz2mult - calculates mult from hz and shift
98 * @hz: Clocksource frequency in Hz
99 * @shift_constant: Clocksource shift factor
101 * Helper functions that converts a hz counter
102 * frequency to a timsource multiplier, given the
103 * clocksource shift value
105 static inline u32
clocksource_hz2mult(u32 hz
, u32 shift_constant
)
107 /* hz = cyc/(Billion ns)
108 * mult/2^shift = ns/cyc
109 * mult = ns/cyc * 2^shift
110 * mult = 1Billion/hz * 2^shift
111 * mult = 1000000000 * 2^shift / hz
112 * mult = (1000000000<<shift) / hz
114 u64 tmp
= ((u64
)1000000000) << shift_constant
;
116 tmp
+= hz
/2; /* round for do_div */
123 * clocksource_read: - Access the clocksource's current cycle value
124 * @cs: pointer to clocksource being read
126 * Uses the clocksource to return the current cycle_t value
128 static inline cycle_t
clocksource_read(struct clocksource
*cs
)
134 * cyc2ns - converts clocksource cycles to nanoseconds
135 * @cs: Pointer to clocksource
138 * Uses the clocksource and ntp ajdustment to convert cycle_ts to nanoseconds.
140 * XXX - This could use some mult_lxl_ll() asm optimization
142 static inline s64
cyc2ns(struct clocksource
*cs
, cycle_t cycles
)
144 u64 ret
= (u64
)cycles
;
145 ret
= (ret
* cs
->mult
) >> cs
->shift
;
150 * clocksource_calculate_interval - Calculates a clocksource interval struct
152 * @c: Pointer to clocksource.
153 * @length_nsec: Desired interval length in nanoseconds.
155 * Calculates a fixed cycle/nsec interval for a given clocksource/adjustment
156 * pair and interval request.
158 * Unless you're the timekeeping code, you should not be using this!
160 static inline void clocksource_calculate_interval(struct clocksource
*c
,
161 unsigned long length_nsec
)
165 /* XXX - All of this could use a whole lot of optimization */
169 do_div(tmp
, c
->mult
);
171 c
->interval_cycles
= (cycle_t
)tmp
;
172 if(c
->interval_cycles
== 0)
173 c
->interval_cycles
= 1;
175 c
->interval_snsecs
= (u64
)c
->interval_cycles
* c
->mult
;
180 * error_aproximation - calculates an error adjustment for a given error
182 * @error: Error value (unsigned)
183 * @unit: Adjustment unit
185 * For a given error value, this function takes the adjustment unit
186 * and uses binary approximation to return a power of two adjustment value.
188 * This function is only for use by the the make_ntp_adj() function
189 * and you must hold a write on the xtime_lock when calling.
191 static inline int error_aproximation(u64 error
, u64 unit
)
193 static int saved_adj
= 0;
194 u64 adjusted_unit
= unit
<< saved_adj
;
196 if (error
> (adjusted_unit
* 2)) {
197 /* large error, so increment the adjustment factor */
199 } else if (error
> adjusted_unit
) {
200 /* just right, don't touch it */
201 } else if (saved_adj
) {
202 /* small error, so drop the adjustment factor */
212 * make_ntp_adj - Adjusts the specified clocksource for a given error
214 * @clock: Pointer to clock to be adjusted
215 * @cycles_delta: Current unacounted cycle delta
216 * @error: Pointer to current error value
218 * Returns clock shifted nanosecond adjustment to be applied against
219 * the accumulated time value (ie: xtime).
221 * If the error value is large enough, this function calulates the
222 * (power of two) adjustment value, and adjusts the clock's mult and
223 * interval_snsecs values accordingly.
225 * However, since there may be some unaccumulated cycles, to avoid
226 * time inconsistencies we must adjust the accumulation value
229 * This is not very intuitive, so the following proof should help:
230 * The basic timeofday algorithm: base + cycle * mult
232 * new_base + cycle * new_mult = old_base + cycle * old_mult
233 * new_base = old_base + cycle * old_mult - cycle * new_mult
234 * new_base = old_base + cycle * (old_mult - new_mult)
235 * new_base - old_base = cycle * (old_mult - new_mult)
236 * base_delta = cycle * (old_mult - new_mult)
237 * base_delta = cycle * (mult_delta)
239 * Where mult_delta is the adjustment value made to mult
242 static inline s64
make_ntp_adj(struct clocksource
*clock
,
243 cycles_t cycles_delta
, s64
* error
)
246 if (*error
> ((s64
)clock
->interval_cycles
+1)/2) {
247 /* calculate adjustment value */
248 int adjustment
= error_aproximation(*error
,
249 clock
->interval_cycles
);
251 clock
->mult
+= 1 << adjustment
;
252 clock
->interval_snsecs
+= clock
->interval_cycles
<< adjustment
;
254 /* adjust the base and error for the adjustment */
255 ret
= -(cycles_delta
<< adjustment
);
256 *error
-= clock
->interval_cycles
<< adjustment
;
257 /* XXX adj error for cycle_delta offset? */
258 } else if ((-(*error
)) > ((s64
)clock
->interval_cycles
+1)/2) {
259 /* calculate adjustment value */
260 int adjustment
= error_aproximation(-(*error
),
261 clock
->interval_cycles
);
263 clock
->mult
-= 1 << adjustment
;
264 clock
->interval_snsecs
-= clock
->interval_cycles
<< adjustment
;
266 /* adjust the base and error for the adjustment */
267 ret
= cycles_delta
<< adjustment
;
268 *error
+= clock
->interval_cycles
<< adjustment
;
269 /* XXX adj error for cycle_delta offset? */
275 /* used to install a new clocksource */
276 int clocksource_register(struct clocksource
*);
277 void clocksource_reselect(void);
278 struct clocksource
* clocksource_get_next(void);
280 #endif /* _LINUX_CLOCKSOURCE_H */