clocksource.h

  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 <linux/clocksource_ids.h>
 21#include <asm/div64.h>
 22#include <asm/io.h>
 23
 24struct clocksource_base;
 25struct clocksource;
 26struct module;
 27
 28#if defined(CONFIG_ARCH_CLOCKSOURCE_DATA) || \
 29    defined(CONFIG_GENERIC_GETTIMEOFDAY)
 30#include <asm/clocksource.h>
 31#endif
 32
 33#include <vdso/clocksource.h>
 34
 35/**
 36 * struct clocksource - hardware abstraction for a free running counter
 37 *	Provides mostly state-free accessors to the underlying hardware.
 38 *	This is the structure used for system time.
 39 *
 40 * @read:		Returns a cycle value, passes clocksource as argument
 41 * @mask:		Bitmask for two's complement
 42 *			subtraction of non 64 bit counters
 43 * @mult:		Cycle to nanosecond multiplier
 44 * @shift:		Cycle to nanosecond divisor (power of two)
 45 * @max_idle_ns:	Maximum idle time permitted by the clocksource (nsecs)
 46 * @maxadj:		Maximum adjustment value to mult (~11%)
 47 * @uncertainty_margin:	Maximum uncertainty in nanoseconds per half second.
 48 *			Zero says to use default WATCHDOG_THRESHOLD.
 49 * @archdata:		Optional arch-specific data
 50 * @max_cycles:		Maximum safe cycle value which won't overflow on
 51 *			multiplication
 52 * @max_raw_delta:	Maximum safe delta value for negative motion detection
 53 * @name:		Pointer to clocksource name
 54 * @list:		List head for registration (internal)
 55 * @freq_khz:		Clocksource frequency in khz.
 56 * @rating:		Rating value for selection (higher is better)
 57 *			To avoid rating inflation the following
 58 *			list should give you a guide as to how
 59 *			to assign your clocksource a rating
 60 *			1-99: Unfit for real use
 61 *				Only available for bootup and testing purposes.
 62 *			100-199: Base level usability.
 63 *				Functional for real use, but not desired.
 64 *			200-299: Good.
 65 *				A correct and usable clocksource.
 66 *			300-399: Desired.
 67 *				A reasonably fast and accurate clocksource.
 68 *			400-499: Perfect
 69 *				The ideal clocksource. A must-use where
 70 *				available.
 71 * @id:			Defaults to CSID_GENERIC. The id value is captured
 72 *			in certain snapshot functions to allow callers to
 73 *			validate the clocksource from which the snapshot was
 74 *			taken.
 75 * @flags:		Flags describing special properties
 76 * @base:		Hardware abstraction for clock on which a clocksource
 77 *			is based
 78 * @enable:		Optional function to enable the clocksource
 79 * @disable:		Optional function to disable the clocksource
 80 * @suspend:		Optional suspend function for the clocksource
 81 * @resume:		Optional resume function for the clocksource
 82 * @mark_unstable:	Optional function to inform the clocksource driver that
 83 *			the watchdog marked the clocksource unstable
 84 * @tick_stable:        Optional function called periodically from the watchdog
 85 *			code to provide stable synchronization points
 86 * @wd_list:		List head to enqueue into the watchdog list (internal)
 87 * @cs_last:		Last clocksource value for clocksource watchdog
 88 * @wd_last:		Last watchdog value corresponding to @cs_last
 89 * @owner:		Module reference, must be set by clocksource in modules
 90 *
 91 * Note: This struct is not used in hotpathes of the timekeeping code
 92 * because the timekeeper caches the hot path fields in its own data
 93 * structure, so no cache line alignment is required,
 94 *
 95 * The pointer to the clocksource itself is handed to the read
 96 * callback. If you need extra information there you can wrap struct
 97 * clocksource into your own struct. Depending on the amount of
 98 * information you need you should consider to cache line align that
 99 * structure.
100 */
101struct clocksource {
102	u64			(*read)(struct clocksource *cs);
103	u64			mask;
104	u32			mult;
105	u32			shift;
106	u64			max_idle_ns;
107	u32			maxadj;
108	u32			uncertainty_margin;
109#ifdef CONFIG_ARCH_CLOCKSOURCE_DATA
110	struct arch_clocksource_data archdata;
111#endif
112	u64			max_cycles;
113	u64			max_raw_delta;
114	const char		*name;
115	struct list_head	list;
116	u32			freq_khz;
117	int			rating;
118	enum clocksource_ids	id;
119	enum vdso_clock_mode	vdso_clock_mode;
120	unsigned long		flags;
121	struct clocksource_base *base;
122
123	int			(*enable)(struct clocksource *cs);
124	void			(*disable)(struct clocksource *cs);
125	void			(*suspend)(struct clocksource *cs);
126	void			(*resume)(struct clocksource *cs);
127	void			(*mark_unstable)(struct clocksource *cs);
128	void			(*tick_stable)(struct clocksource *cs);
129
130	/* private: */
131#ifdef CONFIG_CLOCKSOURCE_WATCHDOG
132	/* Watchdog related data, used by the framework */
133	struct list_head	wd_list;
134	u64			cs_last;
135	u64			wd_last;
136#endif
137	struct module		*owner;
138};
139
140/*
141 * Clock source flags bits::
142 */
143#define CLOCK_SOURCE_IS_CONTINUOUS		0x01
144#define CLOCK_SOURCE_MUST_VERIFY		0x02
145
146#define CLOCK_SOURCE_WATCHDOG			0x10
147#define CLOCK_SOURCE_VALID_FOR_HRES		0x20
148#define CLOCK_SOURCE_UNSTABLE			0x40
149#define CLOCK_SOURCE_SUSPEND_NONSTOP		0x80
150#define CLOCK_SOURCE_RESELECT			0x100
151#define CLOCK_SOURCE_VERIFY_PERCPU		0x200
152/* simplify initialization of mask field */
153#define CLOCKSOURCE_MASK(bits) GENMASK_ULL((bits) - 1, 0)
154
155static inline u32 clocksource_freq2mult(u32 freq, u32 shift_constant, u64 from)
156{
157	/*  freq = cyc/from
158	 *  mult/2^shift  = ns/cyc
159	 *  mult = ns/cyc * 2^shift
160	 *  mult = from/freq * 2^shift
161	 *  mult = from * 2^shift / freq
162	 *  mult = (from<<shift) / freq
163	 */
164	u64 tmp = ((u64)from) << shift_constant;
165
166	tmp += freq/2; /* round for do_div */
167	do_div(tmp, freq);
168
169	return (u32)tmp;
170}
171
172/**
173 * clocksource_khz2mult - calculates mult from khz and shift
174 * @khz:		Clocksource frequency in KHz
175 * @shift_constant:	Clocksource shift factor
176 *
177 * Helper functions that converts a khz counter frequency to a timsource
178 * multiplier, given the clocksource shift value
179 */
180static inline u32 clocksource_khz2mult(u32 khz, u32 shift_constant)
181{
182	return clocksource_freq2mult(khz, shift_constant, NSEC_PER_MSEC);
183}
184
185/**
186 * clocksource_hz2mult - calculates mult from hz and shift
187 * @hz:			Clocksource frequency in Hz
188 * @shift_constant:	Clocksource shift factor
189 *
190 * Helper functions that converts a hz counter
191 * frequency to a timsource multiplier, given the
192 * clocksource shift value
193 */
194static inline u32 clocksource_hz2mult(u32 hz, u32 shift_constant)
195{
196	return clocksource_freq2mult(hz, shift_constant, NSEC_PER_SEC);
197}
198
199/**
200 * clocksource_cyc2ns - converts clocksource cycles to nanoseconds
201 * @cycles:	cycles
202 * @mult:	cycle to nanosecond multiplier
203 * @shift:	cycle to nanosecond divisor (power of two)
204 *
205 * Converts clocksource cycles to nanoseconds, using the given @mult and @shift.
206 * The code is optimized for performance and is not intended to work
207 * with absolute clocksource cycles (as those will easily overflow),
208 * but is only intended to be used with relative (delta) clocksource cycles.
209 *
210 * XXX - This could use some mult_lxl_ll() asm optimization
211 */
212static inline s64 clocksource_cyc2ns(u64 cycles, u32 mult, u32 shift)
213{
214	return ((u64) cycles * mult) >> shift;
215}
216
217
218extern int clocksource_unregister(struct clocksource*);
219extern void clocksource_touch_watchdog(void);
220extern void clocksource_suspend(void);
221extern void clocksource_resume(void);
222extern struct clocksource * __init clocksource_default_clock(void);
223extern void clocksource_mark_unstable(struct clocksource *cs);
224extern void
225clocksource_start_suspend_timing(struct clocksource *cs, u64 start_cycles);
226extern u64 clocksource_stop_suspend_timing(struct clocksource *cs, u64 now);
227
228extern u64
229clocks_calc_max_nsecs(u32 mult, u32 shift, u32 maxadj, u64 mask, u64 *max_cycles);
230extern void
231clocks_calc_mult_shift(u32 *mult, u32 *shift, u32 from, u32 to, u32 minsec);
232
233/*
234 * Don't call __clocksource_register_scale directly, use
235 * clocksource_register_hz/khz
236 */
237extern int
238__clocksource_register_scale(struct clocksource *cs, u32 scale, u32 freq);
239extern void
240__clocksource_update_freq_scale(struct clocksource *cs, u32 scale, u32 freq);
241
242/*
243 * Don't call this unless you are a default clocksource
244 * (AKA: jiffies) and absolutely have to.
245 */
246static inline int __clocksource_register(struct clocksource *cs)
247{
248	return __clocksource_register_scale(cs, 1, 0);
249}
250
251static inline int clocksource_register_hz(struct clocksource *cs, u32 hz)
252{
253	return __clocksource_register_scale(cs, 1, hz);
254}
255
256static inline int clocksource_register_khz(struct clocksource *cs, u32 khz)
257{
258	return __clocksource_register_scale(cs, 1000, khz);
259}
260
261static inline void __clocksource_update_freq_hz(struct clocksource *cs, u32 hz)
262{
263	__clocksource_update_freq_scale(cs, 1, hz);
264}
265
266static inline void __clocksource_update_freq_khz(struct clocksource *cs, u32 khz)
267{
268	__clocksource_update_freq_scale(cs, 1000, khz);
269}
270
271#ifdef CONFIG_ARCH_CLOCKSOURCE_INIT
272extern void clocksource_arch_init(struct clocksource *cs);
273#else
274static inline void clocksource_arch_init(struct clocksource *cs) { }
275#endif
276
277extern int timekeeping_notify(struct clocksource *clock);
278
279extern u64 clocksource_mmio_readl_up(struct clocksource *);
280extern u64 clocksource_mmio_readl_down(struct clocksource *);
281extern u64 clocksource_mmio_readw_up(struct clocksource *);
282extern u64 clocksource_mmio_readw_down(struct clocksource *);
283
284extern int clocksource_mmio_init(void __iomem *, const char *,
285	unsigned long, int, unsigned, u64 (*)(struct clocksource *));
286
287extern int clocksource_i8253_init(void);
288
289#define TIMER_OF_DECLARE(name, compat, fn) \
290	OF_DECLARE_1_RET(timer, name, compat, fn)
291
292#ifdef CONFIG_TIMER_PROBE
293extern void timer_probe(void);
294#else
295static inline void timer_probe(void) {}
296#endif
297
298#define TIMER_ACPI_DECLARE(name, table_id, fn)		\
299	ACPI_DECLARE_PROBE_ENTRY(timer, name, table_id, 0, NULL, 0, fn)
300
301static inline unsigned int clocksource_get_max_watchdog_retry(void)
302{
303	/*
304	 * When system is in the boot phase or under heavy workload, there
305	 * can be random big latencies during the clocksource/watchdog
306	 * read, so allow retries to filter the noise latency. As the
307	 * latency's frequency and maximum value goes up with the number of
308	 * CPUs, scale the number of retries with the number of online
309	 * CPUs.
310	 */
311	return (ilog2(num_online_cpus()) / 2) + 1;
312}
313
314void clocksource_verify_percpu(struct clocksource *cs);
315
316/**
317 * struct clocksource_base - hardware abstraction for clock on which a clocksource
318 *			is based
319 * @id:			Defaults to CSID_GENERIC. The id value is used for conversion
320 *			functions which require that the current clocksource is based
321 *			on a clocksource_base with a particular ID in certain snapshot
322 *			functions to allow callers to validate the clocksource from
323 *			which the snapshot was taken.
324 * @freq_khz:		Nominal frequency of the base clock in kHz
325 * @offset:		Offset between the base clock and the clocksource
326 * @numerator:		Numerator of the clock ratio between base clock and the clocksource
327 * @denominator:	Denominator of the clock ratio between base clock and the clocksource
328 */
329struct clocksource_base {
330	enum clocksource_ids	id;
331	u32			freq_khz;
332	u64			offset;
333	u32			numerator;
334	u32			denominator;
335};
336
337#endif /* _LINUX_CLOCKSOURCE_H */